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 <para>
56 Major PostgreSQL upgrade requires PostgreSQL downtime and a few imperative steps to be called. To simplify this process, use the following NixOS module:
57<programlisting>
58 containers.temp-pg.config.services.postgresql = {
59 enable = true;
60 package = pkgs.postgresql_12;
61 ## set a custom new dataDir
62 # dataDir = "/some/data/dir";
63 };
64 environment.systemPackages =
65 let newpg = config.containers.temp-pg.config.services.postgresql;
66 in [
67 (pkgs.writeScriptBin "upgrade-pg-cluster" ''
68 set -x
69 export OLDDATA="${config.services.postgresql.dataDir}"
70 export NEWDATA="${newpg.dataDir}"
71 export OLDBIN="${config.services.postgresql.package}/bin"
72 export NEWBIN="${newpg.package}/bin"
73
74 install -d -m 0700 -o postgres -g postgres "$NEWDATA"
75 cd "$NEWDATA"
76 sudo -u postgres $NEWBIN/initdb -D "$NEWDATA"
77
78 systemctl stop postgresql # old one
79
80 sudo -u postgres $NEWBIN/pg_upgrade \
81 --old-datadir "$OLDDATA" --new-datadir "$NEWDATA" \
82 --old-bindir $OLDBIN --new-bindir $NEWBIN \
83 "$@"
84 '')
85 ];
86</programlisting>
87 </para>
88
89 <para>
90 The upgrade process is:
91 </para>
92
93 <orderedlist>
94 <listitem>
95 <para>
96 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.
97 </para>
98 </listitem>
99 <listitem>
100 <para>
101 Login as root (<literal>sudo su -</literal>)
102 </para>
103 </listitem>
104 <listitem>
105 <para>
106 Run <literal>upgrade-pg-cluster</literal>. It will stop old postgresql, initialize new one and migrate old one to 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.
107 </para>
108 </listitem>
109 <listitem>
110 <para>
111 Change postgresql package in NixOS configuration to the one you were upgrading to, and change <literal>dataDir</literal> to the one you have migrated to. Rebuild NixOS. This should start new postgres using upgraded data directory.
112 </para>
113 </listitem>
114 <listitem>
115 <para>
116 After upgrade you may want to <literal>ANALYZE</literal> new db.
117 </para>
118 </listitem>
119 </orderedlist>
120 </section>
121 <section xml:id="module-services-postgres-options">
122 <title>Options</title>
123
124 <para>
125 A complete list of options for the PostgreSQL module may be found <link linkend="opt-services.postgresql.enable">here</link>.
126 </para>
127 </section>
128 <section xml:id="module-services-postgres-plugins">
129 <title>Plugins</title>
130
131 <para>
132 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>:
133<screen>
134<prompt>$ </prompt>nix repl '<nixpkgs>'
135
136Loading '<nixpkgs>'...
137Added 10574 variables.
138
139<prompt>nix-repl> </prompt>postgresql_11.pkgs.<TAB><TAB>
140postgresql_11.pkgs.cstore_fdw postgresql_11.pkgs.pg_repack
141postgresql_11.pkgs.pg_auto_failover postgresql_11.pkgs.pg_safeupdate
142postgresql_11.pkgs.pg_bigm postgresql_11.pkgs.pg_similarity
143postgresql_11.pkgs.pg_cron postgresql_11.pkgs.pg_topn
144postgresql_11.pkgs.pg_hll postgresql_11.pkgs.pgjwt
145postgresql_11.pkgs.pg_partman postgresql_11.pkgs.pgroonga
146...
147</screen>
148 </para>
149
150 <para>
151 To add plugins via NixOS configuration, set <literal>services.postgresql.extraPlugins</literal>:
152<programlisting>
153<xref linkend="opt-services.postgresql.package"/> = pkgs.postgresql_11;
154<xref linkend="opt-services.postgresql.extraPlugins"/> = with pkgs.postgresql_11.pkgs; [
155 pg_repack
156 postgis
157];
158</programlisting>
159 </para>
160
161 <para>
162 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:
163<programlisting>
164self: super: {
165 postgresql_custom = self.postgresql_11.withPackages (ps: [
166 ps.pg_repack
167 ps.postgis
168 ]);
169}
170</programlisting>
171 </para>
172
173 <para>
174 Here's a recipe on how to override a particular plugin through an overlay:
175<programlisting>
176self: super: {
177 postgresql_11 = super.postgresql_11.override { this = self.postgresql_11; } // {
178 pkgs = super.postgresql_11.pkgs // {
179 pg_repack = super.postgresql_11.pkgs.pg_repack.overrideAttrs (_: {
180 name = "pg_repack-v20181024";
181 src = self.fetchzip {
182 url = "https://github.com/reorg/pg_repack/archive/923fa2f3c709a506e111cc963034bf2fd127aa00.tar.gz";
183 sha256 = "17k6hq9xaax87yz79j773qyigm4fwk8z4zh5cyp6z0sxnwfqxxw5";
184 };
185 });
186 };
187 };
188}
189</programlisting>
190 </para>
191 </section>
192</chapter>