Documentation/Behavior: Systemd Type=notify failure with pg_ctl on Debian 12
The following documentation comment has been logged on the website:
Page: https://www.postgresql.org/docs/18/server-start.html
Description:
**PostgreSQL Version:** 18.1 (devel/snapshot) and 17.5
**Operating System:** Debian 12.11 (amd64)
**Installation Method:** Source compilation
**Configure Options:** `./configure --prefix=/usr/local/services/pgsql-18.1
--with-llvm --with-systemd`
**Description:**
I am encountering an issue starting the PostgreSQL service using systemd
after compiling from source with `--with-systemd`.
While the server starts correctly when invoking `pg_ctl` manually from the
command line, it fails to start when using a systemd unit file configured
with `Type=notify`, which references the documentation at
[https://www.postgresql.org/docs/current/server-start.html](https://www.postgresql.org/docs/current/server-start.html).
**Steps to Reproduce:**
1. Compile and install PostgreSQL with systemd support.
2. Create a systemd unit file as follows (using `pg_ctl` in ExecStart):
```Ini
[Unit]
Description=PostgreSQL database server
Documentation=man:postgres(1)
After=network-online.target
Wants=network-online.target
[Service]
Type=notify
User=postgres
WorkingDirectory=/usr/local/services/pgsql-18.1
# Using pg_ctl to start the service
ExecStart=/usr/local/services/pgsql-18.1/bin/pg_ctl start -D
/usr/local/services/pgsql-18.1/data -l /usr/local/services/pgsql-18.1/pg.log
ExecReload=/bin/kill -HUP $MAINPID
KillMode=mixed
KillSignal=SIGINT
TimeoutSec=infinity
[Install]
WantedBy=multi-user.target
```
3. Run `sudo systemctl daemon-reload` and `sudo systemctl start postgresql`.
**Observed Result:**
The service hangs in the "activating" state until it times out, even though
the database process is actually running in the background. Systemd
eventually kills the process because it never receives the readiness
notification.
`pg.log` (even at debug5 level) shows no errors, confirming the database
started but the notification was not acknowledged by systemd.
**Analysis & Fix:**
Since `ExecStart` executes `pg_ctl`, but the `sd_notify` signal is sent by
the forked `postgres` process, systemd ignores the signal by default.
I found that adding the following lines to the `[Service]` section fixes the
issue entirely:
```Ini
NotifyAccess=all
PIDFile=/usr/local/services/pgsql-18.1/data/postmaster.pid
```
**Suggestion:**
The documentation regarding Systemd integration (specifically when using
`pg_ctl` combined with `Type=notify`) might be incomplete. It appears that
`NotifyAccess=all` is mandatory when `ExecStart` is a wrapper (like
`pg_ctl`) rather than the `postgres` binary itself.
I confirmed this behavior on both PostgreSQL v18.1 and v17.5 on Debian 12.
I suggest updating the documentation examples or adding a note about
`NotifyAccess` for users compiling with `--with-systemd`.
Best regards.
These forms submit plain text - submitting markdown makes them more
difficult to review. In particular the link format doesn't play well with
my mail reader's link auto-detection.
On Fri, Jan 9, 2026 at 1:10 AM PG Doc comments form <noreply@postgresql.org>
wrote:
The documentation regarding Systemd integration (specifically when using
`pg_ctl` combined with `Type=notify`) might be incomplete.
Such documentation is nonexistent, not incomplete. The provided unit file
for systemd doesn't use pg_ctl, I suppose presumably for this or a similar
reason. It uses the postgres binary directly.
Such, I'm not seeing a bug here (I suppose a comment pointing out that/why
pg_ctl is not used might be in order). I'm not opposed to possibly adding
more detail or alternatives to this part of the documentation - though the
number of people doing their own unit files is few compared to those using
ones bundled in a package - but the lack or responders seems to suggest
such effort is not high on anyone's list.
David J.
The only possible doc change I think warranted is to tell people NOT to use
pg_ctl with systemd (because it makes no sense), but just use the binary
instead. However, the example in the docs (
https://www.postgresql.org/docs/current/server-start.html) already does
that, ,and works fine as written, so I don't think the docs should
anticipate every way in which someone might wrongly modify the file.
Cheers,
Greg
--
Crunchy Data - https://www.crunchydata.com
Enterprise Postgres Software Products & Tech Support