Merge pull request #82739 from danbst/document-postgresql-upgrade

Document postgresql upgrade

1 files changed, 76 insertions, 27 deletions

diff --git a/nixos/modules/services/databases/postgresql.xml b/nixos/modules/services/databases/postgresql.xml
index 72d4a8249a32..07af4c937f03 100644
--- a/nixos/modules/services/databases/postgresql.xml
+++ b/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 '&lt;nixpkgs&gt;'
 
@@ -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; } // {