nixos/postgresql: add docs about procedural languages

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"
   ],

nixos/modules/services/databases/postgresql.md

@@ -9,7 +9,7 @@
 
 <!-- FIXME: more stuff, like maintainer? -->
 
-PostgreSQL is an advanced, free relational database.
+PostgreSQL is an advanced, free, relational database.
 <!-- MORE -->
 
 ## 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/&lt;version&gt;` 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 <https://www.postgresql.org/docs/current/pgupgrade.html> 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 <https://www.postgresql.org/docs/current/pgupgrade.html> 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 '<nixpkgs>'
 
@@ -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.