diff options
Diffstat (limited to 'nixos/modules/services/databases/postgresql.xml')
| -rw-r--r-- | nixos/modules/services/databases/postgresql.xml | 345 |
1 files changed, 182 insertions, 163 deletions
diff --git a/nixos/modules/services/databases/postgresql.xml b/nixos/modules/services/databases/postgresql.xml index e48c578e6ce6..2f62d5d80b19 100644 --- a/nixos/modules/services/databases/postgresql.xml +++ b/nixos/modules/services/databases/postgresql.xml @@ -1,181 +1,199 @@ -<chapter xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" - xmlns:xi="http://www.w3.org/2001/XInclude" - version="5.0" - xml:id="module-postgresql"> - <title>PostgreSQL</title> -<!-- FIXME: render nicely --> -<!-- FIXME: source can be added automatically --> - <para> - <emphasis>Source:</emphasis> <filename>modules/services/databases/postgresql.nix</filename> - </para> - <para> - <emphasis>Upstream documentation:</emphasis> <link xlink:href="http://www.postgresql.org/docs/"/> - </para> -<!-- FIXME: more stuff, like maintainer? --> - <para> - PostgreSQL is an advanced, free relational database. -<!-- MORE --> - </para> - <section xml:id="module-services-postgres-configuring"> - <title>Configuring</title> - +<!-- Do not edit this file directly, edit its companion .md instead + and regenerate this file using nixos/doc/manual/md-to-db.sh --> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="module-postgresql"> + <title>PostgreSQL</title> <para> - 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. + <emphasis>Source:</emphasis> + <filename>modules/services/databases/postgresql.nix</filename> </para> - -<!-- -<para>After running <command>nixos-rebuild</command>, you can verify -whether PostgreSQL works by running <command>psql</command>: - -<screen> -<prompt>$ </prompt>psql -psql (9.2.9) -Type "help" for help. - -<prompt>alice=></prompt> -</screen> ---> - <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. -<programlisting> -<xref linkend="opt-services.postgresql.dataDir"/> = "/data/postgresql"; -</programlisting> + <emphasis>Upstream documentation:</emphasis> + <link xlink:href="http://www.postgresql.org/docs/">http://www.postgresql.org/docs/</link> </para> - </section> - <section xml:id="module-services-postgres-upgrading"> - <title>Upgrading</title> - - <note> - <para> - The steps below demonstrate how to upgrade from an older version to <package>pkgs.postgresql_13</package>. - These instructions are also applicable to other versions. - </para> - </note> <para> - Major PostgreSQL upgrades require a downtime and a few imperative steps to be called. This is the case because - each major version has some internal changes in the databases' state during major releases. Because of that, - NixOS places the state into <filename>/var/lib/postgresql/<version></filename> where each <literal>version</literal> - can be obtained like this: -<programlisting> -<prompt>$ </prompt>nix-instantiate --eval -A postgresql_13.psqlSchema -"13" + PostgreSQL is an advanced, free relational database. + </para> + <section xml:id="module-services-postgres-configuring"> + <title>Configuring</title> + <para> + To enable PostgreSQL, add the following to your + <filename>configuration.nix</filename>: + </para> + <programlisting> +services.postgresql.enable = true; +services.postgresql.package = pkgs.postgresql_11; +</programlisting> + <para> + 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> + <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. + </para> + <programlisting> +services.postgresql.dataDir = "/data/postgresql"; </programlisting> - For an upgrade, a script like this can be used to simplify the process: -<programlisting> + </section> + <section xml:id="module-services-postgres-upgrading"> + <title>Upgrading</title> + <note> + <para> + The steps below demonstrate how to upgrade from an older version + to <literal>pkgs.postgresql_13</literal>. These instructions are + also applicable to other versions. + </para> + </note> + <para> + Major PostgreSQL upgrades require a downtime and a few imperative + steps to be called. This is the case because each major version + has some internal changes in the databases’ state during major + releases. Because of that, NixOS places the state into + <filename>/var/lib/postgresql/<version></filename> where + each <literal>version</literal> can be obtained like this: + </para> + <programlisting> +$ nix-instantiate --eval -A postgresql_13.psqlSchema +"13" +</programlisting> + <para> + For an upgrade, a script like this can be used to simplify the + process: + </para> + <programlisting> { config, pkgs, ... }: { - <xref linkend="opt-environment.systemPackages" /> = [ + environment.systemPackages = [ (let # XXX specify the postgresql package you'd like to upgrade to. # Do not forget to list the extensions you need. newPostgres = pkgs.postgresql_13.withPackages (pp: [ # pp.plv8 ]); - in pkgs.writeScriptBin "upgrade-pg-cluster" '' + in pkgs.writeScriptBin "upgrade-pg-cluster" '' set -eux # XXX it's perhaps advisable to stop all services that depend on postgresql systemctl stop postgresql - export NEWDATA="/var/lib/postgresql/${newPostgres.psqlSchema}" + export NEWDATA="/var/lib/postgresql/${newPostgres.psqlSchema}" - export NEWBIN="${newPostgres}/bin" + export NEWBIN="${newPostgres}/bin" - export OLDDATA="${config.<xref linkend="opt-services.postgresql.dataDir"/>}" - export OLDBIN="${config.<xref linkend="opt-services.postgresql.package"/>}/bin" + export OLDDATA="${config.services.postgresql.dataDir}" + export OLDBIN="${config.services.postgresql.package}/bin" - install -d -m 0700 -o postgres -g postgres "$NEWDATA" - cd "$NEWDATA" - sudo -u postgres $NEWBIN/initdb -D "$NEWDATA" + install -d -m 0700 -o postgres -g postgres "$NEWDATA" + cd "$NEWDATA" + sudo -u postgres $NEWBIN/initdb -D "$NEWDATA" sudo -u postgres $NEWBIN/pg_upgrade \ - --old-datadir "$OLDDATA" --new-datadir "$NEWDATA" \ + --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 a new one and migrate the old one to the 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 via <xref linkend="opt-services.postgresql.package" />. Rebuild NixOS. This should start new postgres using upgraded data directory and all services you stopped during the upgrade. + The upgrade process is: </para> - </listitem> - <listitem> + <orderedlist numeration="arabic"> + <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 a new one and migrate the old one to + the 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">https://www.postgresql.org/docs/current/pgupgrade.html</link> + for details. + </para> + </listitem> + <listitem> + <para> + Change postgresql package in NixOS configuration to the one + you were upgrading to via + <xref linkend="opt-services.postgresql.package" />. Rebuild + NixOS. This should start new postgres using upgraded data + directory and all services you stopped during the upgrade. + </para> + </listitem> + <listitem> + <para> + After the upgrade it’s advisable to analyze the new cluster. + </para> + <itemizedlist> + <listitem> + <para> + For PostgreSQL ≥ 14, use the <literal>vacuumdb</literal> + command printed by the upgrades script. + </para> + </listitem> + <listitem> + <para> + For PostgreSQL < 14, run (as + <literal>su -l postgres</literal> in the + <xref linkend="opt-services.postgresql.dataDir" />, in + this example <filename>/var/lib/postgresql/13</filename>): + </para> + <programlisting> +$ ./analyze_new_cluster.sh +</programlisting> + </listitem> + </itemizedlist> + <warning> + <para> + The next step removes the old state-directory! + </para> + </warning> + <programlisting> +$ ./delete_old_cluster.sh +</programlisting> + </listitem> + </orderedlist> + </section> + <section xml:id="module-services-postgres-options"> + <title>Options</title> <para> - After the upgrade it's advisable to analyze the new cluster. + A complete list of options for the PostgreSQL module may be found + <link linkend="opt-services.postgresql.enable">here</link>. </para> - <itemizedlist> - <listitem> - <para> - For PostgreSQL ≥ 14, use the <literal>vacuumdb</literal> command printed by the upgrades script. - </para> - </listitem> - <listitem> - <para> - For PostgreSQL < 14, run (as <literal>su -l postgres</literal> in the <xref linkend="opt-services.postgresql.dataDir" />, in this example <filename>/var/lib/postgresql/13</filename>): -<programlisting> -<prompt>$ </prompt>./analyze_new_cluster.sh -</programlisting> - </para> - </listitem> - </itemizedlist> + </section> + <section xml:id="module-services-postgres-plugins"> + <title>Plugins</title> <para> - <warning><para>The next step removes the old state-directory!</para></warning> -<programlisting> -<prompt>$ </prompt>./delete_old_cluster.sh -</programlisting> + 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>: </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>. - </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>: -<screen> -<prompt>$ </prompt>nix repl '<nixpkgs>' + <programlisting> +$ nix repl '<nixpkgs>' Loading '<nixpkgs>'... Added 10574 variables. -<prompt>nix-repl> </prompt>postgresql_11.pkgs.<TAB><TAB> +nix-repl> postgresql_11.pkgs.<TAB><TAB> postgresql_11.pkgs.cstore_fdw postgresql_11.pkgs.pg_repack postgresql_11.pkgs.pg_auto_failover postgresql_11.pkgs.pg_safeupdate postgresql_11.pkgs.pg_bigm postgresql_11.pkgs.pg_similarity @@ -183,23 +201,25 @@ postgresql_11.pkgs.pg_cron postgresql_11.pkgs.pg_topn postgresql_11.pkgs.pg_hll postgresql_11.pkgs.pgjwt postgresql_11.pkgs.pg_partman postgresql_11.pkgs.pgroonga ... -</screen> - </para> - - <para> - 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; [ +</programlisting> + <para> + To add plugins via NixOS configuration, set + <literal>services.postgresql.extraPlugins</literal>: + </para> + <programlisting> +services.postgresql.package = pkgs.postgresql_11; +services.postgresql.extraPlugins = with pkgs.postgresql_11.pkgs; [ pg_repack postgis ]; </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: -<programlisting> + <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: + </para> + <programlisting> self: super: { postgresql_custom = self.postgresql_11.withPackages (ps: [ ps.pg_repack @@ -207,25 +227,24 @@ self: super: { ]); } </programlisting> - </para> - - <para> - Here's a recipe on how to override a particular plugin through an overlay: -<programlisting> + <para> + Here’s a recipe on how to override a particular plugin through an + overlay: + </para> + <programlisting> self: super: { postgresql_11 = super.postgresql_11.override { this = self.postgresql_11; } // { pkgs = super.postgresql_11.pkgs // { pg_repack = super.postgresql_11.pkgs.pg_repack.overrideAttrs (_: { - name = "pg_repack-v20181024"; + name = "pg_repack-v20181024"; src = self.fetchzip { - url = "https://github.com/reorg/pg_repack/archive/923fa2f3c709a506e111cc963034bf2fd127aa00.tar.gz"; - sha256 = "17k6hq9xaax87yz79j773qyigm4fwk8z4zh5cyp6z0sxnwfqxxw5"; + url = "https://github.com/reorg/pg_repack/archive/923fa2f3c709a506e111cc963034bf2fd127aa00.tar.gz"; + sha256 = "17k6hq9xaax87yz79j773qyigm4fwk8z4zh5cyp6z0sxnwfqxxw5"; }; }); }; }; } </programlisting> - </para> - </section> + </section> </chapter> |