From 070518ddab2c94afea119f2b1944c05d16792b07 Mon Sep 17 00:00:00 2001 From: Peter Eisentraut Date: Wed, 12 Jun 2013 22:28:24 -0400 Subject: 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 --- doc/src/sgml/auto-explain.sgml | 5 +- doc/src/sgml/config.sgml | 281 ++++++++++++++++++++++++----------------- 2 files changed, 168 insertions(+), 118 deletions(-) (limited to 'doc/src') diff --git a/doc/src/sgml/auto-explain.sgml b/doc/src/sgml/auto-explain.sgml index 03b2309da8f..cd0d6d8727c 100644 --- a/doc/src/sgml/auto-explain.sgml +++ b/doc/src/sgml/auto-explain.sgml @@ -24,7 +24,8 @@ LOAD 'auto_explain'; (You must be superuser to do that.) More typical usage is to preload - it into all sessions by including auto_explain in + it into some or all sessions by including auto_explain in + or in postgresql.conf. Then you can track unexpectedly slow queries no matter when they happen. Of course there is a price in overhead for @@ -185,7 +186,7 @@ LOAD 'auto_explain'; # postgresql.conf -shared_preload_libraries = 'auto_explain' +session_preload_libraries = 'auto_explain' auto_explain.log_min_duration = '3s' diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml index 6a4d15fc84d..23ebc11202f 100644 --- a/doc/src/sgml/config.sgml +++ b/doc/src/sgml/config.sgml @@ -1252,66 +1252,6 @@ include 'filename' - - - shared_preload_libraries (string) - - shared_preload_libraries configuration parameter - - - - This variable specifies one or more shared libraries - to be preloaded at server start. For example, - '$libdir/mylib' would cause - mylib.so (or on some platforms, - mylib.sl) to be preloaded from the installation's - standard library directory. - All library names are converted to lower case unless double-quoted. - If more than one library is to be loaded, separate their names - with commas. This parameter can only be set at server start. - - - - PostgreSQL procedural language - libraries can be preloaded in this way, typically by using the - syntax '$libdir/plXXX' where - XXX is pgsql, perl, - tcl, or python. - - - - By preloading a shared library, the library startup time is avoided - when the library is first used. However, the time to start each new - server process might increase slightly, even if that process never - uses the library. So this parameter is recommended only for - libraries that will be used in most sessions. - - - - - On Windows hosts, preloading a library at server start will not reduce - the time required to start each new server process; each server process - will re-load all preload libraries. However, shared_preload_libraries - is still useful on Windows hosts because some shared libraries may - need to perform certain operations that only take place at postmaster start - (for example, a shared library may need to reserve lightweight locks - or shared memory and you can't do that after the postmaster has started). - - - - If a specified library is not found, - the server will fail to start. - - - - Every PostgreSQL-supported library has a magic - block that is checked to guarantee compatibility. - For this reason, non-PostgreSQL libraries cannot be - loaded in this way. - - - - @@ -5514,6 +5454,171 @@ SET XML OPTION { DOCUMENT | CONTENT }; + + + Shared Library Preloading + + + Several settings are available for preloading shared libraries into the + server, in order to load additional functionality or achieve performance + benefits. For example, a setting of + '$libdir/mylib' would cause + mylib.so (or on some platforms, + mylib.sl) to be preloaded from the installation's standard + library directory. The differences between the settings are when they + take effect and what privileges are required to change them. + + + + PostgreSQL procedural language libraries can + be preloaded in this way, typically by using the + syntax '$libdir/plXXX' where + XXX is pgsql, perl, + tcl, or python. + + + + For each parameter, if more than one library is to be loaded, separate + their names with commas. All library names are converted to lower case + unless double-quoted. + + + + Only shared libraries specifically intended to be used with PostgreSQL + can be loaded this way. Every PostgreSQL-supported library has + a magic block that is checked to guarantee compatibility. For + this reason, non-PostgreSQL libraries cannot be loaded in this way. You + might be able to use operating-system facilities such + as LD_PRELOAD for that. + + + + In general, refer to the documentation of a specific module for the + recommended way to load that module. + + + + + local_preload_libraries (string) + + local_preload_libraries configuration parameter + + + $libdir/plugins + + + + This variable specifies one or more shared libraries that are to be + preloaded at connection start. This parameter cannot be changed after + the start of a particular session. If a specified library is not + found, the connection attempt will fail. + + + + This option can be set by any user. Because of that, the libraries + that can be loaded are restricted to those appearing in the + plugins subdirectory of the installation's + standard library directory. (It is the database administrator's + responsibility to ensure that only safe libraries + are installed there.) Entries in local_preload_libraries + can specify this directory explicitly, for example + $libdir/plugins/mylib, or just specify + the library name — mylib would have + the same effect as $libdir/plugins/mylib. + + + + Unless a module is specifically designed to be used in this way by + non-superusers, this is usually not the right setting to use. Look + at instead. + + + + + + + session_preload_libraries (string) + + session_preload_libraries configuration parameter + + + + This variable specifies one or more shared libraries that are to be + preloaded at connection start. Only superusers can change this setting. + The parameter value only takes effect at the start of the connection. + Subsequent changes have no effect. If a specified library is not + found, the connection attempt will fail. + + + + The intent of this feature is to allow debugging or + performance-measurement libraries to be loaded into specific sessions + without an explicit + LOAD command being given. For + example, could be enabled for all + sessions under a given user name by setting this parameter + with ALTER ROLE SET. Also, this parameter can be changed + without restarting the server (but changes only take effect when a new + session is started), so it is easier to add new modules this way, even + if they should apply to all sessions. + + + + Unlike , there is no large + performance advantage to loading a library at session start rather than + when it is first used. There is some advantage, however, when + connection pooling is used. + + + + + + shared_preload_libraries (string) + + shared_preload_libraries configuration parameter + + + + This variable specifies one or more shared libraries to be preloaded at + server start. with commas. This parameter can only be set at server + start. If a specified library is not found, the server will fail to + start. + + + + Some libraries need to perform certain operations that can only take + place at postmaster start, such as allocating shared memory, reserving + light-weight locks, or starting background workers. Those libraries + must be loaded at server start through this parameter. See the + documentation of each library for details. + + + + Other libraries can also be preloaded. By preloading a shared library, + the library startup time is avoided when the library is first used. + However, the time to start each new server process might increase + slightly, even if that process never uses the library. So this + parameter is recommended only for libraries that will be used in most + sessions. Also, changing this parameter requires a server restart, so + this is not the right setting to use for short-term debugging tasks, + say. Use for that + instead. + + + + + On Windows hosts, preloading a library at server start will not reduce + the time required to start each new server process; each server process + will re-load all preload libraries. However, shared_preload_libraries + is still useful on Windows hosts for libraries that need to + perform operations at postmaster start time.. + + + + + + + Other Defaults @@ -5585,62 +5690,6 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir' - - local_preload_libraries (string) - - local_preload_libraries configuration parameter - - - $libdir/plugins - - - - This variable specifies one or more shared libraries that are - to be preloaded at connection start. If more than one library - is to be loaded, separate their names with commas. All library - names are converted to lower case unless double-quoted. - This parameter cannot be changed after the start of a particular - session. - - - - Because this is not a superuser-only option, the libraries - that can be loaded are restricted to those appearing in the - plugins subdirectory of the installation's - standard library directory. (It is the database administrator's - responsibility to ensure that only safe libraries - are installed there.) Entries in local_preload_libraries - can specify this directory explicitly, for example - $libdir/plugins/mylib, or just specify - the library name — mylib would have - the same effect as $libdir/plugins/mylib. - - - - Unlike , there is no - performance advantage to loading a library at session - start rather than when it is first used. Rather, the intent of - this feature is to allow debugging or performance-measurement - libraries to be loaded into specific sessions without an explicit - LOAD command being given. For example, debugging could - be enabled for all sessions under a given user name by setting - this parameter with ALTER ROLE SET. - - - - If a specified library is not found, - the connection attempt will fail. - - - - Every PostgreSQL-supported library has a magic - block that is checked to guarantee compatibility. - For this reason, non-PostgreSQL libraries cannot be - loaded in this way. - - - - -- cgit v1.2.3