{"Entry":{"collection":"guc","key":"extension_control_path","name":"extension_control_path","aliases":[],"metadata":{"baseline":false,"boot_human":"Not specified","boot_val":null,"category":"Client Connection Defaults / Other Defaults","category_zh":"","changed_in":[],"changes":[{"documentation_changed":false,"fields":{},"from":"17","status":"added","to":"18"}],"content_hash":"b159c39bbc015161624a4095a9f2e7866ae0f7ca760d411c2a4970226b3e1d70","context":"","default_changed_in":[],"default_history":[{"from":"18","to":"19","value":"$system"}],"editorial":{"advice":{"olap":"Use a separate path only to distribute a reviewed extension catalog consistently across primary and standby packages; test CREATE EXTENSION and every upgrade edge.","oltp":"Keep $system first and add only administrator-controlled extension repositories whose control files, scripts, native libraries, upgrades, and rollback are versioned together.","small":"Keep $system. Extra control-file roots do not improve capacity and make extension provenance and disaster recovery harder to audit."},"mechanism":["extension_control_path sets the path for extension control files. The remaining extension script and secondary control files are then loaded from the same directory where the primary control file was found. PostgreSQL searches this path for an extension's primary control file, then loads its scripts and secondary control files from the directory where that primary file was found.","extension_control_path is a SUPERUSER-context setting. Superuser or a role granted the appropriate SET privilege can change it for a session, while ALTER ROLE or ALTER DATABASE can establish a default for future sessions.","Library discovery and preloading interact with installed binary versions, extension control files, server or backend startup, and the module's own GUCs."],"pitfalls":["Changing extension_control_path 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 extension_control_path globally without a rollback plan and a client or operational compatibility test."],"references":[{"title":"PostgreSQL 19 Beta 4: extension_control_path","url":"https://www.postgresql.org/docs/19/runtime-config-client.html#GUC-EXTENSION-CONTROL-PATH"},{"title":"PostgreSQL 19 release notes","url":"https://www.postgresql.org/docs/19/release-19.html"}],"related":["shared_preload_libraries","session_preload_libraries","local_preload_libraries","dynamic_library_path","jit_provider"],"summary":"extension_control_path is the PostgreSQL setting that defines the path for extension control files."},"enumvals":[],"first_version":"18","group":"Client Connection Defaults","group_slug":"client","imported_at":"2026-09-27T17:57:31.265019+08:00","intro_commit":{"authored_at":"2025-03-19T06:57:20+01:00","discussion":["https://www.postgresql.org/message-id/flat/E7C7BFFB-8857-48D4-A71F-88B359FADCFD@justatheory.com"],"hash":"4f7f7b0375854e2f89876473405a8f21c95012af","subject":"extension_control_path","url":"https://git.postgresql.org/gitweb/?p=postgresql.git;a=commit;h=4f7f7b0375854e2f89876473405a8f21c95012af"},"key":"extension_control_path","last_version":"20","max_val":"","min_val":"","name":"extension_control_path","position":143,"present_in":["18","19","20"],"short_desc":"A path to search for extensions, specifically extension control files (name.control).","short_desc_zh":"","source_rev":"english-manuals:9d53152d15b249da98f84c32ca123ac4405bbc5d73306d5717ba26df05452fee","unit":"","vartype":"string"}},"Definition":{"Collection":"guc","Key":"extension_control_path","SourceDatabase":"center","Version":"18","SourceTable":"guc","SourceKey":"extension_control_path","SourceRevision":"english-manuals:9d53152d15b249da98f84c32ca123ac4405bbc5d73306d5717ba26df05452fee","Facts":{"boot_val":"$system","category":"Client Connection Defaults / Other Defaults","context":"superuser","description":"A path to search for extensions, specifically extension control files (name.control). The remaining extension script and secondary control files are then loaded from the same directory where the primary control file was found. See Section 36.17.1 for details. The value for extension_control_path must be a list of absolute directory paths separated by colons (or semi-colons on Windows). If a list element starts with the special string $system, the compiled-in PostgreSQL extension directory is substituted for $system; this is where the extensions provided by the standard PostgreSQL distribution are installed. (Use pg_config --sharedir to find out the name of this directory.) For example: extension_control_path = '/usr/local/share/postgresql:/home/my_project/share:$system' or, in a Windows environment: extension_control_path = 'C:\\tools\\postgresql;H:\\my_project\\share;$system' Note that the specified paths elements are expected to have a subdirectory extension which will contain the .control and .sql files; the extension suffix is automatically appended to each path element. The default value for this parameter is '$system'. If the value is set to an empty string, the default '$system' is also assumed. If extensions with equal names are present in multiple directories in the configured path, only the instance found first in the path will be used. This parameter can be changed at run time by superusers and users with the appropriate SET privilege, but a setting done that way will only persist until the end of the client connection, so this method should be reserved for development purposes. The recommended way to set this parameter is in the postgresql.conf configuration file. Note that if you set this parameter to be able to load extensions from nonstandard locations, you will most likely also need to set dynamic_library_path to a correspondent location, for example, extension_control_path = '/usr/local/share/postgresql:$system' dynamic_library_path = '/usr/local/lib/postgresql:$libdir'","doc":{"anchor":"GUC-EXTENSION-CONTROL-PATH","file":"runtime-config-client.html","lang":"en","sha256":"6be6cc70f29eca4695dc43b2b2b94c75b7e0eaaa2c00273d7a98488917a7edb7","slug":"18"},"documented":true,"enumvals":null,"extra_desc":"The remaining extension script and secondary control files are then loaded from the same directory where the primary control file was found.","lang":"en","max_val":null,"metadata_version":"18","min_val":null,"name":"extension_control_path","short_desc":"Sets the path for extension control files.","source":"pg-settings-source-snapshot","unit":null,"vartype":"string"},"ManualEvidence":{"doc":{"anchor":"GUC-EXTENSION-CONTROL-PATH","file":"runtime-config-client.html","lang":"en","sha256":"6be6cc70f29eca4695dc43b2b2b94c75b7e0eaaa2c00273d7a98488917a7edb7","slug":"18"}},"MeasuredEvidence":{"metadata_version":"18"}},"Text":{"Collection":"guc","Key":"extension_control_path","SourceDatabase":"pgweb","Version":"18","Locale":"zh-Hans","Title":"extension_control_path","Summary":"","BodyHTML":"\u003cp\u003e搜索扩展的路径，特别是扩展控制文件（\u003ccode\u003e\u003cem\u003e\u003ccode\u003ename\u003c/code\u003e\u003c/em\u003e.control\u003c/code\u003e）。其余扩展脚本和辅助控制文件会从找到主控制文件的同一目录中加载。详情请参见\u003ca href=\"/docs/18/extend-extensions.html#EXTEND-EXTENSIONS-FILES\" rel=\"nofollow\"\u003e第 36.17.1 节\u003c/a\u003e。\u003c/p\u003e\u003cp\u003e\u003ccode\u003eextension_control_path\u003c/code\u003e 的值必须是绝对目录路径列表，各路径以冒号分隔（在 Windows 上使用分号）。如果某个列表元素以特殊字符串 \u003ccode\u003e$system\u003c/code\u003e 开头，则 \u003ccode\u003e$system\u003c/code\u003e 会被替换为编译时确定的 \u003cspan\u003ePostgreSQL\u003c/span\u003e 扩展目录，也就是标准版 \u003cspan\u003ePostgreSQL\u003c/span\u003e 所提供扩展的安装位置。（可使用 \u003ccode\u003epg_config --sharedir\u003c/code\u003e 查找该目录名称。）例如：\u003c/p\u003e\u003cpre\u003eextension_control_path = \u0026#39;/usr/local/share/postgresql:/home/my_project/share:$system\u0026#39;\n\u003c/pre\u003e\u003cp\u003e或者在 Windows 环境中：\u003c/p\u003e\u003cpre\u003eextension_control_path = \u0026#39;C:\\tools\\postgresql;H:\\my_project\\share;$system\u0026#39;\n\u003c/pre\u003e\u003cp\u003e请注意，指定的每个路径元素都应当包含一个 \u003ccode\u003eextension\u003c/code\u003e 子目录，其中放置 \u003ccode\u003e.control\u003c/code\u003e 和 \u003ccode\u003e.sql\u003c/code\u003e 文件；系统会自动为每个路径元素追加 \u003ccode\u003eextension\u003c/code\u003e 后缀。\u003c/p\u003e\u003cp\u003e该参数的默认值是 \u003ccode\u003e\u0026#39;$system\u0026#39;\u003c/code\u003e。如果将其设置为空字符串，也会视为默认的 \u003ccode\u003e\u0026#39;$system\u0026#39;\u003c/code\u003e。\u003c/p\u003e\u003cp\u003e如果配置路径中的多个目录中存在同名扩展，则只会使用路径中最先找到的那个。\u003c/p\u003e\u003cp\u003e该参数可以由超级用户和具有适当\u003ccode\u003eSET\u003c/code\u003e权限的用户在运行时更改，但这种方式下的设置只会持续到客户端连接结束，因此这种方法应保留用于开发目的。推荐在\u003ccode\u003epostgresql.conf\u003c/code\u003e中设置该参数。\u003c/p\u003e\u003cp\u003e请注意，如果设置此参数以便从非标准位置加载扩展，通常还需要将\u003ca href=\"/docs/18/runtime-config-client.html#GUC-DYNAMIC-LIBRARY-PATH\" rel=\"nofollow\"\u003edynamic_library_path\u003c/a\u003e设置为相应的位置，例如：\u003c/p\u003e\u003cpre\u003eextension_control_path = \u0026#39;/usr/local/share/postgresql:$system\u0026#39;\ndynamic_library_path = \u0026#39;/usr/local/lib/postgresql:$libdir\u0026#39;\n\u003c/pre\u003e","SourceRevision":"2026-09-11@29c86d9","ContentHash":"67f2b411ada499968ab7d8ee2a4c9a32e90a35e7d278a4586998d09299b553e3","Payload":{"carried_from":"","carry_reason":"","doc_html":"\u003cp\u003e搜索扩展的路径，特别是扩展控制文件（\u003ccode class=\"filename\"\u003e\u003cem\u003e\u003ccode\u003ename\u003c/code\u003e\u003c/em\u003e.control\u003c/code\u003e）。其余扩展脚本和辅助控制文件会从找到主控制文件的同一目录中加载。详情请参见\u003ca href=\"/docs/18/extend-extensions.html#EXTEND-EXTENSIONS-FILES\" title=\"36.17.1. 扩展文件\"\u003e第 36.17.1 节\u003c/a\u003e。\u003c/p\u003e\u003cp\u003e\u003ccode class=\"varname\"\u003eextension_control_path\u003c/code\u003e 的值必须是绝对目录路径列表，各路径以冒号分隔（在 Windows 上使用分号）。如果某个列表元素以特殊字符串 \u003ccode class=\"literal\"\u003e$system\u003c/code\u003e 开头，则 \u003ccode class=\"literal\"\u003e$system\u003c/code\u003e 会被替换为编译时确定的 \u003cspan class=\"productname\"\u003ePostgreSQL\u003c/span\u003e 扩展目录，也就是标准版 \u003cspan class=\"productname\"\u003ePostgreSQL\u003c/span\u003e 所提供扩展的安装位置。（可使用 \u003ccode class=\"literal\"\u003epg_config --sharedir\u003c/code\u003e 查找该目录名称。）例如：\u003c/p\u003e\u003cpre\u003eextension_control_path = '/usr/local/share/postgresql:/home/my_project/share:$system'\n\u003c/pre\u003e\u003cp\u003e或者在 Windows 环境中：\u003c/p\u003e\u003cpre\u003eextension_control_path = 'C:\\tools\\postgresql;H:\\my_project\\share;$system'\n\u003c/pre\u003e\u003cp\u003e请注意，指定的每个路径元素都应当包含一个 \u003ccode class=\"filename\"\u003eextension\u003c/code\u003e 子目录，其中放置 \u003ccode class=\"filename\"\u003e.control\u003c/code\u003e 和 \u003ccode class=\"filename\"\u003e.sql\u003c/code\u003e 文件；系统会自动为每个路径元素追加 \u003ccode class=\"filename\"\u003eextension\u003c/code\u003e 后缀。\u003c/p\u003e\u003cp\u003e该参数的默认值是 \u003ccode class=\"literal\"\u003e'$system'\u003c/code\u003e。如果将其设置为空字符串，也会视为默认的 \u003ccode class=\"literal\"\u003e'$system'\u003c/code\u003e。\u003c/p\u003e\u003cp\u003e如果配置路径中的多个目录中存在同名扩展，则只会使用路径中最先找到的那个。\u003c/p\u003e\u003cp\u003e该参数可以由超级用户和具有适当\u003ccode class=\"literal\"\u003eSET\u003c/code\u003e权限的用户在运行时更改，但这种方式下的设置只会持续到客户端连接结束，因此这种方法应保留用于开发目的。推荐在\u003ccode class=\"filename\"\u003epostgresql.conf\u003c/code\u003e中设置该参数。\u003c/p\u003e\u003cp\u003e请注意，如果设置此参数以便从非标准位置加载扩展，通常还需要将\u003ca href=\"/docs/18/runtime-config-client.html#GUC-DYNAMIC-LIBRARY-PATH\"\u003edynamic_library_path\u003c/a\u003e设置为相应的位置，例如：\u003c/p\u003e\u003cpre\u003eextension_control_path = '/usr/local/share/postgresql:$system'\ndynamic_library_path = '/usr/local/lib/postgresql:$libdir'\n\u003c/pre\u003e","doc_same_as":""}},"RequestedLocale":"zh-Hans","Fallback":false,"Versions":["18","19","20"],"Locales":["en","zh-Hans"],"Signatures":null,"Spellings":null,"SQLState":null,"Evidence":null}