{"Entry":{"collection":"guc","key":"local_preload_libraries","name":"local_preload_libraries","aliases":[],"metadata":{"baseline":false,"boot_human":"Not specified","boot_val":null,"category":"Client Connection Defaults / Shared Library Preloading","category_zh":"","changed_in":["9.4","9.5"],"changes":[{"documentation_changed":false,"fields":{},"from":"8.1","status":"added","to":"8.2"},{"documentation_changed":true,"fields":{},"from":"8.4","status":"changed","to":"9.0"},{"documentation_changed":true,"fields":{"category":{"from":"Client Connection Defaults / Other Defaults","to":"Client Connection Defaults / Shared Library Preloading"},"short_desc":{"from":"Lists shared libraries to preload into each backend.","to":"Lists unprivileged shared libraries to preload into each backend."}},"from":"9.3","status":"changed","to":"9.4"},{"documentation_changed":true,"fields":{"context":{"from":"backend","to":"user"}},"from":"9.4","status":"changed","to":"9.5"},{"documentation_changed":true,"fields":{},"from":"9.6","status":"changed","to":"10"}],"content_hash":"63eae2042b9b078bc1283f84a8aecd1ac4a924555840e5667612abb3275ddeb8","context":"","default_changed_in":[],"default_history":[{"from":"9.0","to":"19","value":"Empty string"}],"editorial":{"advice":{"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."},"mechanism":["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."],"pitfalls":["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."],"references":[{"title":"PostgreSQL 19 Beta 4: local_preload_libraries","url":"https://www.postgresql.org/docs/19/runtime-config-client.html#GUC-LOCAL-PRELOAD-LIBRARIES"},{"title":"PostgreSQL 19 release notes","url":"https://www.postgresql.org/docs/19/release-19.html"}],"related":["shared_preload_libraries","session_preload_libraries","dynamic_library_path","jit_provider","extension_control_path"],"summary":"local_preload_libraries is the PostgreSQL setting that lists unprivileged shared libraries to preload into each backend."},"enumvals":[],"first_version":"8.2","group":"Client Connection Defaults","group_slug":"client","imported_at":"2026-09-27T17:57:31.498305+08:00","intro_commit":{},"key":"local_preload_libraries","last_version":"20","max_val":"","min_val":"","name":"local_preload_libraries","position":214,"present_in":["8.2","8.3","8.4","9.0","9.1","9.2","9.3","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:41746a5ead0db2c64462ad2fa9c51f099f74432e4244d6e57785dabbb9c040e2","unit":"","vartype":"string"}},"Definition":{"Collection":"guc","Key":"local_preload_libraries","SourceDatabase":"center","Version":"18","SourceTable":"guc","SourceKey":"local_preload_libraries","SourceRevision":"english-manuals:41746a5ead0db2c64462ad2fa9c51f099f74432e4244d6e57785dabbb9c040e2","Facts":{"boot_val":"","category":"Client Connection Defaults / Shared Library Preloading","context":"user","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. 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.","doc":{"anchor":"GUC-LOCAL-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":"local_preload_libraries","short_desc":"Lists unprivileged shared libraries to preload into each backend.","source":"pg-settings-source-snapshot","unit":null,"vartype":"string"},"ManualEvidence":{"doc":{"anchor":"GUC-LOCAL-PRELOAD-LIBRARIES","file":"runtime-config-client.html","lang":"en","sha256":"6be6cc70f29eca4695dc43b2b2b94c75b7e0eaaa2c00273d7a98488917a7edb7","slug":"18"}},"MeasuredEvidence":{"metadata_version":"18"}},"Text":{"Collection":"guc","Key":"local_preload_libraries","SourceDatabase":"pgweb","Version":"18","Locale":"zh-Hans","Title":"local_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命令的方式解析。项之间的空格会被忽略，如果需要在库名中包含空格或者逗号，请把库名放在双引号内。这个参数值只在连接开始时生效。后续的更改不会有任何效果。如果一个指定的库没有找到，连接尝试将会失败。\u003c/p\u003e\u003cp\u003e任何用户都能设置这个选项。正因为如此，能被这样载入的库被严格限制为出现于安装的标准库目录中\u003ccode\u003eplugins\u003c/code\u003e子目录下的共享库（保证只有\u003cspan\u003e“\u003cspan\u003e安全的\u003c/span\u003e”\u003c/span\u003e库被安装到这里是数据库管理员的责任）。\u003ccode\u003elocal_preload_libraries\u003c/code\u003e中的项可以显式指定这个目录，例如\u003ccode\u003e$libdir/plugins/mylib\u003c/code\u003e，或者只是指定库的名称 — \u003ccode\u003emylib\u003c/code\u003e 和 \u003ccode\u003e$libdir/plugins/mylib\u003c/code\u003e的效果是相同的。\u003c/p\u003e\u003cp\u003e这个特性的目的是允许非特权用户在特定的会话中载入用于调试或性能测量的库，而无需一个显式的\u003ccode\u003eLOAD\u003c/code\u003e命令。为了这个目的，通常通过使用客户端的\u003ccode\u003ePGOPTIONS\u003c/code\u003e环境变量或者 \u003ccode\u003eALTER ROLE SET\u003c/code\u003e来设置这个参数。\u003c/p\u003e\u003cp\u003e不过，除非一个模块被特别设计成由非超级用户以这种方式使用，通常不推荐使用这个设置。请改为参阅\u003ca href=\"/docs/18/runtime-config-client.html#GUC-SESSION-PRELOAD-LIBRARIES\" rel=\"nofollow\"\u003esession_preload_libraries\u003c/a\u003e。\u003c/p\u003e","SourceRevision":"2026-09-11@29c86d9","ContentHash":"5ed461b9d820596ba283d88cf520b2319dda96e3af9e3f5970b32c07db264b8c","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命令的方式解析。项之间的空格会被忽略，如果需要在库名中包含空格或者逗号，请把库名放在双引号内。这个参数值只在连接开始时生效。后续的更改不会有任何效果。如果一个指定的库没有找到，连接尝试将会失败。\u003c/p\u003e\u003cp\u003e任何用户都能设置这个选项。正因为如此，能被这样载入的库被严格限制为出现于安装的标准库目录中\u003ccode class=\"filename\"\u003eplugins\u003c/code\u003e子目录下的共享库（保证只有\u003cspan class=\"quote\"\u003e“\u003cspan class=\"quote\"\u003e安全的\u003c/span\u003e”\u003c/span\u003e库被安装到这里是数据库管理员的责任）。\u003ccode class=\"varname\"\u003elocal_preload_libraries\u003c/code\u003e中的项可以显式指定这个目录，例如\u003ccode class=\"literal\"\u003e$libdir/plugins/mylib\u003c/code\u003e，或者只是指定库的名称 — \u003ccode class=\"literal\"\u003emylib\u003c/code\u003e 和 \u003ccode class=\"literal\"\u003e$libdir/plugins/mylib\u003c/code\u003e的效果是相同的。\u003c/p\u003e\u003cp\u003e这个特性的目的是允许非特权用户在特定的会话中载入用于调试或性能测量的库，而无需一个显式的\u003ccode class=\"command\"\u003eLOAD\u003c/code\u003e命令。为了这个目的，通常通过使用客户端的\u003ccode class=\"envar\"\u003ePGOPTIONS\u003c/code\u003e环境变量或者 \u003ccode class=\"command\"\u003eALTER ROLE SET\u003c/code\u003e来设置这个参数。\u003c/p\u003e\u003cp\u003e不过，除非一个模块被特别设计成由非超级用户以这种方式使用，通常不推荐使用这个设置。请改为参阅\u003ca href=\"/docs/18/runtime-config-client.html#GUC-SESSION-PRELOAD-LIBRARIES\"\u003esession_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","8.2","8.3","8.4","9.0","9.1","9.2","9.3","9.4","9.5","9.6"],"Locales":["en","zh-Hans"],"Signatures":null,"Spellings":null,"SQLState":null,"Evidence":null}