# session_preload_libraries

> session_preload_libraries is the PostgreSQL setting that lists shared libraries to preload into each backend.
---

> [!NOTE]
> **Fact — official short description:** “Lists shared libraries to preload into each backend.”

## Identity {#identity}

| Field | Value | Meaning |
| --- | --- | --- |
| Type | `string` | Upstream pg_settings type |
| Context | `superuser` | Settable at runtime by a superuser |
| Unit | — | Raw unit |
| Range | — | Raw limits in the last observed version |
| Enum values | — | — for non-enum types |
| Category | Client Connection Defaults / Shared Library Preloading | Upstream classification |
| Latest boot value | `""` | empty string |
{.fields meta="-"}

## Lifecycle {#lifecycle}

| Fact | Value |
| --- | --- |
| First observed | PG9.4 |
| Present in | PG9.4–19 Beta 3 |
| Removed in | No |
| Introduction commit | [`070518ddab2c`](https://git.postgresql.org/gitweb/?p=postgresql.git;a=commit;h=070518ddab2c94afea119f2b1944c05d16792b07) — Add session_preload_libraries configuration parameter |
| Commit date | 2013-06-12 |
| Discussion | — |

## Default history {#default-history}

| Versions | Raw `boot_val` | Unit | Human value |
| --- | --- | --- | --- |
| PG9.4–19 Beta 3 | `""` | — | empty string |
{.full-width caption="Measured PG9.0–19 Beta 3 boot defaults"}

## How it works {#mechanism}

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.

## Tuning advice {#tuning-advice}

> [!TIP]
> **Advice.** These are workload-specific starting points and must be validated with measurements.

| Workload | Guidance |
| --- | --- |
| 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. |
| OLAP | Use session_preload_libraries for a measured extension or JIT requirement, accounting for backend startup, resident memory, and behavior under connection pooling. |
| Small nodes | 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. |
{.full-width}

## Pigsty {#pigsty}

Values use the fixed 8-vCPU, 32-GiB, 100-GiB SSD fixture and render the current Pigsty templates for PG19 Beta 3; this does not assert current Pigsty support for that historical or beta release.

| Template | Effective value | Versus upstream boot | Source expression |
| --- | --- | --- | --- |
| OLTP | Unmodified | — | — |
| OLAP | Unmodified | — | — |
| CRIT | Unmodified | — | — |
| TINY | Unmodified | — | — |
{.full-width}

> [!CAUTION]
> **Advice — pending human review.** Fact from the current Pigsty template projection: OLTP: PG9.4–19 Beta 3 unmodified; OLAP: PG9.4–19 Beta 3 unmodified; CRIT: PG9.4–19 Beta 3 unmodified; TINY: PG9.4–19 Beta 3 unmodified. No Pigsty-specific rationale is inferred from an absent override.

## Common pitfalls {#common-pitfalls}

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

## Related parameters {#related-parameters}

[`shared_preload_libraries`](/parameters/shared-preload-libraries/) · [`local_preload_libraries`](/parameters/local-preload-libraries/) · [`dynamic_library_path`](/parameters/dynamic-library-path/) · [`jit_provider`](/parameters/jit-provider/) · [`extension_control_path`](/parameters/extension-control-path/)

## References {#references}

- [PostgreSQL 19 Beta 3 — session_preload_libraries](https://www.postgresql.org/docs/19/runtime-config-client.html#GUC-SESSION-PRELOAD-LIBRARIES)
- [PostgreSQL 19 release notes](https://www.postgresql.org/docs/19/release-19.html)
- [Machine-readable GUC export](/data/guc.jsonl)