{"Entry":{"collection":"guc","key":"session_preload_libraries","name":"session_preload_libraries","aliases":[],"metadata":{"baseline":false,"boot_human":"Not specified","boot_val":null,"category":"Client Connection Defaults / Shared Library Preloading","category_zh":"","changed_in":[],"changes":[{"documentation_changed":false,"fields":{},"from":"9.3","status":"added","to":"9.4"},{"documentation_changed":true,"fields":{},"from":"9.6","status":"changed","to":"10"},{"documentation_changed":true,"fields":{},"from":"14","status":"changed","to":"15"}],"content_hash":"59a8ebce0a02d4a5896f30066b55c3303e65f7460078f2752c737659496b4725","context":"","default_changed_in":[],"default_history":[{"from":"9.4","to":"19","value":"Empty string"}],"editorial":{"advice":{"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."},"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."],"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."],"references":[{"title":"PostgreSQL 19 Beta 4: session_preload_libraries","url":"https://www.postgresql.org/docs/19/runtime-config-client.html#GUC-SESSION-PRELOAD-LIBRARIES"},{"title":"PostgreSQL 19 release notes","url":"https://www.postgresql.org/docs/19/release-19.html"}],"related":["shared_preload_libraries","local_preload_libraries","dynamic_library_path","jit_provider","extension_control_path"],"summary":"session_preload_libraries is the PostgreSQL setting that lists shared libraries to preload into each backend."},"enumvals":[],"first_version":"9.4","group":"Client Connection Defaults","group_slug":"client","imported_at":"2026-09-27T17:57:31.95519+08:00","intro_commit":{"authored_at":"2013-06-12T22:28:24-04:00","discussion":[],"hash":"070518ddab2c94afea119f2b1944c05d16792b07","subject":"Add session_preload_libraries configuration parameter","url":"https://git.postgresql.org/gitweb/?p=postgresql.git;a=commit;h=070518ddab2c94afea119f2b1944c05d16792b07"},"key":"session_preload_libraries","last_version":"20","max_val":"","min_val":"","name":"session_preload_libraries","position":355,"present_in":["9.4","9.5","9.6","10","11","12","13","14","15","16","17","18","19","20"],"short_desc":"This variable specifies one or more shared libraries that are to be preloaded at connection start.","short_desc_zh":"","source_rev":"english-manuals:48ef0691f40262da8a8ae6443935c0c995f94160ba8254bb1812147df9a316eb","unit":"","vartype":"string"}},"Definition":{"Collection":"guc","Key":"session_preload_libraries","SourceDatabase":"center","Version":"18","SourceTable":"guc","SourceKey":"session_preload_libraries","SourceRevision":"english-manuals:48ef0691f40262da8a8ae6443935c0c995f94160ba8254bb1812147df9a316eb","Facts":{"boot_val":"","category":"Client Connection Defaults / Shared Library Preloading","context":"superuser","description":"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.","doc":{"anchor":"GUC-SESSION-PRELOAD-LIBRARIES","file":"runtime-config-client.html","lang":"en","sha256":"6be6cc70f29eca4695dc43b2b2b94c75b7e0eaaa2c00273d7a98488917a7edb7","slug":"18"},"documented":true,"enumvals":null,"extra_desc":null,"lang":"en","max_val":null,"metadata_version":"18","min_val":null,"name":"session_preload_libraries","short_desc":"Lists shared libraries to preload into each backend.","source":"pg-settings-source-snapshot","unit":null,"vartype":"string"},"ManualEvidence":{"doc":{"anchor":"GUC-SESSION-PRELOAD-LIBRARIES","file":"runtime-config-client.html","lang":"en","sha256":"6be6cc70f29eca4695dc43b2b2b94c75b7e0eaaa2c00273d7a98488917a7edb7","slug":"18"}},"MeasuredEvidence":{"metadata_version":"18"}},"Text":{"Collection":"guc","Key":"session_preload_libraries","SourceDatabase":"pgweb","Version":"18","Locale":"zh-Hans","Title":"session_preload_libraries","Summary":"","BodyHTML":"\u003cp\u003e这个变量指定在连接开始时要预加载的一个或多个共享库。它包含一个逗号分隔的库名称列表，其中每个名称的解释方式与\u003ca href=\"/docs/18/sql-load.html\" title=\"LOAD\" rel=\"nofollow\"\u003e\u003ccode\u003eLOAD\u003c/code\u003e\u003c/a\u003e命令相同。条目之间的空格会被忽略；如果需要在名称中包含空格或逗号，请用双引号括起库名称。参数值仅在连接开始时生效。后续更改不会生效。如果指定的库未找到，连接尝试将失败。只有超级用户和具有适当\u003ccode\u003eSET\u003c/code\u003e权限的用户才能更改此设置。\u003c/p\u003e\u003cp\u003e这个特性的意图是允许在特定会话中载入调试用的或者测量性能的库，而不需要显式地给出一个 \u003ccode\u003eLOAD\u003c/code\u003e命令。例如，通过用\u003ccode\u003eALTER ROLE SET\u003c/code\u003e设置这个参数可以为一个给定用户名下的所有会话启用\u003ca href=\"/docs/18/auto-explain.html\" rel=\"nofollow\"\u003eauto_explain\u003c/a\u003e。还有，无需重启服务器就能更改这个参数（但是只有新会话启动时才会生效），这样可以以这种方式更容易地增加新模块，即便它们会应用到所有会话。\u003c/p\u003e\u003cp\u003e和\u003ca href=\"/docs/18/runtime-config-client.html#GUC-SHARED-PRELOAD-LIBRARIES\" rel=\"nofollow\"\u003eshared_preload_libraries\u003c/a\u003e不同，相对于在库被第一次使用时载入它，在会话开始时载入库并没有明显的性能优势。不过，当使用连接池时这样做还是有一些优势。\u003c/p\u003e","SourceRevision":"2026-09-11@29c86d9","ContentHash":"17ae6f4c4f0733778c0df068f9908ef2f58212a4a5cdd071e1c0b5f1b6bcc0a6","Payload":{"carried_from":"","carry_reason":"","doc_html":"\u003cp\u003e这个变量指定在连接开始时要预加载的一个或多个共享库。它包含一个逗号分隔的库名称列表，其中每个名称的解释方式与\u003ca href=\"/docs/18/sql-load.html\" title=\"LOAD\"\u003e\u003ccode class=\"command\"\u003eLOAD\u003c/code\u003e\u003c/a\u003e命令相同。条目之间的空格会被忽略；如果需要在名称中包含空格或逗号，请用双引号括起库名称。参数值仅在连接开始时生效。后续更改不会生效。如果指定的库未找到，连接尝试将失败。只有超级用户和具有适当\u003ccode class=\"literal\"\u003eSET\u003c/code\u003e权限的用户才能更改此设置。\u003c/p\u003e\u003cp\u003e这个特性的意图是允许在特定会话中载入调试用的或者测量性能的库，而不需要显式地给出一个 \u003ccode class=\"command\"\u003eLOAD\u003c/code\u003e命令。例如，通过用\u003ccode class=\"command\"\u003eALTER ROLE SET\u003c/code\u003e设置这个参数可以为一个给定用户名下的所有会话启用\u003ca href=\"/docs/18/auto-explain.html\" title=\"F.3. auto_explain — 记录慢查询的执行计划\"\u003eauto_explain\u003c/a\u003e。还有，无需重启服务器就能更改这个参数（但是只有新会话启动时才会生效），这样可以以这种方式更容易地增加新模块，即便它们会应用到所有会话。\u003c/p\u003e\u003cp\u003e和\u003ca href=\"/docs/18/runtime-config-client.html#GUC-SHARED-PRELOAD-LIBRARIES\"\u003eshared_preload_libraries\u003c/a\u003e不同，相对于在库被第一次使用时载入它，在会话开始时载入库并没有明显的性能优势。不过，当使用连接池时这样做还是有一些优势。\u003c/p\u003e","doc_same_as":""}},"RequestedLocale":"zh-Hans","Fallback":false,"Versions":["10","11","12","13","14","15","16","17","18","19","20","9.4","9.5","9.6"],"Locales":["en","zh-Hans"],"Signatures":null,"Spellings":null,"SQLState":null,"Evidence":null}