cafkafk/nixpkgs
cafkafk/nixpkgs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 2

doc/postgresql: apply xmlformat

Browse source
This commit is contained in:
danbst 2020-03-16 19:18:23 +02:00
parent 759fd9b0b0
commit a723672c20
1 changed files with 42 additions and 36 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

78
nixos/modules/services/databases/postgresql.xml
View file

@ -7,12 +7,10 @@
<!-- FIXME: render nicely -->
<!-- FIXME: source can be added automatically -->
<para>
<emphasis>Source:</emphasis>
<filename>modules/services/databases/postgresql.nix</filename>
<emphasis>Source:</emphasis> <filename>modules/services/databases/postgresql.nix</filename>
</para>
<para>
<emphasis>Upstream documentation:</emphasis>
<link xlink:href="http://www.postgresql.org/docs/"/>
<emphasis>Upstream documentation:</emphasis> <link xlink:href="http://www.postgresql.org/docs/"/>
</para>
<!-- FIXME: more stuff, like maintainer? -->
<para>
@ -23,18 +21,12 @@
<title>Configuring</title>
<para>
To enable PostgreSQL, add the following to your
<filename>configuration.nix</filename>:
To enable PostgreSQL, add the following to your <filename>configuration.nix</filename>:
<programlisting>
<xref linkend="opt-services.postgresql.enable"/> = true;
<xref linkend="opt-services.postgresql.package"/> = pkgs.postgresql_11;
</programlisting>
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.
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.
</para>
<!--
@ -51,9 +43,7 @@ Type "help" for help.
-->
<para>
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.
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.
<programlisting>
<xref linkend="opt-services.postgresql.dataDir"/> = "/data/postgresql";
</programlisting>
@ -64,7 +54,6 @@ Type "help" for help.
<para>
Major PostgreSQL upgrade requires PostgreSQL downtime and a few imperative steps to be called. To simplify this process, use the following NixOS module:
<programlisting>
containers.temp-pg.config.services.postgresql = {
enable = true;
@ -95,36 +84,52 @@ Type "help" for help.
'')
];
</programlisting>
</para>
</para>
<para>
The upgrade process is:</para>
The upgrade process is:
</para>
<orderedlist>
<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>
<listitem><para>Login as root (<literal>sudo su -</literal>)</para></listitem>
<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>
<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>
<listitem><para>After upgrade you may want to <literal>ANALYZE</literal> new db.</para></listitem>
<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>
<listitem>
<para>
Login as root (<literal>sudo su -</literal>)
</para>
</listitem>
<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>
<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>
<listitem>
<para>
After upgrade you may want to <literal>ANALYZE</literal> new db.
</para>
</listitem>
</orderedlist>
</section>
<section xml:id="module-services-postgres-options">
<title>Options</title>
<para>
A complete list of options for the PostgreSQL module may be found
<link linkend="opt-services.postgresql.enable">here</link>.
A complete list of options for the PostgreSQL module may be found <link linkend="opt-services.postgresql.enable">here</link>.
</para>
</section>
<section xml:id="module-services-postgres-plugins">
<title>Plugins</title>
<para>
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>:
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>:
<screen>
<prompt>$ </prompt>nix repl '&lt;nixpkgs&gt;'
@ -141,8 +146,9 @@ postgresql_11.pkgs.pg_partman postgresql_11.pkgs.pgroonga
...
</screen>
</para>
<para>
To add plugins via NixOS configuration, set <literal>services.postgresql.extraPlugins</literal>:
To add plugins via NixOS configuration, set <literal>services.postgresql.extraPlugins</literal>:
<programlisting>
<xref linkend="opt-services.postgresql.package"/> = pkgs.postgresql_11;
<xref linkend="opt-services.postgresql.extraPlugins"/> = with pkgs.postgresql_11.pkgs; [
@ -151,10 +157,9 @@ postgresql_11.pkgs.pg_partman postgresql_11.pkgs.pgroonga
];
</programlisting>
</para>
<para>
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:
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:
<programlisting>
self: super: {
postgresql_custom = self.postgresql_11.withPackages (ps: [
@ -164,8 +169,9 @@ self: super: {
}
</programlisting>
</para>
<para>
Here's a recipe on how to override a particular plugin through an overlay:
Here's a recipe on how to override a particular plugin through an overlay:
<programlisting>
self: super: {
postgresql_11 = super.postgresql_11.override { this = self.postgresql_11; } // {