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

[Chao Li]

> On Oct 31, 2026, at 11:47, Mahendrakar Srinivasarao 
> <mahendrakarfo...@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/