shared_preload_libraries

Definition PG 18 manual

This variable specifies one or more shared libraries to be preloaded at server 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. 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 session_preload_libraries for that instead.

How it works

shared_preload_libraries lists shared libraries to preload into server. Libraries load once in the postmaster before shared memory is finalized, enabling hooks and shared state unavailable to later LOAD; one missing library prevents server startup.

shared_preload_libraries is a POSTMASTER-context setting: PostgreSQL reads it during server startup, and a configuration reload or session SET cannot activate a new value.

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

Operational considerations

Expecting a reload or SET to activate shared_preload_libraries, although it requires a controlled server restart.

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 shared_preload_libraries globally without a rollback plan and a client or operational compatibility test.

Workload guidance

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

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

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