···

       
7
       
 
       
<!-- FIXME: render nicely -->

     

       
8
       
 
       
<!-- FIXME: source can be added automatically -->

     

       
9
       
 
       
 <para>

     

       
10
       
-
       
  <emphasis>Source:</emphasis>

     

       
11
       
-
       
  <filename>modules/services/databases/postgresql.nix</filename>

     

       
12
       
 
       
 </para>

     

       
13
       
 
       
 <para>

     

       
14
       
-
       
  <emphasis>Upstream documentation:</emphasis>

     

       
15
       
-
       
  <link xlink:href="http://www.postgresql.org/docs/"/>

     

       
16
       
 
       
 </para>

     

       
17
       
 
       
<!-- FIXME: more stuff, like maintainer? -->

     

       
18
       
 
       
 <para>

     
···

       
23
       
 
       
  <title>Configuring</title>

     

       
24
       
 
       


     

       
25
       
 
       
  <para>

     

       
26
       
-
       
   To enable PostgreSQL, add the following to your

     

       
27
       
-
       
   <filename>configuration.nix</filename>:

     

       
28
       
 
       
<programlisting>

     

       
29
       
 
       
<xref linkend="opt-services.postgresql.enable"/> = true;

     

       
30
       
 
       
<xref linkend="opt-services.postgresql.package"/> = pkgs.postgresql_11;

     

       
31
       
 
       
</programlisting>

     

       
32
       
-
       
   Note that you are required to specify the desired version of PostgreSQL

     

       
33
       
-
       
   (e.g. <literal>pkgs.postgresql_11</literal>). Since upgrading your

     

       
34
       
-
       
   PostgreSQL version requires a database dump and reload (see below), NixOS

     

       
35
       
-
       
   cannot provide a default value for

     

       
36
       
-
       
   <xref linkend="opt-services.postgresql.package"/> such as the most recent

     

       
37
       
-
       
   release of PostgreSQL.

     

       
38
       
 
       
  </para>

     

       
39
       
 
       


     

       
40
       
 
       
<!--

     
···

       
51
       
 
       
-->

     

       
52
       
 
       


     

       
53
       
 
       
  <para>

     

       
54
       
-
       
   By default, PostgreSQL stores its databases in

     

       
55
       
-
       
   <filename>/var/lib/postgresql/$psqlSchema</filename>. You can override this using

     

       
56
       
-
       
   <xref linkend="opt-services.postgresql.dataDir"/>, e.g.

     

       
57
       
 
       
<programlisting>

     

       
58
       
 
       
<xref linkend="opt-services.postgresql.dataDir"/> = "/data/postgresql";

     

       
59
       
 
       
</programlisting>

     
···

       
64
       
 
       


     

       
65
       
 
       
  <para>

     

       
66
       
 
       
   Major PostgreSQL upgrade requires PostgreSQL downtime and a few imperative steps to be called. To simplify this process, use the following NixOS module:

     

       
67
       
-
       


     

       
68
       
 
       
<programlisting>

     

       
69
       
 
       
  containers.temp-pg.config.services.postgresql = {

     

       
70
       
 
       
    enable = true;

     
···

       
95
       
 
       
      '')

     

       
96
       
 
       
    ];

     

       
97
       
 
       
</programlisting>

     

       
98
       
-
       
    </para>

     

       
0
       
 
       

     

       
99
       
 
       
  <para>

     

       
100
       
-
       
      The upgrade process is:</para>

     

       
0
       
 
       

     

       
101
       
 
       


     

       
102
       
 
       
  <orderedlist>

     

       
103
       
-
       
      <listitem><para>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.</para></listitem>

     

       
104
       
-
       
          <listitem><para>Login as root (<literal>sudo su -</literal>)</para></listitem>

     

       
105
       
-
       
              <listitem><para>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.</para></listitem>

     

       
106
       
-
       
                  <listitem><para>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.</para></listitem>

     

       
107
       
-
       
                      <listitem><para>After upgrade you may want to <literal>ANALYZE</literal> new db.</para></listitem>

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
108
       
 
       
  </orderedlist>

     

       
109
       
-
       
  

     

       
110
       
-
       


     

       
111
       
 
       
 </section>

     

       
112
       
 
       
 <section xml:id="module-services-postgres-options">

     

       
113
       
 
       
  <title>Options</title>

     

       
114
       
 
       


     

       
115
       
 
       
  <para>

     

       
116
       
-
       
   A complete list of options for the PostgreSQL module may be found

     

       
117
       
-
       
   <link linkend="opt-services.postgresql.enable">here</link>.

     

       
118
       
 
       
  </para>

     

       
119
       
 
       
 </section>

     

       
120
       
 
       
 <section xml:id="module-services-postgres-plugins">

     

       
121
       
 
       
  <title>Plugins</title>

     

       
122
       
 
       


     

       
123
       
 
       
  <para>

     

       
124
       
-
       
   Plugins collection for each PostgreSQL version can be accessed with

     

       
125
       
-
       
   <literal>.pkgs</literal>. For example, for

     

       
126
       
-
       
   <literal>pkgs.postgresql_11</literal> package, its plugin collection is

     

       
127
       
-
       
   accessed by <literal>pkgs.postgresql_11.pkgs</literal>:

     

       
128
       
 
       
<screen>

     

       
129
       
 
       
<prompt>$ </prompt>nix repl '&lt;nixpkgs&gt;'

     

       
130
       
 
       


     
···

       
141
       
 
       
...

     

       
142
       
 
       
</screen>

     

       
143
       
 
       
  </para>

     

       
0
       
 
       

     

       
144
       
 
       
  <para>

     

       
145
       
-
       
    To add plugins via NixOS configuration, set <literal>services.postgresql.extraPlugins</literal>:

     

       
146
       
 
       
<programlisting>

     

       
147
       
 
       
<xref linkend="opt-services.postgresql.package"/> = pkgs.postgresql_11;

     

       
148
       
 
       
<xref linkend="opt-services.postgresql.extraPlugins"/> = with pkgs.postgresql_11.pkgs; [

     
···

       
151
       
 
       
];

     

       
152
       
 
       
</programlisting>

     

       
153
       
 
       
  </para>

     

       
0
       
 
       

     

       
154
       
 
       
  <para>

     

       
155
       
-
       
   You can build custom PostgreSQL-with-plugins (to be used outside of NixOS) using

     

       
156
       
-
       
   function <literal>.withPackages</literal>. For example, creating a custom

     

       
157
       
-
       
   PostgreSQL package in an overlay can look like:

     

       
158
       
 
       
<programlisting>

     

       
159
       
 
       
self: super: {

     

       
160
       
 
       
  postgresql_custom = self.postgresql_11.withPackages (ps: [

     
···

       
164
       
 
       
}

     

       
165
       
 
       
</programlisting>

     

       
166
       
 
       
  </para>

     

       
0
       
 
       

     

       
167
       
 
       
  <para>

     

       
168
       
-
       
    Here's a recipe on how to override a particular plugin through an overlay:

     

       
169
       
 
       
<programlisting>

     

       
170
       
 
       
self: super: {

     

       
171
       
 
       
  postgresql_11 = super.postgresql_11.override { this = self.postgresql_11; } // {

     

···

       
7
       
 
       
<!-- FIXME: render nicely -->

     

       
8
       
 
       
<!-- FIXME: source can be added automatically -->

     

       
9
       
 
       
 <para>

     

       
10
       
+
       
  <emphasis>Source:</emphasis> <filename>modules/services/databases/postgresql.nix</filename>

     

       
0
       
 
       

     

       
11
       
 
       
 </para>

     

       
12
       
 
       
 <para>

     

       
13
       
+
       
  <emphasis>Upstream documentation:</emphasis> <link xlink:href="http://www.postgresql.org/docs/"/>

     

       
0
       
 
       

     

       
14
       
 
       
 </para>

     

       
15
       
 
       
<!-- FIXME: more stuff, like maintainer? -->

     

       
16
       
 
       
 <para>

     
···

       
21
       
 
       
  <title>Configuring</title>

     

       
22
       
 
       


     

       
23
       
 
       
  <para>

     

       
24
       
+
       
   To enable PostgreSQL, add the following to your <filename>configuration.nix</filename>:

     

       
0
       
 
       

     

       
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.

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
30
       
 
       
  </para>

     

       
31
       
 
       


     

       
32
       
 
       
<!--

     
···

       
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.

     

       
0
       
 
       

     

       
0
       
 
       

     

       
47
       
 
       
<programlisting>

     

       
48
       
 
       
<xref linkend="opt-services.postgresql.dataDir"/> = "/data/postgresql";

     

       
49
       
 
       
</programlisting>

     
···

       
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:

     

       
0
       
 
       

     

       
57
       
 
       
<programlisting>

     

       
58
       
 
       
  containers.temp-pg.config.services.postgresql = {

     

       
59
       
 
       
    enable = true;

     
···

       
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>

     

       
0
       
 
       

     

       
0
       
 
       

     

       
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>.

     

       
0
       
 
       

     

       
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>:

     

       
0
       
 
       

     

       
0
       
 
       

     

       
0
       
 
       

     

       
133
       
 
       
<screen>

     

       
134
       
 
       
<prompt>$ </prompt>nix repl '&lt;nixpkgs&gt;'

     

       
135
       
 
       


     
···

       
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; [

     
···

       
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:

     

       
0
       
 
       

     

       
0
       
 
       

     

       
163
       
 
       
<programlisting>

     

       
164
       
 
       
self: super: {

     

       
165
       
 
       
  postgresql_custom = self.postgresql_11.withPackages (ps: [

     
···

       
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>

     

       
176
       
 
       
self: super: {

     

       
177
       
 
       
  postgresql_11 = super.postgresql_11.override { this = self.postgresql_11; } // {