{"Entry":{"collection":"guc","key":"shared_preload_libraries","name":"shared_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"],"changes":[{"documentation_changed":false,"fields":{},"from":"8.1","status":"added","to":"8.2"},{"documentation_changed":true,"fields":{},"from":"8.2","status":"changed","to":"8.3"},{"documentation_changed":true,"fields":{},"from":"8.4","status":"changed","to":"9.0"},{"documentation_changed":true,"fields":{"category":{"from":"Resource Usage / Kernel Resources","to":"Client Connection Defaults / Shared Library Preloading"}},"from":"9.3","status":"changed","to":"9.4"},{"documentation_changed":true,"fields":{},"from":"9.4","status":"changed","to":"9.5"},{"documentation_changed":true,"fields":{},"from":"9.6","status":"changed","to":"10"}],"content_hash":"4f3399f0b93f7d7f70ea13e4c4496f746393f0076584aa2c5769e6153b2bd4c9","context":"","default_changed_in":[],"default_history":[{"from":"9.0","to":"19","value":"Empty string"}],"editorial":{"advice":{"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."},"mechanism":["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."],"pitfalls":["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."],"references":[{"title":"PostgreSQL 19 Beta 4: shared_preload_libraries","url":"https://www.postgresql.org/docs/19/runtime-config-client.html#GUC-SHARED-PRELOAD-LIBRARIES"},{"title":"PostgreSQL 19 release notes","url":"https://www.postgresql.org/docs/19/release-19.html"}],"related":["session_preload_libraries","local_preload_libraries","dynamic_library_path","jit_provider","extension_control_path"],"summary":"shared_preload_libraries is the PostgreSQL setting that lists shared libraries to preload into server."},"enumvals":[],"first_version":"8.2","group":"Client Connection Defaults","group_slug":"client","imported_at":"2026-09-27T17:57:31.976263+08:00","intro_commit":{},"key":"shared_preload_libraries","last_version":"20","max_val":"","min_val":"","name":"shared_preload_libraries","position":361,"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 to be preloaded at server start.","short_desc_zh":"","source_rev":"english-manuals:d08630ebaefede03839708edb7a796056863e9bffbcc4c92a505450d8cf6c105","unit":"","vartype":"string"}},"Definition":{"Collection":"guc","Key":"shared_preload_libraries","SourceDatabase":"center","Version":"18","SourceTable":"guc","SourceKey":"shared_preload_libraries","SourceRevision":"english-manuals:d08630ebaefede03839708edb7a796056863e9bffbcc4c92a505450d8cf6c105","Facts":{"boot_val":"","category":"Client Connection Defaults / Shared Library Preloading","context":"postmaster","description":"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. Note On Windows hosts, preloading a library at server start will not reduce the time required to start each new server process; each server process will re-load all preload libraries. However, shared_preload_libraries is still useful on Windows hosts for libraries that need to perform operations at postmaster start time.","doc":{"anchor":"GUC-SHARED-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":"shared_preload_libraries","short_desc":"Lists shared libraries to preload into server.","source":"pg-settings-source-snapshot","unit":null,"vartype":"string"},"ManualEvidence":{"doc":{"anchor":"GUC-SHARED-PRELOAD-LIBRARIES","file":"runtime-config-client.html","lang":"en","sha256":"6be6cc70f29eca4695dc43b2b2b94c75b7e0eaaa2c00273d7a98488917a7edb7","slug":"18"}},"MeasuredEvidence":{"metadata_version":"18"}},"Text":{"Collection":"guc","Key":"shared_preload_libraries","SourceDatabase":"pgweb","Version":"18","Locale":"zh-Hans","Title":"shared_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有些库需要执行只能在postmaster启动时发生的特定操作，例如分配共享内存、保留轻量级锁或者启动后台工作者。这些库必须通过这个参数在服务器启动时载入。每个库的详情请见文档。\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\u003cdiv\u003e\n注意\u003cp\u003e在 Windows 主机上，在服务器启动时预载入一个库并不会减少启动每个新服务器进程所需的时间；每一个服务器进程将会重新载入所有预载入的库。不过，对于那些要在postmaster启动时执行操作的库来说，Windows 主机上的 \u003ccode\u003eshared_preload_libraries\u003c/code\u003e仍然有用。\u003c/p\u003e\u003c/div\u003e","SourceRevision":"2026-09-11@29c86d9","ContentHash":"da36477e46d3921d958087b5be4ebeb40fae08389d6fced3f02adf8e2769c391","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有些库需要执行只能在postmaster启动时发生的特定操作，例如分配共享内存、保留轻量级锁或者启动后台工作者。这些库必须通过这个参数在服务器启动时载入。每个库的详情请见文档。\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\u003cdiv class=\"note\"\u003e\n注意\u003cp\u003e在 Windows 主机上，在服务器启动时预载入一个库并不会减少启动每个新服务器进程所需的时间；每一个服务器进程将会重新载入所有预载入的库。不过，对于那些要在postmaster启动时执行操作的库来说，Windows 主机上的 \u003ccode class=\"varname\"\u003eshared_preload_libraries\u003c/code\u003e仍然有用。\u003c/p\u003e\u003c/div\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}