pyrox.dev
1<chapter xmlns="http://docbook.org/ns/docbook"
2 xmlns:xlink="http://www.w3.org/1999/xlink"
3 xmlns:xi="http://www.w3.org/2001/XInclude"
4 version="5.0"
5 xml:id="module-postgresql">
6 <title>PostgreSQL</title>
7<!-- FIXME: render nicely -->
8<!-- FIXME: source can be added automatically -->
9 <para>
10 <emphasis>Source:</emphasis> <filename>modules/services/databases/postgresql.nix</filename>
11 </para>
12 <para>
13 <emphasis>Upstream documentation:</emphasis> <link xlink:href="http://www.postgresql.org/docs/"/>
14 </para>
15<!-- FIXME: more stuff, like maintainer? -->
16 <para>
17 PostgreSQL is an advanced, free relational database.
18<!-- MORE -->
19 </para>
20 <section xml:id="module-services-postgres-configuring">
21 <title>Configuring</title>
22
23 <para>
24 To enable PostgreSQL, add the following to your <filename>configuration.nix</filename>:
25<programlisting>
26<xref linkend="opt-services.postgresql.enable"/> = true;
27<xref linkend="opt-services.postgresql.package"/> = pkgs.postgresql_11;
28</programlisting>
29 Note that you are required to specify the desired version of PostgreSQL (e.g. <literal>pkgs.postgresql_11</literal>). Since upgrading your PostgreSQL version requires a database dump and reload (see below), NixOS cannot provide a default value for <xref linkend="opt-services.postgresql.package"/> such as the most recent release of PostgreSQL.
30 </para>
31
32<!--
33<para>After running <command>nixos-rebuild</command>, you can verify
34whether PostgreSQL works by running <command>psql</command>:
35
36<screen>
37<prompt>$ </prompt>psql
38psql (9.2.9)
39Type "help" for help.
40
41<prompt>alice=></prompt>
42</screen>
43-->
44
45 <para>
46 By default, PostgreSQL stores its databases in <filename>/var/lib/postgresql/$psqlSchema</filename>. You can override this using <xref linkend="opt-services.postgresql.dataDir"/>, e.g.
47<programlisting>
48<xref linkend="opt-services.postgresql.dataDir"/> = "/data/postgresql";
49</programlisting>
50 </para>
51 </section>
52 <section xml:id="module-services-postgres-upgrading">
53 <title>Upgrading</title>
54
55 <note>
56 <para>
57 The steps below demonstrate how to upgrade from an older version to <package>pkgs.postgresql_13</package>.
58 These instructions are also applicable to other versions.
59 </para>
60 </note>
61 <para>
62 Major PostgreSQL upgrades require a downtime and a few imperative steps to be called. This is the case because
63 each major version has some internal changes in the databases' state during major releases. Because of that,
64 NixOS places the state into <filename>/var/lib/postgresql/<version></filename> where each <literal>version</literal>
65 can be obtained like this:
66<programlisting>
67<prompt>$ </prompt>nix-instantiate --eval -A postgresql_13.psqlSchema
68"13"
69</programlisting>
70 For an upgrade, a script like this can be used to simplify the process:
71<programlisting>
72{ config, pkgs, ... }:
73{
74 <xref linkend="opt-environment.systemPackages" /> = [
75 (let
76 # XXX specify the postgresql package you'd like to upgrade to.
77 # Do not forget to list the extensions you need.
78 newPostgres = pkgs.postgresql_13.withPackages (pp: [
79 # pp.plv8
80 ]);
81 in pkgs.writeScriptBin "upgrade-pg-cluster" ''
82 set -eux
83 # XXX it's perhaps advisable to stop all services that depend on postgresql
84 systemctl stop postgresql
85
86 export NEWDATA="/var/lib/postgresql/${newPostgres.psqlSchema}"
87
88 export NEWBIN="${newPostgres}/bin"
89
90 export OLDDATA="${config.<xref linkend="opt-services.postgresql.dataDir"/>}"
91 export OLDBIN="${config.<xref linkend="opt-services.postgresql.package"/>}/bin"
92
93 install -d -m 0700 -o postgres -g postgres "$NEWDATA"
94 cd "$NEWDATA"
95 sudo -u postgres $NEWBIN/initdb -D "$NEWDATA"
96
97 sudo -u postgres $NEWBIN/pg_upgrade \
98 --old-datadir "$OLDDATA" --new-datadir "$NEWDATA" \
99 --old-bindir $OLDBIN --new-bindir $NEWBIN \
100 "$@"
101 '')
102 ];
103}
104</programlisting>
105 </para>
106
107 <para>
108 The upgrade process is:
109 </para>
110
111 <orderedlist>
112 <listitem>
113 <para>
114 Rebuild nixos configuration with the configuration above added to your <filename>configuration.nix</filename>. Alternatively, add that into separate file and reference it in <literal>imports</literal> list.
115 </para>
116 </listitem>
117 <listitem>
118 <para>
119 Login as root (<literal>sudo su -</literal>)
120 </para>
121 </listitem>
122 <listitem>
123 <para>
124 Run <literal>upgrade-pg-cluster</literal>. It will stop old postgresql, initialize a new one and migrate the old one to the new one. You may supply arguments like <literal>--jobs 4</literal> and <literal>--link</literal> to speedup migration process. See <link xlink:href="https://www.postgresql.org/docs/current/pgupgrade.html" /> for details.
125 </para>
126 </listitem>
127 <listitem>
128 <para>
129 Change postgresql package in NixOS configuration to the one you were upgrading to via <xref linkend="opt-services.postgresql.package" />. Rebuild NixOS. This should start new postgres using upgraded data directory and all services you stopped during the upgrade.
130 </para>
131 </listitem>
132 <listitem>
133 <para>
134 After the upgrade it's advisable to analyze the new cluster.
135 </para>
136 <itemizedlist>
137 <listitem>
138 <para>
139 For PostgreSQL ≥ 14, use the <literal>vacuumdb</literal> command printed by the upgrades script.
140 </para>
141 </listitem>
142 <listitem>
143 <para>
144 For PostgreSQL < 14, run (as <literal>su -l postgres</literal> in the <xref linkend="opt-services.postgresql.dataDir" />, in this example <filename>/var/lib/postgresql/13</filename>):
145<programlisting>
146<prompt>$ </prompt>./analyze_new_cluster.sh
147</programlisting>
148 </para>
149 </listitem>
150 </itemizedlist>
151 <para>
152 <warning><para>The next step removes the old state-directory!</para></warning>
153<programlisting>
154<prompt>$ </prompt>./delete_old_cluster.sh
155</programlisting>
156 </para>
157 </listitem>
158 </orderedlist>
159 </section>
160 <section xml:id="module-services-postgres-options">
161 <title>Options</title>
162
163 <para>
164 A complete list of options for the PostgreSQL module may be found <link linkend="opt-services.postgresql.enable">here</link>.
165 </para>
166 </section>
167 <section xml:id="module-services-postgres-plugins">
168 <title>Plugins</title>
169
170 <para>
171 Plugins collection for each PostgreSQL version can be accessed with <literal>.pkgs</literal>. For example, for <literal>pkgs.postgresql_11</literal> package, its plugin collection is accessed by <literal>pkgs.postgresql_11.pkgs</literal>:
172<screen>
173<prompt>$ </prompt>nix repl '<nixpkgs>'
174
175Loading '<nixpkgs>'...
176Added 10574 variables.
177
178<prompt>nix-repl> </prompt>postgresql_11.pkgs.<TAB><TAB>
179postgresql_11.pkgs.cstore_fdw postgresql_11.pkgs.pg_repack
180postgresql_11.pkgs.pg_auto_failover postgresql_11.pkgs.pg_safeupdate
181postgresql_11.pkgs.pg_bigm postgresql_11.pkgs.pg_similarity
182postgresql_11.pkgs.pg_cron postgresql_11.pkgs.pg_topn
183postgresql_11.pkgs.pg_hll postgresql_11.pkgs.pgjwt
184postgresql_11.pkgs.pg_partman postgresql_11.pkgs.pgroonga
185...
186</screen>
187 </para>
188
189 <para>
190 To add plugins via NixOS configuration, set <literal>services.postgresql.extraPlugins</literal>:
191<programlisting>
192<xref linkend="opt-services.postgresql.package"/> = pkgs.postgresql_11;
193<xref linkend="opt-services.postgresql.extraPlugins"/> = with pkgs.postgresql_11.pkgs; [
194 pg_repack
195 postgis
196];
197</programlisting>
198 </para>
199
200 <para>
201 You can build custom PostgreSQL-with-plugins (to be used outside of NixOS) using function <literal>.withPackages</literal>. For example, creating a custom PostgreSQL package in an overlay can look like:
202<programlisting>
203self: super: {
204 postgresql_custom = self.postgresql_11.withPackages (ps: [
205 ps.pg_repack
206 ps.postgis
207 ]);
208}
209</programlisting>
210 </para>
211
212 <para>
213 Here's a recipe on how to override a particular plugin through an overlay:
214<programlisting>
215self: super: {
216 postgresql_11 = super.postgresql_11.override { this = self.postgresql_11; } // {
217 pkgs = super.postgresql_11.pkgs // {
218 pg_repack = super.postgresql_11.pkgs.pg_repack.overrideAttrs (_: {
219 name = "pg_repack-v20181024";
220 src = self.fetchzip {
221 url = "https://github.com/reorg/pg_repack/archive/923fa2f3c709a506e111cc963034bf2fd127aa00.tar.gz";
222 sha256 = "17k6hq9xaax87yz79j773qyigm4fwk8z4zh5cyp6z0sxnwfqxxw5";
223 };
224 });
225 };
226 };
227}
228</programlisting>
229 </para>
230 </section>
231</chapter>