diff options
Diffstat (limited to 'nixos/modules/services/databases/postgresql.xml')
| -rw-r--r-- | nixos/modules/services/databases/postgresql.xml | 214 |
1 files changed, 214 insertions, 0 deletions
diff --git a/nixos/modules/services/databases/postgresql.xml b/nixos/modules/services/databases/postgresql.xml new file mode 100644 index 00000000000..0ca9f3faed2 --- /dev/null +++ b/nixos/modules/services/databases/postgresql.xml @@ -0,0 +1,214 @@ +<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> + + <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. + </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> + </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" +</programlisting> + For an upgrade, a script like this can be used to simplify the process: +<programlisting> +{ config, pkgs, ... }: +{ + <xref linkend="opt-environment.systemPackages" /> = [ + (pkgs.writeScriptBin "upgrade-pg-cluster" '' + set -eux + # XXX it's perhaps advisable to stop all services that depend on postgresql + systemctl stop postgresql + + # XXX replace `<new version>` with the psqlSchema here + export NEWDATA="/var/lib/postgresql/<new version>" + + # XXX specify the postgresql package you'd like to upgrade to + export NEWBIN="${pkgs.postgresql_13}/bin" + + export OLDDATA="${config.<xref linkend="opt-services.postgresql.dataDir"/>}" + export OLDBIN="${config.<xref linkend="opt-services.postgresql.package"/>}/bin" + + 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-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. + </para> + </listitem> + <listitem> + <para> + After the upgrade it's advisable to analyze the new cluster (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> + <warning><para>The next step removes the old state-directory!</para></warning> +<programlisting> +<prompt>$ </prompt>./delete_old_cluster.sh +</programlisting> + </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>' + +Loading '<nixpkgs>'... +Added 10574 variables. + +<prompt>nix-repl> </prompt>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 +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; [ + 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> +self: super: { + postgresql_custom = self.postgresql_11.withPackages (ps: [ + ps.pg_repack + ps.postgis + ]); +} +</programlisting> + </para> + + <para> + 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; } // { + pkgs = super.postgresql_11.pkgs // { + pg_repack = super.postgresql_11.pkgs.pg_repack.overrideAttrs (_: { + name = "pg_repack-v20181024"; + src = self.fetchzip { + url = "https://github.com/reorg/pg_repack/archive/923fa2f3c709a506e111cc963034bf2fd127aa00.tar.gz"; + sha256 = "17k6hq9xaax87yz79j773qyigm4fwk8z4zh5cyp6z0sxnwfqxxw5"; + }; + }); + }; + }; +} +</programlisting> + </para> + </section> +</chapter> |