Skip to content

Commit 070518d

Browse files
peterepetere
committed
Add session_preload_libraries configuration parameter
This is like shared_preload_libraries except that it takes effect at backend start and can be changed without a full postmaster restart. It is like local_preload_libraries except that it is still only settable by a superuser. This can be a better way to load modules such as auto_explain. Since there are now three preload parameters, regroup the documentation a bit. Put all parameters into one section, explain common functionality only once, update the descriptions to reflect current and future realities. Reviewed-by: Dimitri Fontaine <dimitri@2ndQuadrant.fr>
1 parent f3ab5d4 commit 070518d

File tree

7 files changed

+193
-124
lines changed

7 files changed

+193
-124
lines changed

‎doc/src/sgml/auto-explain.sgml‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,8 @@ LOAD 'auto_explain';
2424
</programlisting>
2525

2626
(You must be superuser to do that.) More typical usage is to preload
27-
it into all sessions by including <literal>auto_explain</> in
27+
it into some or all sessions by including <literal>auto_explain</> in
28+
<xref linkend="guc-session-preload-libraries"> or
2829
<xref linkend="guc-shared-preload-libraries"> in
2930
<filename>postgresql.conf</>. Then you can track unexpectedly slow queries
3031
no matter when they happen. Of course there is a price in overhead for
@@ -185,7 +186,7 @@ LOAD 'auto_explain';
185186

186187
<programlisting>
187188
# postgresql.conf
188-
shared_preload_libraries = 'auto_explain'
189+
session_preload_libraries = 'auto_explain'
189190

190191
auto_explain.log_min_duration = '3s'
191192
</programlisting>

‎doc/src/sgml/config.sgml‎

Lines changed: 165 additions & 116 deletions
Original file line numberDiff line numberDiff line change
@@ -1252,66 +1252,6 @@ include 'filename'
12521252
</para>
12531253
</listitem>
12541254
</varlistentry>
1255-
1256-
<varlistentry id="guc-shared-preload-libraries" xreflabel="shared_preload_libraries">
1257-
<term><varname>shared_preload_libraries</varname> (<type>string</type>)</term>
1258-
<indexterm>
1259-
<primary><varname>shared_preload_libraries</> configuration parameter</primary>
1260-
</indexterm>
1261-
<listitem>
1262-
<para>
1263-
This variable specifies one or more shared libraries
1264-
to be preloaded at server start. For example,
1265-
<literal>'$libdir/mylib'</literal> would cause
1266-
<literal>mylib.so</> (or on some platforms,
1267-
<literal>mylib.sl</>) to be preloaded from the installation's
1268-
standard library directory.
1269-
All library names are converted to lower case unless double-quoted.
1270-
If more than one library is to be loaded, separate their names
1271-
with commas. This parameter can only be set at server start.
1272-
</para>
1273-
1274-
<para>
1275-
<productname>PostgreSQL</productname> procedural language
1276-
libraries can be preloaded in this way, typically by using the
1277-
syntax <literal>'$libdir/plXXX'</literal> where
1278-
<literal>XXX</literal> is <literal>pgsql</>, <literal>perl</>,
1279-
<literal>tcl</>, or <literal>python</>.
1280-
</para>
1281-
1282-
<para>
1283-
By preloading a shared library, the library startup time is avoided
1284-
when the library is first used. However, the time to start each new
1285-
server process might increase slightly, even if that process never
1286-
uses the library. So this parameter is recommended only for
1287-
libraries that will be used in most sessions.
1288-
</para>
1289-
1290-
<note>
1291-
<para>
1292-
On Windows hosts, preloading a library at server start will not reduce
1293-
the time required to start each new server process; each server process
1294-
will re-load all preload libraries. However, <varname>shared_preload_libraries
1295-
</varname> is still useful on Windows hosts because some shared libraries may
1296-
need to perform certain operations that only take place at postmaster start
1297-
(for example, a shared library may need to reserve lightweight locks
1298-
or shared memory and you can't do that after the postmaster has started).
1299-
</para>
1300-
</note>
1301-
<para>
1302-
If a specified library is not found,
1303-
the server will fail to start.
1304-
</para>
1305-
1306-
<para>
1307-
Every PostgreSQL-supported library has a <quote>magic
1308-
block</> that is checked to guarantee compatibility.
1309-
For this reason, non-PostgreSQL libraries cannot be
1310-
loaded in this way.
1311-
</para>
1312-
</listitem>
1313-
</varlistentry>
1314-
13151255
</variablelist>
13161256
</sect2>
13171257

@@ -5514,6 +5454,171 @@ SET XML OPTION { DOCUMENT | CONTENT };
55145454
</variablelist>
55155455

55165456
</sect2>
5457+
5458+
<sect2 id="runtime-config-client-preload">
5459+
<title>Shared Library Preloading</title>
5460+
5461+
<para>
5462+
Several settings are available for preloading shared libraries into the
5463+
server, in order to load additional functionality or achieve performance
5464+
benefits. For example, a setting of
5465+
<literal>'$libdir/mylib'</literal> would cause
5466+
<literal>mylib.so</> (or on some platforms,
5467+
<literal>mylib.sl</>) to be preloaded from the installation's standard
5468+
library directory. The differences between the settings are when they
5469+
take effect and what privileges are required to change them.
5470+
</para>
5471+
5472+
<para>
5473+
<productname>PostgreSQL</productname> procedural language libraries can
5474+
be preloaded in this way, typically by using the
5475+
syntax <literal>'$libdir/plXXX'</literal> where
5476+
<literal>XXX</literal> is <literal>pgsql</>, <literal>perl</>,
5477+
<literal>tcl</>, or <literal>python</>.
5478+
</para>
5479+
5480+
<para>
5481+
For each parameter, if more than one library is to be loaded, separate
5482+
their names with commas. All library names are converted to lower case
5483+
unless double-quoted.
5484+
</para>
5485+
5486+
<para>
5487+
Only shared libraries specifically intended to be used with PostgreSQL
5488+
can be loaded this way. Every PostgreSQL-supported library has
5489+
a <quote>magic block</> that is checked to guarantee compatibility. For
5490+
this reason, non-PostgreSQL libraries cannot be loaded in this way. You
5491+
might be able to use operating-system facilities such
5492+
as <envar>LD_PRELOAD</envar> for that.
5493+
</para>
5494+
5495+
<para>
5496+
In general, refer to the documentation of a specific module for the
5497+
recommended way to load that module.
5498+
</para>
5499+
5500+
<variablelist>
5501+
<varlistentry id="guc-local-preload-libraries" xreflabel="local_preload_libraries">
5502+
<term><varname>local_preload_libraries</varname> (<type>string</type>)</term>
5503+
<indexterm>
5504+
<primary><varname>local_preload_libraries</> configuration parameter</primary>
5505+
</indexterm>
5506+
<indexterm>
5507+
<primary><filename>$libdir/plugins</></primary>
5508+
</indexterm>
5509+
<listitem>
5510+
<para>
5511+
This variable specifies one or more shared libraries that are to be
5512+
preloaded at connection start. This parameter cannot be changed after
5513+
the start of a particular session. If a specified library is not
5514+
found, the connection attempt will fail.
5515+
</para>
5516+
5517+
<para>
5518+
This option can be set by any user. Because of that, the libraries
5519+
that can be loaded are restricted to those appearing in the
5520+
<filename>plugins</> subdirectory of the installation's
5521+
standard library directory. (It is the database administrator's
5522+
responsibility to ensure that only <quote>safe</> libraries
5523+
are installed there.) Entries in <varname>local_preload_libraries</>
5524+
can specify this directory explicitly, for example
5525+
<literal>$libdir/plugins/mylib</literal>, or just specify
5526+
the library name &mdash; <literal>mylib</literal> would have
5527+
the same effect as <literal>$libdir/plugins/mylib</literal>.
5528+
</para>
5529+
5530+
<para>
5531+
Unless a module is specifically designed to be used in this way by
5532+
non-superusers, this is usually not the right setting to use. Look
5533+
at <xref linkend="guc-session-preload-libraries"> instead.
5534+
</para>
5535+
</listitem>
5536+
</varlistentry>
5537+
5538+
5539+
<varlistentry id="guc-session-preload-libraries" xreflabel="session_preload_libraries">
5540+
<term><varname>session_preload_libraries</varname> (<type>string</type>)</term>
5541+
<indexterm>
5542+
<primary><varname>session_preload_libraries</> configuration parameter</primary>
5543+
</indexterm>
5544+
<listitem>
5545+
<para>
5546+
This variable specifies one or more shared libraries that are to be
5547+
preloaded at connection start. Only superusers can change this setting.
5548+
The parameter value only takes effect at the start of the connection.
5549+
Subsequent changes have no effect. If a specified library is not
5550+
found, the connection attempt will fail.
5551+
</para>
5552+
5553+
<para>
5554+
The intent of this feature is to allow debugging or
5555+
performance-measurement libraries to be loaded into specific sessions
5556+
without an explicit
5557+
<command>LOAD</> command being given. For
5558+
example, <xref linkend="auto-explain"> could be enabled for all
5559+
sessions under a given user name by setting this parameter
5560+
with <command>ALTER ROLE SET</>. Also, this parameter can be changed
5561+
without restarting the server (but changes only take effect when a new
5562+
session is started), so it is easier to add new modules this way, even
5563+
if they should apply to all sessions.
5564+
</para>
5565+
5566+
<para>
5567+
Unlike <xref linkend="guc-shared-preload-libraries">, there is no large
5568+
performance advantage to loading a library at session start rather than
5569+
when it is first used. There is some advantage, however, when
5570+
connection pooling is used.
5571+
</para>
5572+
</listitem>
5573+
</varlistentry>
5574+
5575+
<varlistentry id="guc-shared-preload-libraries" xreflabel="shared_preload_libraries">
5576+
<term><varname>shared_preload_libraries</varname> (<type>string</type>)</term>
5577+
<indexterm>
5578+
<primary><varname>shared_preload_libraries</> configuration parameter</primary>
5579+
</indexterm>
5580+
<listitem>
5581+
<para>
5582+
This variable specifies one or more shared libraries to be preloaded at
5583+
server start. with commas. This parameter can only be set at server
5584+
start. If a specified library is not found, the server will fail to
5585+
start.
5586+
</para>
5587+
5588+
<para>
5589+
Some libraries need to perform certain operations that can only take
5590+
place at postmaster start, such as allocating shared memory, reserving
5591+
light-weight locks, or starting background workers. Those libraries
5592+
must be loaded at server start through this parameter. See the
5593+
documentation of each library for details.
5594+
</para>
5595+
5596+
<para>
5597+
Other libraries can also be preloaded. By preloading a shared library,
5598+
the library startup time is avoided when the library is first used.
5599+
However, the time to start each new server process might increase
5600+
slightly, even if that process never uses the library. So this
5601+
parameter is recommended only for libraries that will be used in most
5602+
sessions. Also, changing this parameter requires a server restart, so
5603+
this is not the right setting to use for short-term debugging tasks,
5604+
say. Use <xref linkend="guc-session-preload-libraries"> for that
5605+
instead.
5606+
</para>
5607+
5608+
<note>
5609+
<para>
5610+
On Windows hosts, preloading a library at server start will not reduce
5611+
the time required to start each new server process; each server process
5612+
will re-load all preload libraries. However, <varname>shared_preload_libraries
5613+
</varname> is still useful on Windows hosts for libraries that need to
5614+
perform operations at postmaster start time..
5615+
</para>
5616+
</note>
5617+
</listitem>
5618+
</varlistentry>
5619+
</variablelist>
5620+
</sect2>
5621+
55175622
<sect2 id="runtime-config-client-other">
55185623
<title>Other Defaults</title>
55195624

@@ -5585,62 +5690,6 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
55855690
</listitem>
55865691
</varlistentry>
55875692

5588-
<varlistentry id="guc-local-preload-libraries" xreflabel="local_preload_libraries">
5589-
<term><varname>local_preload_libraries</varname> (<type>string</type>)</term>
5590-
<indexterm>
5591-
<primary><varname>local_preload_libraries</> configuration parameter</primary>
5592-
</indexterm>
5593-
<indexterm>
5594-
<primary><filename>$libdir/plugins</></primary>
5595-
</indexterm>
5596-
<listitem>
5597-
<para>
5598-
This variable specifies one or more shared libraries that are
5599-
to be preloaded at connection start. If more than one library
5600-
is to be loaded, separate their names with commas. All library
5601-
names are converted to lower case unless double-quoted.
5602-
This parameter cannot be changed after the start of a particular
5603-
session.
5604-
</para>
5605-
5606-
<para>
5607-
Because this is not a superuser-only option, the libraries
5608-
that can be loaded are restricted to those appearing in the
5609-
<filename>plugins</> subdirectory of the installation's
5610-
standard library directory. (It is the database administrator's
5611-
responsibility to ensure that only <quote>safe</> libraries
5612-
are installed there.) Entries in <varname>local_preload_libraries</>
5613-
can specify this directory explicitly, for example
5614-
<literal>$libdir/plugins/mylib</literal>, or just specify
5615-
the library name &mdash; <literal>mylib</literal> would have
5616-
the same effect as <literal>$libdir/plugins/mylib</literal>.
5617-
</para>
5618-
5619-
<para>
5620-
Unlike <xref linkend="guc-shared-preload-libraries">, there is no
5621-
performance advantage to loading a library at session
5622-
start rather than when it is first used. Rather, the intent of
5623-
this feature is to allow debugging or performance-measurement
5624-
libraries to be loaded into specific sessions without an explicit
5625-
<command>LOAD</> command being given. For example, debugging could
5626-
be enabled for all sessions under a given user name by setting
5627-
this parameter with <command>ALTER ROLE SET</>.
5628-
</para>
5629-
5630-
<para>
5631-
If a specified library is not found,
5632-
the connection attempt will fail.
5633-
</para>
5634-
5635-
<para>
5636-
Every PostgreSQL-supported library has a <quote>magic
5637-
block</> that is checked to guarantee compatibility.
5638-
For this reason, non-PostgreSQL libraries cannot be
5639-
loaded in this way.
5640-
</para>
5641-
</listitem>
5642-
</varlistentry>
5643-
56445693
</variablelist>
56455694
</sect2>
56465695
</sect1>

‎src/backend/tcop/postgres.c‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3743,7 +3743,7 @@ PostgresMain(int argc, char *argv[],
37433743
* process any libraries that should be preloaded at backend start (this
37443744
* likewise can't be done until GUC settings are complete)
37453745
*/
3746-
process_local_preload_libraries();
3746+
process_session_preload_libraries();
37473747

37483748
/*
37493749
* Send this backend's cancellation info to the frontend.

‎src/backend/utils/init/miscinit.c‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1222,6 +1222,7 @@ ValidatePgVersion(const char *path)
12221222
* GUC variables: lists of library names to be preloaded at postmaster
12231223
* start and at backend start
12241224
*/
1225+
char *session_preload_libraries_string = NULL;
12251226
char *shared_preload_libraries_string = NULL;
12261227
char *local_preload_libraries_string = NULL;
12271228

@@ -1318,8 +1319,11 @@ process_shared_preload_libraries(void)
13181319
* process any libraries that should be preloaded at backend start
13191320
*/
13201321
void
1321-
process_local_preload_libraries(void)
1322+
process_session_preload_libraries(void)
13221323
{
1324+
load_libraries(session_preload_libraries_string,
1325+
"session_preload_libraries",
1326+
false);
13231327
load_libraries(local_preload_libraries_string,
13241328
"local_preload_libraries",
13251329
true);

‎src/backend/utils/misc/guc.c‎

Lines changed: 16 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -591,6 +591,8 @@ const char *const config_group_names[] =
591591
gettext_noop("Client Connection Defaults / Statement Behavior"),
592592
/* CLIENT_CONN_LOCALE */
593593
gettext_noop("Client Connection Defaults / Locale and Formatting"),
594+
/* CLIENT_CONN_PRELOAD */
595+
gettext_noop("Client Connection Defaults / Shared Library Preloading"),
594596
/* CLIENT_CONN_OTHER */
595597
gettext_noop("Client Connection Defaults / Other Defaults"),
596598
/* LOCK_MANAGEMENT */
@@ -2770,7 +2772,18 @@ static struct config_string ConfigureNamesString[] =
27702772
},
27712773

27722774
{
2773-
{"shared_preload_libraries", PGC_POSTMASTER, RESOURCES_KERNEL,
2775+
{"session_preload_libraries", PGC_SUSET, CLIENT_CONN_PRELOAD,
2776+
gettext_noop("Lists shared libraries to preload into each backend."),
2777+
NULL,
2778+
GUC_LIST_INPUT | GUC_LIST_QUOTE | GUC_SUPERUSER_ONLY
2779+
},
2780+
&session_preload_libraries_string,
2781+
"",
2782+
NULL, NULL, NULL
2783+
},
2784+
2785+
{
2786+
{"shared_preload_libraries", PGC_POSTMASTER, CLIENT_CONN_PRELOAD,
27742787
gettext_noop("Lists shared libraries to preload into server."),
27752788
NULL,
27762789
GUC_LIST_INPUT | GUC_LIST_QUOTE | GUC_SUPERUSER_ONLY
@@ -2781,8 +2794,8 @@ static struct config_string ConfigureNamesString[] =
27812794
},
27822795

27832796
{
2784-
{"local_preload_libraries", PGC_BACKEND, CLIENT_CONN_OTHER,
2785-
gettext_noop("Lists shared libraries to preload into each backend."),
2797+
{"local_preload_libraries", PGC_BACKEND, CLIENT_CONN_PRELOAD,
2798+
gettext_noop("Lists unprivileged shared libraries to preload into each backend."),
27862799
NULL,
27872800
GUC_LIST_INPUT | GUC_LIST_QUOTE
27882801
},

0 commit comments

Comments
 (0)