docs: update docs for postgresql plugins (#64899)

docs: update docs for postgresql plugins

Co-Authored-By: Mario Rodas <marsam@users.noreply.github.com>
This commit is contained in:
Danylo Hlynskyi 2019-07-21 22:05:41 +03:00 committed by GitHub
parent b647c76929
commit caa0f82bf8
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 80 additions and 33 deletions

View File

@ -6,26 +6,10 @@ let
cfg = config.services.postgresql;
# see description of extraPlugins
postgresqlAndPlugins = pg:
if cfg.extraPlugins == [] then pg
else pkgs.buildEnv {
name = "postgresql-and-plugins-${(builtins.parseDrvName pg.name).version}";
paths = [ pg pg.lib ] ++ cfg.extraPlugins;
# We include /bin to ensure the $out/bin directory is created which is
# needed because we'll be removing files from that directory in postBuild
# below. See #22653
pathsToLink = [ "/" "/bin" ];
buildInputs = [ pkgs.makeWrapper ];
postBuild =
''
rm $out/bin/{pg_config,postgres,pg_ctl}
cp --target-directory=$out/bin ${pg}/bin/{postgres,pg_config,pg_ctl}
wrapProgram $out/bin/postgres --set NIX_PGLIBDIR $out/lib
'';
};
postgresql = postgresqlAndPlugins cfg.package;
postgresql =
if cfg.extraPlugins == []
then cfg.package
else cfg.package.withPackages (_: cfg.extraPlugins);
# The main PostgreSQL configuration file.
configFile = pkgs.writeText "postgresql.conf"
@ -58,7 +42,7 @@ in
package = mkOption {
type = types.package;
example = literalExample "pkgs.postgresql_9_6";
example = literalExample "pkgs.postgresql_11";
description = ''
PostgreSQL package to use.
'';
@ -74,7 +58,7 @@ in
dataDir = mkOption {
type = types.path;
example = "/var/lib/postgresql/9.6";
example = "/var/lib/postgresql/11";
description = ''
Data directory for PostgreSQL.
'';
@ -195,17 +179,11 @@ in
extraPlugins = mkOption {
type = types.listOf types.path;
default = [];
example = literalExample "[ (pkgs.postgis.override { postgresql = pkgs.postgresql_9_4; }) ]";
example = literalExample "with pkgs.postgresql_11.pkgs; [ postgis pg_repack ]";
description = ''
When this list contains elements a new store path is created.
PostgreSQL and the elements are symlinked into it. Then pg_config,
postgres and pg_ctl are copied to make them use the new
$out/lib directory as pkglibdir. This makes it possible to use postgis
without patching the .sql files which reference $libdir/postgis-1.5.
List of PostgreSQL plugins. PostgreSQL version for each plugin should
match version for <literal>services.postgresql.package</literal> value.
'';
# Note: the duplication of executables is about 4MB size.
# So a nicer solution was patching postgresql to allow setting the
# libdir explicitely.
};
extraConfig = mkOption {

View File

@ -27,10 +27,10 @@
<filename>configuration.nix</filename>:
<programlisting>
<xref linkend="opt-services.postgresql.enable"/> = true;
<xref linkend="opt-services.postgresql.package"/> = pkgs.postgresql_9_4;
<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_9_4</literal>). Since upgrading your
(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
@ -74,4 +74,70 @@ Type "help" for help.
<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 '&lt;nixpkgs&gt;'
Loading '&lt;nixpkgs&gt;'...
Added 10574 variables.
<prompt>nix-repl&gt; </prompt>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
...
</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>

View File

@ -151,6 +151,9 @@ let
# below. See #22653
pathsToLink = ["/" "/bin"];
# Note: the duplication of executables is about 4MB size.
# So a nicer solution was patching postgresql to allow setting the
# libdir explicitely.
postBuild = ''
mkdir -p $out/bin
rm $out/bin/{pg_config,postgres,pg_ctl}