local_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.

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.

The intent of this feature is to allow unprivileged users to load debugging or performance-measurement libraries into specific sessions without requiring an explicit LOAD command. To that end, it would be typical to set this parameter using the PGOPTIONS environment variable on the client or by using ALTER ROLE SET.

However, 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 session_preload_libraries instead.

How it works

local_preload_libraries lists unprivileged shared libraries to preload into each backend. Unprivileged users may name only libraries installed in PostgreSQL's plugins subdirectory, making package placement part of the security boundary.

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

Workload guidance

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

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

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