depot/third_party/nixpkgs/nixos/modules/services/databases/postgresql.xml

<!-- 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 = &quot;/data/postgresql&quot;;
</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/&lt;version&gt;</filename> where
      each <literal>version</literal> can be obtained like this:
    </para>
    <programlisting>
$ nix-instantiate --eval -A postgresql_13.psqlSchema
&quot;13&quot;
</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 &quot;upgrade-pg-cluster&quot; ''
      set -eux
      # XXX it's perhaps advisable to stop all services that depend on postgresql
      systemctl stop postgresql

      export NEWDATA=&quot;/var/lib/postgresql/${newPostgres.psqlSchema}&quot;

      export NEWBIN=&quot;${newPostgres}/bin&quot;

      export OLDDATA=&quot;${config.services.postgresql.dataDir}&quot;
      export OLDBIN=&quot;${config.services.postgresql.package}/bin&quot;

      install -d -m 0700 -o postgres -g postgres &quot;$NEWDATA&quot;
      cd &quot;$NEWDATA&quot;
      sudo -u postgres $NEWBIN/initdb -D &quot;$NEWDATA&quot;

      sudo -u postgres $NEWBIN/pg_upgrade \
        --old-datadir &quot;$OLDDATA&quot; --new-datadir &quot;$NEWDATA&quot; \
        --old-bindir $OLDBIN --new-bindir $NEWBIN \
        &quot;$@&quot;
    '')
  ];
}
</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 &lt; 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 '&lt;nixpkgs&gt;'

Loading '&lt;nixpkgs&gt;'...
Added 10574 variables.

nix-repl&gt; postgresql_11.pkgs.&lt;TAB&gt;&lt;TAB&gt;
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 = &quot;pg_repack-v20181024&quot;;
        src = self.fetchzip {
          url = &quot;https://github.com/reorg/pg_repack/archive/923fa2f3c709a506e111cc963034bf2fd127aa00.tar.gz&quot;;
          sha256 = &quot;17k6hq9xaax87yz79j773qyigm4fwk8z4zh5cyp6z0sxnwfqxxw5&quot;;
        };
      });
    };
  };
}
</programlisting>
  </section>
</chapter>