Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Commit070518d

Browse files
committed
Add session_preload_libraries configuration parameter
This is like shared_preload_libraries except that it takes effect atbackend start and can be changed without a full postmaster restart. Itis like local_preload_libraries except that it is still only settable bya superuser. This can be a better way to load modules such asauto_explain.Since there are now three preload parameters, regroup the documentationa bit. Put all parameters into one section, explain commonfunctionality only once, update the descriptions to reflect current andfuture realities.Reviewed-by: Dimitri Fontaine <dimitri@2ndQuadrant.fr>
1 parentf3ab5d4 commit070518d

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("Listsunprivilegedshared libraries to preload into each backend."),
27862799
NULL,
27872800
GUC_LIST_INPUT |GUC_LIST_QUOTE
27882801
},

0 commit comments

Comments
 (0)
[8]ページ先頭
©2009-2025 Movatter.jp