[PATCH] doc: Fix description of relative extension "directory" setting
Hi,
Since PostgreSQL 18 (commit 81eaaa2c41d), the documentation of the
extension control file "directory" parameter says a relative path is
"relative to the directory where the control file was found".
However, that doesn't match the code: a relative path is resolved
against SHAREDIR,
or against the extension_control_path element in which the control
file was found, i.e. the parent of that "extension" directory.
Repro steps on master:
/tmp/repro/extension/dir_doc_probe.control:
default_version = '1.0'
directory = 'scripts'
relocatable = true
/tmp/repro/scripts/dir_doc_probe--1.0.sql:
CREATE TABLE dir_doc_probe_result (origin text);
INSERT INTO dir_doc_probe_result VALUES ('installation base');
/tmp/repro/extension/scripts/dir_doc_probe--1.0.sql:
CREATE TABLE dir_doc_probe_result (origin text);
INSERT INTO dir_doc_probe_result VALUES ('control-file directory');
BEGIN;
SET LOCAL extension_control_path = '/tmp/repro';
CREATE EXTENSION dir_doc_probe;
SELECT origin FROM dir_doc_probe_result;
origin
-------------------
installation base
(1 row)
ROLLBACK;
The attached patch restores the pre-18 wording, extended to cover
extension_control_path, and clarifies the extension_control_path
description accordingly.
On Oct 31, 2026, at 11:47, Mahendrakar Srinivasarao <mahendrakarforpg@gmail.com> wrote:
Hi,
Since PostgreSQL 18 (commit 81eaaa2c41d), the documentation of the
extension control file "directory" parameter says a relative path is
"relative to the directory where the control file was found".
However, that doesn't match the code: a relative path is resolved
against SHAREDIR,
or against the extension_control_path element in which the control
file was found, i.e. the parent of that "extension" directory.Repro steps on master:
/tmp/repro/extension/dir_doc_probe.control:
default_version = '1.0'
directory = 'scripts'
relocatable = true/tmp/repro/scripts/dir_doc_probe--1.0.sql:
CREATE TABLE dir_doc_probe_result (origin text);
INSERT INTO dir_doc_probe_result VALUES ('installation base');/tmp/repro/extension/scripts/dir_doc_probe--1.0.sql:
CREATE TABLE dir_doc_probe_result (origin text);
INSERT INTO dir_doc_probe_result VALUES ('control-file directory');BEGIN;
SET LOCAL extension_control_path = '/tmp/repro';
CREATE EXTENSION dir_doc_probe;
SELECT origin FROM dir_doc_probe_result;
origin
-------------------
installation base
(1 row)
ROLLBACK;The attached patch restores the pre-18 wording, extended to cover
extension_control_path, and clarifies the extension_control_path
description accordingly.
<0001-doc-Fix-description-of-relative-extension-directory.patch>
Thanks for the patch. I think the fix is going in the right direction.
The relevant code is:
```
static char *
get_extension_script_directory(ExtensionControlFile *control)
{
/*
* The directory parameter can be omitted, absolute, or relative to the
* installation's base directory, which can be the sharedir or a custom
* path that was set via extension_control_path. It depends on where the
* .control file was found.
*/
if (!control->directory)
return pstrdup(control->control_dir);
if (is_absolute_path(control->directory))
return pstrdup(control->directory);
Assert(control->basedir != NULL);
return psprintf("%s/%s", control->basedir, control->directory);
}
```
When control->directory is a relative path, it is resolved relative to control->basedir, which is either SHAREDIR or the corresponding path element in extension_control_path.
In the patch:
```
- the directory where the control file was found. By default,
- the script files are looked for in the same directory where the
- control file was found.
+ the installation's <literal>SHAREDIR</literal> directory, or to the
+ <xref linkend="guc-extension-control-path"/> element in which the
+ control file was found. The default behavior is equivalent to
+ specifying <literal>directory = 'extension'</literal>.
```
I think the phrase "the extension_control_path element in which the control file was found" is a little misleading.
For example, suppose we have:
```
extension_control_path = '/opt/myext/share’
```
The primary control file is found in /opt/myext/share/extension. If it specifies:
```
directory = ‘scripts’
```
the scripts will be loaded from /opt/myext/share/scripts, not /opt/myext/share/extension/scripts.
So, saying "in which the control file was found" might suggest /opt/myext/share/extension, rather than /opt/myext/share.
I would suggest wording it more explicitly, like:
```
or to the extension_control_path element used to locate the primary control file.
```
Best regards,
--
Chao Li (Evan)
HighGo Software Co., Ltd.
https://www.highgo.com/
+PostgreSQL Hackers
Show quoted text
On Tue, 3 Nov 2026 at 10:53, Chao Li <li.evan.chao@gmail.com> wrote:
On Nov 3, 2026, at 00:34, Mahendrakar Srinivasarao <mahendrakarforpg@gmail.com> wrote:
Hi Chao,
Thanks for the review.
I would suggest wording it more explicitly, like:
or to the extension_control_path element used to locate the primary control file.Agreed, the sentence "in which the control file was found" could be read as the
"extension" subdirectory itself.v2 patch uses your suggested wording:
```
Unless an absolute path is given, the name is relative to the
installation's SHAREDIR directory, or to the extension_control_path
element used to locate the primary control file. The default
behavior is equivalent to specifying directory = 'extension'.
```
I have also updated the commit message to match the same.Best regards,
Mahendrakar.<v2-0001-doc-Fix-description-of-relative-extension-directo.patch>
V2 LGTM.
Best regards,
--
Chao Li (Evan)
HighGo Software Co., Ltd.
https://www.highgo.com/
Import Notes
Reply to msg id not found: A40EAC4A-F75E-405F-8A15-92A203AE5B95@gmail.com
Hi,
Thanks for the patch!
I tested extension_control_path with a few different "directory" values:
a relative 'scripts', the MODULEDIR style 'extension/foo', an absolute
path, 'extension' and no directory at all. In all cases the scripts were
loaded from where the new wording says they should be, and 'extension'
behaves the same as not setting it. The patch also applies cleanly on
REL_18_STABLE, which has the same wrong text, and the docs build fine.
I have some small comments:
1: The SHAREDIR vs extension_control_path wording
- the directory where the control file was found. By default,
- the script files are looked for in the same directory where the
- control file was found.
+ the installation's <literal>SHAREDIR</literal> directory, or to the
+ <xref linkend="guc-extension-control-path"/> element used to locate
+ the primary control file. The default behavior is equivalent to
+ specifying <literal>directory = 'extension'</literal>.
The "or" in the new sentence doesn't say when each case applies. If the
control file is found via $system, the extension_control_path element
is $system itself, which expands to SHAREDIR/extension, not SHAREDIR,
so the "element used to locate the primary control file" can still be
read as the extension subdirectory. Maybe something like this?
Unless an absolute path is given, the name is relative to the parent
of the extension directory where the primary control file was
found, that is, the installation's SHAREDIR directory, or the
corresponding extension_control_path element.
It's just a nit though, v2 is already much better than the current text.
2: Commit message
"relative to the installation's base directory, i.e., SHAREDIR or the
extension_control_path element" is a bit loose, since a custom path
element is not really the installation's directory. Just "the base
directory" would be enough IMO.
Unrelated to the "directory" fix, but while reading the
extension_control_path docs I noticed that it says "If a list element
starts with the special string $system, the compiled-in PostgreSQL
extension directory is substituted for $system", but
get_extension_control_directories() only accepts an exact match, so
something like '$system/foo' is not expanded. CREATE EXTENSION then
fails with "component in parameter "extension_control_path" is not an
absolute path", while pg_available_extensions silently skips it.
The attached v3 includes a 0002 that fixes the docs for this. 0001 is
the same as v2-0001, so the comments above still apply to it.
--
Matheus Alcantara
EDB: https://www.enterprisedb.com
Attachments:
t254487_4v3-0001-doc-Fix-description-of-relative-extension-directo.patchtext/plain; charset=utf-8; name=v3-0001-doc-Fix-description-of-relative-extension-directo.patchDownload+7-5
v3-0002-doc-Fix-description-of-system-in-extension_contro.patchtext/plain; charset=utf-8; name=v3-0002-doc-Fix-description-of-system-in-extension_contro.patchDownload+8-6
Hi Matheus,
Thanks for testing this and for the review.
1: The SHAREDIR vs extension_control_path wording
Agreed. With extension_control_path = '$system', a control file in
SHAREDIR/extension with directory = 'scripts' loads its scripts from
SHAREDIR/scripts, so "the element used to locate the primary control
file" could indeed be read as SHAREDIR/extension. v4-0001 uses your
suggested wording:
Unless an absolute path is given, the name is relative to the parent
of the extension directory where the primary control file was found,
that is, the installation's SHAREDIR directory, or the corresponding
extension_control_path element.
2: Commit message
Fixed; it now says the path is resolved against "the base directory,
i.e., the parent of the "extension" directory in which the primary
control file was found".
The attached v3 includes a 0002 that fixes the docs for this.
I can reproduce it: with extension_control_path = '$system/foo',
pg_available_extensions returns no rows and CREATE EXTENSION fails with
"component in parameter "extension_control_path" is not an absolute
path". It's even more confusing when combined with a valid element:
with extension_control_path = '$system/foo:$system',
pg_available_extensions lists the extensions from $system (the bad
element is silently skipped as a nonexistent directory), but CREATE
EXTENSION on any of them still fails with the same error, because
find_in_paths() rejects the first element before it gets to $system.
0002 looks good and is included in v4 unchanged.
Two related things I noticed while testing:
- The long_desc of extension_control_path in guc_parameters.dat
(guc_tables.c on 18) has the same "loaded from the same directory
where the primary control file was found" sentence that 0001 fixes in
config.sgml. The new 0003 adjusts it to match. Since it's a
translatable string, I've kept it separate and meant it for master
only, so 0001 and 0002 can be backpatched without it.
- The '$system/foo:$system' inconsistency comes from find_in_paths()
and pg_available_extensions handling an invalid element differently,
and from nothing validating the value when it's set. Would a check
hook that rejects such elements at SET time be worth pursuing? One
concern is that it could break existing setups: a value like
'$system:$system/foo' works today for any extension found in $system,
but with a check hook it would be rejected, and in postgresql.conf
that would prevent the server from starting after an upgrade.
dynamic_library_path also only validates its elements when they're
used. If there's interest I can start a separate thread for that;
it's not addressed in v4.
v4-0001 and v4-0002 are rebased on current master and apply cleanly to
REL_19_STABLE and REL_18_STABLE; the docs build without warnings.
v4-0003 applies on master (and REL_19_STABLE, if wanted there); it
builds and passes make check.
Attachments:
t254487_5v4-0001-doc-Fix-description-of-relative-extension-directo.patchapplication/octet-stream; name=v4-0001-doc-Fix-description-of-relative-extension-directo.patchDownload+9-5
v4-0002-doc-Fix-description-of-system-in-extension_contro.patchapplication/octet-stream; name=v4-0002-doc-Fix-description-of-system-in-extension_contro.patchDownload+8-6
v4-0003-Fix-long-description-of-extension_control_path.patchapplication/octet-stream; name=v4-0003-Fix-long-description-of-extension_control_path.patchDownload+1-2
On Tue Nov 10, 2026 at 11:24 AM -03, Mahendrakar Srinivasarao wrote:
The attached v3 includes a 0002 that fixes the docs for this.
I can reproduce it: with extension_control_path = '$system/foo',
pg_available_extensions returns no rows and CREATE EXTENSION fails with
"component in parameter "extension_control_path" is not an absolute
path". It's even more confusing when combined with a valid element:
with extension_control_path = '$system/foo:$system',
pg_available_extensions lists the extensions from $system (the bad
element is silently skipped as a nonexistent directory), but CREATE
EXTENSION on any of them still fails with the same error, because
find_in_paths() rejects the first element before it gets to $system.0002 looks good and is included in v4 unchanged.
Thanks for checking!
Two related things I noticed while testing:
- The long_desc of extension_control_path in guc_parameters.dat
(guc_tables.c on 18) has the same "loaded from the same directory
where the primary control file was found" sentence that 0001 fixes in
config.sgml. The new 0003 adjusts it to match. Since it's a
translatable string, I've kept it separate and meant it for master
only, so 0001 and 0002 can be backpatched without it.
Good.
- The '$system/foo:$system' inconsistency comes from find_in_paths()
and pg_available_extensions handling an invalid element differently,
and from nothing validating the value when it's set. Would a check
hook that rejects such elements at SET time be worth pursuing? One
concern is that it could break existing setups: a value like
'$system:$system/foo' works today for any extension found in $system,
but with a check hook it would be rejected, and in postgresql.conf
that would prevent the server from starting after an upgrade.
dynamic_library_path also only validates its elements when they're
used. If there's interest I can start a separate thread for that;
it's not addressed in v4.
This seems related with another discussion about an
extension_control_path bug [1]/messages/by-id/DC2D9FA5-45C4-494F-99FC-F9B95AD4FF55@gmail.com that accepts an empty path element and
append /extension by mistake. I think that we can discuss about this
case on this other thread.
v4-0001 and v4-0002 are rebased on current master and apply cleanly to
REL_19_STABLE and REL_18_STABLE; the docs build without warnings.
v4-0003 applies on master (and REL_19_STABLE, if wanted there); it
builds and passes make check.
v4 looks good to me, thanks!
I've moved the CF entry from drafts to PG20-4. If there is no other
comments on this I think that we can mark this as Ready for Committer in
the following days.
[1]: /messages/by-id/DC2D9FA5-45C4-494F-99FC-F9B95AD4FF55@gmail.com
--
Matheus Alcantara
EDB: https://www.enterprisedb.com
On Nov 11, 2026, at 00:30, Matheus Alcantara <matheusssilv97@gmail.com> wrote:
On Tue Nov 10, 2026 at 11:24 AM -03, Mahendrakar Srinivasarao wrote:
The attached v3 includes a 0002 that fixes the docs for this.
I can reproduce it: with extension_control_path = '$system/foo',
pg_available_extensions returns no rows and CREATE EXTENSION fails with
"component in parameter "extension_control_path" is not an absolute
path". It's even more confusing when combined with a valid element:
with extension_control_path = '$system/foo:$system',
pg_available_extensions lists the extensions from $system (the bad
element is silently skipped as a nonexistent directory), but CREATE
EXTENSION on any of them still fails with the same error, because
find_in_paths() rejects the first element before it gets to $system.0002 looks good and is included in v4 unchanged.
Thanks for checking!
Two related things I noticed while testing:
- The long_desc of extension_control_path in guc_parameters.dat
(guc_tables.c on 18) has the same "loaded from the same directory
where the primary control file was found" sentence that 0001 fixes in
config.sgml. The new 0003 adjusts it to match. Since it's a
translatable string, I've kept it separate and meant it for master
only, so 0001 and 0002 can be backpatched without it.Good.
- The '$system/foo:$system' inconsistency comes from find_in_paths()
and pg_available_extensions handling an invalid element differently,
and from nothing validating the value when it's set. Would a check
hook that rejects such elements at SET time be worth pursuing? One
concern is that it could break existing setups: a value like
'$system:$system/foo' works today for any extension found in $system,
but with a check hook it would be rejected, and in postgresql.conf
that would prevent the server from starting after an upgrade.
dynamic_library_path also only validates its elements when they're
used. If there's interest I can start a separate thread for that;
it's not addressed in v4.This seems related with another discussion about an
extension_control_path bug [1] that accepts an empty path element and
append /extension by mistake. I think that we can discuss about this
case on this other thread.v4-0001 and v4-0002 are rebased on current master and apply cleanly to
REL_19_STABLE and REL_18_STABLE; the docs build without warnings.
v4-0003 applies on master (and REL_19_STABLE, if wanted there); it
builds and passes make check.v4 looks good to me, thanks!
V4 LGTM too.
Best regards,
--
Chao Li (Evan)
HighGo Software Co., Ltd.
https://www.highgo.com/