git.iko.soy/typeable/nixpkgs
on master help sign in
docs: update docs for postgresql plugins (#64899)

docs: update docs for postgresql plugins Co-Authored-By: Mario Rodas <marsam@users.noreply.github.com>

commitcaa0f82bf8a0bf7712c9c004be45380ce6e78dd3 authorDanylo Hlynskyi <abcz2.uprola@gmail.com> dateSun 21 Jul 2019, 22:05 (7 years ago) parentb647c76
3 files changed+80−33
nixos/modules/services/databases/postgresql.nix+9−31 nixos/modules/services/databases/postgresql.xml+68−2 pkgs/servers/sql/postgresql/default.nix+3
nixos/modules/services/databases/postgresql.nix+9−31
@@ -6,26 +6,10 @@ let
66
77 cfg = config.services.postgresql;
88
9− # see description of extraPlugins
10− postgresqlAndPlugins = pg:
11− if cfg.extraPlugins == [] then pg
12− else pkgs.buildEnv {
13− name = "postgresql-and-plugins-${(builtins.parseDrvName pg.name).version}";
14− paths = [ pg pg.lib ] ++ cfg.extraPlugins;
15− # We include /bin to ensure the $out/bin directory is created which is
16− # needed because we'll be removing files from that directory in postBuild
17− # below. See #22653
18− pathsToLink = [ "/" "/bin" ];
19− buildInputs = [ pkgs.makeWrapper ];
20− postBuild =
21− ''
22− rm $out/bin/{pg_config,postgres,pg_ctl}
23− cp --target-directory=$out/bin ${pg}/bin/{postgres,pg_config,pg_ctl}
24− wrapProgram $out/bin/postgres --set NIX_PGLIBDIR $out/lib
25− '';
26− };
27−
28− postgresql = postgresqlAndPlugins cfg.package;
9+ postgresql =
10+ if cfg.extraPlugins == []
11+ then cfg.package
12+ else cfg.package.withPackages (_: cfg.extraPlugins);
2913
3014 # The main PostgreSQL configuration file.
3115 configFile = pkgs.writeText "postgresql.conf"
@@ -58,7 +42,7 @@ in
5842
5943 package = mkOption {
6044 type = types.package;
61− example = literalExample "pkgs.postgresql_9_6";
45+ example = literalExample "pkgs.postgresql_11";
6246 description = ''
6347 PostgreSQL package to use.
6448 '';
@@ -74,7 +58,7 @@ in
7458
7559 dataDir = mkOption {
7660 type = types.path;
77− example = "/var/lib/postgresql/9.6";
61+ example = "/var/lib/postgresql/11";
7862 description = ''
7963 Data directory for PostgreSQL.
8064 '';
@@ -195,17 +179,11 @@ in
195179 extraPlugins = mkOption {
196180 type = types.listOf types.path;
197181 default = [];
198− example = literalExample "[ (pkgs.postgis.override { postgresql = pkgs.postgresql_9_4; }) ]";
182+ example = literalExample "with pkgs.postgresql_11.pkgs; [ postgis pg_repack ]";
199183 description = ''
200− When this list contains elements a new store path is created.
201− PostgreSQL and the elements are symlinked into it. Then pg_config,
202− postgres and pg_ctl are copied to make them use the new
203− $out/lib directory as pkglibdir. This makes it possible to use postgis
204− without patching the .sql files which reference $libdir/postgis-1.5.
184+ List of PostgreSQL plugins. PostgreSQL version for each plugin should
185+ match version for <literal>services.postgresql.package</literal> value.
205186 '';
206− # Note: the duplication of executables is about 4MB size.
207− # So a nicer solution was patching postgresql to allow setting the
208− # libdir explicitely.
209187 };
210188
211189 extraConfig = mkOption {
nixos/modules/services/databases/postgresql.xml+68−2
@@ -27,10 +27,10 @@
2727 <filename>configuration.nix</filename>:
2828<programlisting>
2929<xref linkend="opt-services.postgresql.enable"/> = true;
30−<xref linkend="opt-services.postgresql.package"/> = pkgs.postgresql_9_4;
30+<xref linkend="opt-services.postgresql.package"/> = pkgs.postgresql_11;
3131</programlisting>
3232 Note that you are required to specify the desired version of PostgreSQL
33− (e.g. <literal>pkgs.postgresql_9_4</literal>). Since upgrading your
33+ (e.g. <literal>pkgs.postgresql_11</literal>). Since upgrading your
3434 PostgreSQL version requires a database dump and reload (see below), NixOS
3535 cannot provide a default value for
3636 <xref linkend="opt-services.postgresql.package"/> such as the most recent
@@ -74,4 +74,70 @@ Type "help" for help.
7474 <link linkend="opt-services.postgresql.enable">here</link>.
7575 </para>
7676 </section>
77+ <section xml:id="module-services-postgres-plugins">
78+ <title>Plugins</title>
79+
80+ <para>
81+ Plugins collection for each PostgreSQL version can be accessed with
82+ <literal>.pkgs</literal>. For example, for
83+ <literal>pkgs.postgresql_11</literal> package, its plugin collection is
84+ accessed by <literal>pkgs.postgresql_11.pkgs</literal>:
85+<screen>
86+<prompt>$ </prompt>nix repl '&lt;nixpkgs&gt;'
87+
88+Loading '&lt;nixpkgs&gt;'...
89+Added 10574 variables.
90+
91+<prompt>nix-repl&gt; </prompt>postgresql_11.pkgs.&lt;TAB&gt;&lt;TAB&gt;
92+postgresql_11.pkgs.cstore_fdw postgresql_11.pkgs.pg_repack
93+postgresql_11.pkgs.pg_auto_failover postgresql_11.pkgs.pg_safeupdate
94+postgresql_11.pkgs.pg_bigm postgresql_11.pkgs.pg_similarity
95+postgresql_11.pkgs.pg_cron postgresql_11.pkgs.pg_topn
96+postgresql_11.pkgs.pg_hll postgresql_11.pkgs.pgjwt
97+postgresql_11.pkgs.pg_partman postgresql_11.pkgs.pgroonga
98+...
99+</screen>
100+ </para>
101+ <para>
102+ To add plugins via NixOS configuration, set <literal>services.postgresql.extraPlugins</literal>:
103+<programlisting>
104+<xref linkend="opt-services.postgresql.package"/> = pkgs.postgresql_11;
105+<xref linkend="opt-services.postgresql.extraPlugins"/> = with pkgs.postgresql_11.pkgs; [
106+ pg_repack
107+ postgis
108+];
109+</programlisting>
110+ </para>
111+ <para>
112+ You can build custom PostgreSQL-with-plugins (to be used outside of NixOS) using
113+ function <literal>.withPackages</literal>. For example, creating a custom
114+ PostgreSQL package in an overlay can look like:
115+<programlisting>
116+self: super: {
117+ postgresql_custom = self.postgresql_11.withPackages (ps: [
118+ ps.pg_repack
119+ ps.postgis
120+ ]);
121+}
122+</programlisting>
123+ </para>
124+ <para>
125+ Here's a recipe on how to override a particular plugin through an overlay:
126+<programlisting>
127+self: super: {
128+ postgresql_11 = super.postgresql_11.override { this = self.postgresql_11; } // {
129+ pkgs = super.postgresql_11.pkgs // {
130+ pg_repack = super.postgresql_11.pkgs.pg_repack.overrideAttrs (_: {
131+ name = "pg_repack-v20181024";
132+ src = self.fetchzip {
133+ url = "https://github.com/reorg/pg_repack/archive/923fa2f3c709a506e111cc963034bf2fd127aa00.tar.gz";
134+ sha256 = "17k6hq9xaax87yz79j773qyigm4fwk8z4zh5cyp6z0sxnwfqxxw5";
135+ };
136+ });
137+ };
138+ };
139+}
140+</programlisting>
141+ </para>
142+ </section>
77143</chapter>
pkgs/servers/sql/postgresql/default.nix+3
@@ -151,6 +151,9 @@ let
151151 # below. See #22653
152152 pathsToLink = ["/" "/bin"];
153153
154+ # Note: the duplication of executables is about 4MB size.
155+ # So a nicer solution was patching postgresql to allow setting the
156+ # libdir explicitely.
154157 postBuild = ''
155158 mkdir -p $out/bin
156159 rm $out/bin/{pg_config,postgres,pg_ctl}