pyrox.dev
1# PostgreSQL {#module-postgresql}
2
3<!-- FIXME: render nicely -->
4<!-- FIXME: source can be added automatically -->
5
6*Source:* {file}`modules/services/databases/postgresql.nix`
7
8*Upstream documentation:* <http://www.postgresql.org/docs/>
9
10<!-- FIXME: more stuff, like maintainer? -->
11
12PostgreSQL is an advanced, free relational database.
13<!-- MORE -->
14
15## Configuring {#module-services-postgres-configuring}
16
17To enable PostgreSQL, add the following to your {file}`configuration.nix`:
18```
19services.postgresql.enable = true;
20services.postgresql.package = pkgs.postgresql_11;
21```
22Note that you are required to specify the desired version of PostgreSQL (e.g. `pkgs.postgresql_11`). Since upgrading your PostgreSQL version requires a database dump and reload (see below), NixOS cannot provide a default value for [](#opt-services.postgresql.package) such as the most recent release of PostgreSQL.
23
24<!--
25After running {command}`nixos-rebuild`, you can verify
26whether PostgreSQL works by running {command}`psql`:
27
28```ShellSession
29$ psql
30psql (9.2.9)
31Type "help" for help.
32
33alice=>
34```
35-->
36
37By default, PostgreSQL stores its databases in {file}`/var/lib/postgresql/$psqlSchema`. You can override this using [](#opt-services.postgresql.dataDir), e.g.
38```
39services.postgresql.dataDir = "/data/postgresql";
40```
41
42## Upgrading {#module-services-postgres-upgrading}
43
44::: {.note}
45The steps below demonstrate how to upgrade from an older version to `pkgs.postgresql_13`.
46These instructions are also applicable to other versions.
47:::
48
49Major PostgreSQL upgrades require a downtime and a few imperative steps to be called. This is the case because
50each major version has some internal changes in the databases' state during major releases. Because of that,
51NixOS places the state into {file}`/var/lib/postgresql/<version>` where each `version`
52can be obtained like this:
53```
54$ nix-instantiate --eval -A postgresql_13.psqlSchema
55"13"
56```
57For an upgrade, a script like this can be used to simplify the process:
58```
59{ config, pkgs, ... }:
60{
61 environment.systemPackages = [
62 (let
63 # XXX specify the postgresql package you'd like to upgrade to.
64 # Do not forget to list the extensions you need.
65 newPostgres = pkgs.postgresql_13.withPackages (pp: [
66 # pp.plv8
67 ]);
68 in pkgs.writeScriptBin "upgrade-pg-cluster" ''
69 set -eux
70 # XXX it's perhaps advisable to stop all services that depend on postgresql
71 systemctl stop postgresql
72
73 export NEWDATA="/var/lib/postgresql/${newPostgres.psqlSchema}"
74
75 export NEWBIN="${newPostgres}/bin"
76
77 export OLDDATA="${config.services.postgresql.dataDir}"
78 export OLDBIN="${config.services.postgresql.package}/bin"
79
80 install -d -m 0700 -o postgres -g postgres "$NEWDATA"
81 cd "$NEWDATA"
82 sudo -u postgres $NEWBIN/initdb -D "$NEWDATA"
83
84 sudo -u postgres $NEWBIN/pg_upgrade \
85 --old-datadir "$OLDDATA" --new-datadir "$NEWDATA" \
86 --old-bindir $OLDBIN --new-bindir $NEWBIN \
87 "$@"
88 '')
89 ];
90}
91```
92
93The upgrade process is:
94
95 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.
96 2. Login as root (`sudo su -`)
97 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.
98 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.
99 5. After the upgrade it's advisable to analyze the new cluster.
100
101 - For PostgreSQL ≥ 14, use the `vacuumdb` command printed by the upgrades script.
102 - For PostgreSQL < 14, run (as `su -l postgres` in the [](#opt-services.postgresql.dataDir), in this example {file}`/var/lib/postgresql/13`):
103
104 ```
105 $ ./analyze_new_cluster.sh
106 ```
107
108 ::: {.warning}
109 The next step removes the old state-directory!
110 :::
111
112 ```
113 $ ./delete_old_cluster.sh
114 ```
115
116## Options {#module-services-postgres-options}
117
118A complete list of options for the PostgreSQL module may be found [here](#opt-services.postgresql.enable).
119
120## Plugins {#module-services-postgres-plugins}
121
122Plugins collection for each PostgreSQL version can be accessed with `.pkgs`. For example, for `pkgs.postgresql_11` package, its plugin collection is accessed by `pkgs.postgresql_11.pkgs`:
123```ShellSession
124$ nix repl '<nixpkgs>'
125
126Loading '<nixpkgs>'...
127Added 10574 variables.
128
129nix-repl> postgresql_11.pkgs.<TAB><TAB>
130postgresql_11.pkgs.cstore_fdw postgresql_11.pkgs.pg_repack
131postgresql_11.pkgs.pg_auto_failover postgresql_11.pkgs.pg_safeupdate
132postgresql_11.pkgs.pg_bigm postgresql_11.pkgs.pg_similarity
133postgresql_11.pkgs.pg_cron postgresql_11.pkgs.pg_topn
134postgresql_11.pkgs.pg_hll postgresql_11.pkgs.pgjwt
135postgresql_11.pkgs.pg_partman postgresql_11.pkgs.pgroonga
136...
137```
138
139To add plugins via NixOS configuration, set `services.postgresql.extraPlugins`:
140```
141services.postgresql.package = pkgs.postgresql_11;
142services.postgresql.extraPlugins = with pkgs.postgresql_11.pkgs; [
143 pg_repack
144 postgis
145];
146```
147
148You 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:
149```
150self: super: {
151 postgresql_custom = self.postgresql_11.withPackages (ps: [
152 ps.pg_repack
153 ps.postgis
154 ]);
155}
156```
157
158Here's a recipe on how to override a particular plugin through an overlay:
159```
160self: super: {
161 postgresql_11 = super.postgresql_11.override { this = self.postgresql_11; } // {
162 pkgs = super.postgresql_11.pkgs // {
163 pg_repack = super.postgresql_11.pkgs.pg_repack.overrideAttrs (_: {
164 name = "pg_repack-v20181024";
165 src = self.fetchzip {
166 url = "https://github.com/reorg/pg_repack/archive/923fa2f3c709a506e111cc963034bf2fd127aa00.tar.gz";
167 sha256 = "17k6hq9xaax87yz79j773qyigm4fwk8z4zh5cyp6z0sxnwfqxxw5";
168 };
169 });
170 };
171 };
172}
173```
174
175## JIT (Just-In-Time compilation) {#module-services-postgres-jit}
176
177[JIT](https://www.postgresql.org/docs/current/jit-reason.html)-support in the PostgreSQL package
178is disabled by default because of the ~300MiB closure-size increase from the LLVM dependency. It
179can be optionally enabled in PostgreSQL with the following config option:
180
181```nix
182{
183 services.postgresql.enableJIT = true;
184}
185```
186
187This makes sure that the [`jit`](https://www.postgresql.org/docs/current/runtime-config-query.html#GUC-JIT)-setting
188is set to `on` and a PostgreSQL package with JIT enabled is used. Further tweaking of the JIT compiler, e.g. setting a different
189query cost threshold via [`jit_above_cost`](https://www.postgresql.org/docs/current/runtime-config-query.html#GUC-JIT-ABOVE-COST)
190can be done manually via [`services.postgresql.settings`](#opt-services.postgresql.settings).
191
192The attribute-names of JIT-enabled PostgreSQL packages are suffixed with `_jit`, i.e. for each `pkgs.postgresql`
193(and `pkgs.postgresql_<major>`) in `nixpkgs` there's also a `pkgs.postgresql_jit` (and `pkgs.postgresql_<major>_jit`).
194Alternatively, a JIT-enabled variant can be derived from a given `postgresql` package via `postgresql.withJIT`.
195This is also useful if it's not clear which attribute from `nixpkgs` was originally used (e.g. when working with
196[`config.services.postgresql.package`](#opt-services.postgresql.package) or if the package was modified via an
197overlay) since all modifications are propagated to `withJIT`. I.e.
198
199```nix
200with import <nixpkgs> {
201 overlays = [
202 (self: super: {
203 postgresql = super.postgresql.overrideAttrs (_: { pname = "foobar"; });
204 })
205 ];
206};
207postgresql.withJIT.pname
208```
209
210evaluates to `"foobar"`.