session_preload_libraries

Definition PG 18 manual

This variable specifies one or more shared libraries that are to be preloaded at connection start. It contains a comma-separated list of library names, where each name is interpreted as for the LOAD command. Whitespace between entries is ignored; surround a library name with double quotes if you need to include whitespace or commas in the name. 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. Only superusers and users with the appropriate SET privilege can change this setting.

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, auto_explain 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 shared_preload_libraries, 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.

How it works

session_preload_libraries lists shared libraries to preload into each backend. The list is loaded into each new matching backend and may be set only by a superuser or an appropriately privileged role; a missing library rejects the connection.

Although session_preload_libraries is configurable without a server restart, its library list is acted on only when a new backend starts; changing it inside an established connection does not unload or retroactively load modules.

Library discovery and preloading interact with installed binary versions, extension control files, server or backend startup, and the module's own GUCs.

Operational considerations

Changing session_preload_libraries in one session and assuming role defaults, database defaults, or other pooled sessions changed with it.

Naming a missing or ABI-incompatible module and causing connection failure or a server that cannot start.

Treating a search or preload path as harmless even though it defines which native code the server trusts.

Changing session_preload_libraries globally without a rollback plan and a client or operational compatibility test.

Workload guidance

OLAP: Use session_preload_libraries for a measured extension or JIT requirement, accounting for backend startup, resident memory, and behavior under connection pooling.

OLTP: Do not tune session_preload_libraries generically. Load or expose only modules required by a reviewed feature, verify binary compatibility, and rehearse failure recovery before rollout.

SMALL: Keep session_preload_libraries minimal. A missing or incompatible module can reject connections or prevent startup, and every preloaded library consumes scarce address space or memory.