diff options
Diffstat (limited to 'nixpkgs/nixos/modules/services/databases/postgresql.xml')
| -rw-r--r-- | nixpkgs/nixos/modules/services/databases/postgresql.xml | 103 |
1 files changed, 76 insertions, 27 deletions
diff --git a/nixpkgs/nixos/modules/services/databases/postgresql.xml b/nixpkgs/nixos/modules/services/databases/postgresql.xml index 72d4a8249a32..07af4c937f03 100644 --- a/nixpkgs/nixos/modules/services/databases/postgresql.xml +++ b/nixpkgs/nixos/modules/services/databases/postgresql.xml @@ -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> @@ -63,25 +53,83 @@ Type "help" for help. <title>Upgrading</title> <para> - FIXME: document dump/upgrade/load cycle. + 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; + package = pkgs.postgresql_12; + ## set a custom new dataDir + # dataDir = "/some/data/dir"; + }; + environment.systemPackages = + let newpg = config.containers.temp-pg.config.services.postgresql; + in [ + (pkgs.writeScriptBin "upgrade-pg-cluster" '' + set -x + export OLDDATA="${config.services.postgresql.dataDir}" + export NEWDATA="${newpg.dataDir}" + export OLDBIN="${config.services.postgresql.package}/bin" + export NEWBIN="${newpg.package}/bin" + + install -d -m 0700 -o postgres -g postgres "$NEWDATA" + cd "$NEWDATA" + sudo -u postgres $NEWBIN/initdb -D "$NEWDATA" + + systemctl stop postgresql # old one + + sudo -u postgres $NEWBIN/pg_upgrade \ + --old-datadir "$OLDDATA" --new-datadir "$NEWDATA" \ + --old-bindir $OLDBIN --new-bindir $NEWBIN \ + "$@" + '') + ]; +</programlisting> </para> + + <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> + </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 '<nixpkgs>' @@ -98,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; [ @@ -108,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: [ @@ -121,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; } // { |