[PATCH] doc: Fix description of relative extension "directory" setting

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