From e031c5ff6b49c208fccdd701b448da7ae36afd3d Mon Sep 17 00:00:00 2001 From: Maximilian Bosch Date: Tue, 1 Jul 2025 16:29:22 +0200 Subject: [PATCH] nixos/postgresql: add section about pg_config See https://discourse.nixos.org/t/i-cannot-for-the-life-of-me-find-the-package-that-has-pg-config/66244/4 I decided against doing this in its own nixpkgs manual: the line to draw is quite blurry already (e.g. we have documented our package removal policy in here as well) and having to check two manuals for a single subsystem feels pretty annoying to me. The relevant part - where to find pg_config - is written at the top. I decided to give a bit more context about the way our packaging works since I realized a few times now that I don't remember all the details about the problems we had in the past and having to look up individual commit messages for that isn't very productive. --- nixos/doc/manual/redirects.json | 3 +++ .../modules/services/databases/postgresql.md | 22 +++++++++++++++++++ 2 files changed, 25 insertions(+) diff --git a/nixos/doc/manual/redirects.json b/nixos/doc/manual/redirects.json index 922d806b4e16..867e369d79f1 100644 --- a/nixos/doc/manual/redirects.json +++ b/nixos/doc/manual/redirects.json @@ -1320,6 +1320,9 @@ "module-services-postgres-authentication-user-mapping": [ "index.html#module-services-postgres-authentication-user-mapping" ], + "module-services-postgres-pg_config": [ + "index.html#module-services-postgres-pg_config" + ], "module-services-postgres-upgrading": [ "index.html#module-services-postgres-upgrading" ], diff --git a/nixos/modules/services/databases/postgresql.md b/nixos/modules/services/databases/postgresql.md index aa38ebb3a249..58a76e4846b2 100644 --- a/nixos/modules/services/databases/postgresql.md +++ b/nixos/modules/services/databases/postgresql.md @@ -260,6 +260,28 @@ Thus: This leaves a small gap of a couple of weeks after the latest minor release and the end of our support window for the .05 release, in which there could be an emergency release to other major versions of PostgreSQL - but not the oldest major we have in that branch. In that case: If we can't trivially patch the issue, we will mark the package/version as insecure **immediately**. +## `pg_config` {#module-services-postgres-pg_config} + +`pg_config` is not part of the `postgresql`-package itself. +It is available under `postgresql_.pg_config` and `libpq.pg_config`. +Use the `pg_config` from the postgresql package you're using in your build. + +Also, `pg_config` is a shell-script that replicates the behavior of the upstream `pg_config` and ensures at build-time that the output doesn't change. + +This approach is done for the following reasons: + +* By using a shell script, cross compilation of extensions is made easier. + +* The separation allowed a massive reduction of the runtime closure's size. + Any attempts to move `pg_config` into `$dev` resulted in brittle and more complex solutions + (see commits [`0c47767`](https://github.com/NixOS/nixpkgs/commit/0c477676412564bd2d5dadc37cf245fe4259f4d9), [`435f51c`](https://github.com/NixOS/nixpkgs/commit/435f51c37faf74375134dfbd7c5a4560da2a9ea7)). + +* `pg_config` is only needed to build extensions or in some exceptions for building client libraries linking to `libpq.so`. + If such a build works without `pg_config`, this is strictly preferable over adding `pg_config` to the build environment. + + With the current approach it's now explicit that this is needed. + + ## Options {#module-services-postgres-options} A complete list of options for the PostgreSQL module may be found [here](#opt-services.postgresql.enable).