extension_control_path

Definition PG 18 manual

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'

How it works

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.

Operational considerations

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.

Workload guidance

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.