diff --git a/nixos/doc/manual/redirects.json b/nixos/doc/manual/redirects.json index 29f7f9d51996..11c6c5813114 100644 --- a/nixos/doc/manual/redirects.json +++ b/nixos/doc/manual/redirects.json @@ -1253,6 +1253,9 @@ "module-services-postgres-plugins": [ "index.html#module-services-postgres-plugins" ], + "module-services-postgres-pls": [ + "index.html#module-services-postgres-pls" + ], "module-services-postgres-jit": [ "index.html#module-services-postgres-jit" ], diff --git a/nixos/modules/services/databases/postgresql.md b/nixos/modules/services/databases/postgresql.md index f92e0fd19d02..957c5e40a628 100644 --- a/nixos/modules/services/databases/postgresql.md +++ b/nixos/modules/services/databases/postgresql.md @@ -9,7 +9,7 @@ -PostgreSQL is an advanced, free relational database. +PostgreSQL is an advanced, free, relational database. ## Configuring {#module-services-postgres-configuring} @@ -67,7 +67,7 @@ name. This can be done with If the database user name equals the connecting system user name, postgres by default will accept a passwordless connection via unix domain socket. This makes it possible to run many postgres-backed -services without creating any database secrets at all +services without creating any database secrets at all. ### Assigning extra permissions {#module-services-postgres-initializing-extra-permissions} @@ -178,7 +178,7 @@ These instructions are also applicable to other versions. ::: Major PostgreSQL upgrades require a downtime and a few imperative steps to be called. This is the case because -each major version has some internal changes in the databases' state during major releases. Because of that, +each major version has some internal changes in the databases' state. Because of that, NixOS places the state into {file}`/var/lib/postgresql/<version>` where each `version` can be obtained like this: ``` @@ -203,7 +203,6 @@ For an upgrade, a script like this can be used to simplify the process: systemctl stop postgresql export NEWDATA="/var/lib/postgresql/${newPostgres.psqlSchema}" - export NEWBIN="${newPostgres}/bin" export OLDDATA="${cfg.dataDir}" @@ -224,11 +223,11 @@ For an upgrade, a script like this can be used to simplify the process: The upgrade process is: - 1. Rebuild nixos configuration with the configuration above added to your {file}`configuration.nix`. Alternatively, add that into separate file and reference it in `imports` list. - 2. Login as root (`sudo su -`) - 3. Run `upgrade-pg-cluster`. It will stop old postgresql, initialize a new one and migrate the old one to the new one. You may supply arguments like `--jobs 4` and `--link` to speedup migration process. See for details. - 4. Change postgresql package in NixOS configuration to the one you were upgrading to via [](#opt-services.postgresql.package). Rebuild NixOS. This should start new postgres using upgraded data directory and all services you stopped during the upgrade. - 5. After the upgrade it's advisable to analyze the new cluster. + 1. Add the above to your {file}`configuration.nix` and rebuild. Alternatively, add that into a separate file and reference it in the `imports` list. + 2. Login as root (`sudo su -`). + 3. Run `upgrade-pg-cluster`. This will stop the old postgresql cluster, initialize a new one and migrate the old one to the new one. You may supply arguments like `--jobs 4` and `--link` to speedup the migration process. See for details. + 4. Change the postgresql package in NixOS configuration to the one you were upgrading to via [](#opt-services.postgresql.package). Rebuild NixOS. This should start the new postgres version using the upgraded data directory and all services you stopped during the upgrade. + 5. After the upgrade it's advisable to analyze the new cluster: - For PostgreSQL ≥ 14, use the `vacuumdb` command printed by the upgrades script. - For PostgreSQL < 14, run (as `su -l postgres` in the [](#opt-services.postgresql.dataDir), in this example {file}`/var/lib/postgresql/13`): @@ -273,7 +272,7 @@ A complete list of options for the PostgreSQL module may be found [here](#opt-se ## Plugins {#module-services-postgres-plugins} -Plugins collection for each PostgreSQL version can be accessed with `.pkgs`. For example, for `pkgs.postgresql_15` package, its plugin collection is accessed by `pkgs.postgresql_15.pkgs`: +The collection of plugins for each PostgreSQL version can be accessed with `.pkgs`. For example, for the `pkgs.postgresql_15` package, its plugin collection is accessed by `pkgs.postgresql_15.pkgs`: ```ShellSession $ nix repl '' @@ -301,7 +300,7 @@ To add plugins via NixOS configuration, set `services.postgresql.extensions`: } ``` -You can build custom PostgreSQL-with-plugins (to be used outside of NixOS) using function `.withPackages`. For example, creating a custom PostgreSQL package in an overlay can look like: +You can build a custom `postgresql-with-plugins` (to be used outside of NixOS) using the function `.withPackages`. For example, creating a custom PostgreSQL package in an overlay can look like this: ```nix self: super: { postgresql_custom = self.postgresql_17.withPackages (ps: [ @@ -328,10 +327,41 @@ self: super: { } ``` +## Procedural Languages {#module-services-postgres-pls} + +PostgreSQL ships the additional procedural languages PL/Perl, PL/Python and PL/Tcl as extensions. +They are packaged as plugins and can be made available in the same way as external extensions: +```nix +{ + services.postgresql.extensions = ps: with ps; [ + plperl + plpython3 + pltcl + ]; +} +``` + +Each procedural language plugin provides a `.withPackages` helper to make language specific packages available at run-time. + +For example, to make `python3Packages.base58` available: +```nix +{ + services.postgresql.extensions = pgps: with pgps; [ + (plpython3.withPackages (pyps: with pyps; [ base58 ])) + ]; +} +``` + +This currently works for: +- `plperl` by re-using `perl.withPackages` +- `plpython3` by re-using `python3.withPackages` +- `plr` by exposing `rPackages` +- `pltcl` by exposing `tclPackages` + ## JIT (Just-In-Time compilation) {#module-services-postgres-jit} [JIT](https://www.postgresql.org/docs/current/jit-reason.html)-support in the PostgreSQL package -is disabled by default because of the ~300MiB closure-size increase from the LLVM dependency. It +is disabled by default because of the ~600MiB closure-size increase from the LLVM dependency. It can be optionally enabled in PostgreSQL with the following config option: ```nix @@ -384,7 +414,7 @@ several common hardening options from `systemd`, most notably: } ``` -The NixOS module also contains necessary adjustments for extensions from `nixpkgs` +The NixOS module also contains necessary adjustments for extensions from `nixpkgs`, if these are enabled. If an extension or a postgresql feature from `nixpkgs` breaks with hardening, it's considered a bug.