diff options
Diffstat (limited to 'nixos/modules/services/databases/postgresql.xml')
| -rw-r--r-- | nixos/modules/services/databases/postgresql.xml | 250 |
1 files changed, 0 insertions, 250 deletions
diff --git a/nixos/modules/services/databases/postgresql.xml b/nixos/modules/services/databases/postgresql.xml deleted file mode 100644 index 2f62d5d80b19..000000000000 --- a/nixos/modules/services/databases/postgresql.xml +++ /dev/null @@ -1,250 +0,0 @@ -<!-- 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> - <emphasis>Source:</emphasis> - <filename>modules/services/databases/postgresql.nix</filename> - </para> - <para> - <emphasis>Upstream documentation:</emphasis> - <link xlink:href="http://www.postgresql.org/docs/">http://www.postgresql.org/docs/</link> - </para> - <para> - 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> - </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, ... }: -{ - 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" '' - 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 NEWBIN="${newPostgres}/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" - - sudo -u postgres $NEWBIN/pg_upgrade \ - --old-datadir "$OLDDATA" --new-datadir "$NEWDATA" \ - --old-bindir $OLDBIN --new-bindir $NEWBIN \ - "$@" - '') - ]; -} -</programlisting> - <para> - The upgrade process is: - </para> - <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> - 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>: - </para> - <programlisting> -$ nix repl '<nixpkgs>' - -Loading '<nixpkgs>'... -Added 10574 variables. - -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 -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 -... -</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> - 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 - ps.postgis - ]); -} -</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"; - src = self.fetchzip { - url = "https://github.com/reorg/pg_repack/archive/923fa2f3c709a506e111cc963034bf2fd127aa00.tar.gz"; - sha256 = "17k6hq9xaax87yz79j773qyigm4fwk8z4zh5cyp6z0sxnwfqxxw5"; - }; - }); - }; - }; -} -</programlisting> - </section> -</chapter> |