Operating a package install

Before exposing it to a network

The gateway binds all interfaces (0.0.0.0:10260 and [::]:10260) by default. The PostgreSQL instance behind it stays on loopback.

Before using this anywhere but a private machine:

• Restrict the listener with DOCUMENTDB_LISTEN_ADDR=127.0.0.1:10260 in /etc/documentdb/local/<major>/gateway.env and restart the service, or firewall port 10260. Re-running documentdb-setup silently resets this to a wildcard bind, so re-check with grep DOCUMENTDB_LISTEN_ADDR /etc/documentdb/local/<major>/gateway.env afterwards. A firewall rule is the more durable control.
• Replace the auto-generated self-signed certificate. tlsAllowInvalidCertificates=true disables certificate validation — point DOCUMENTDB_TLS_CERT_FILE / DOCUMENTDB_TLS_KEY_FILE at a real certificate and drop that option.
• Use a strong admin password and create per-application users rather than sharing admin.

Services and paths

sudo documentdb-setup --status      # gateway listener, service states, resolved paths
documentdb-gateway --version        # DocumentDB version
dpkg -l | grep documentdb           # or: rpm -qa | grep documentdb

On a systemd host both services log to the journal; the log files above exist only when documentdb-setup falls back to its non-systemd nohup mode. documentdb-setup --status prints whichever applies to your host.

Units are templated per PostgreSQL major:

sudo systemctl status  documentdb-local@18.target
sudo systemctl restart documentdb-local@18.target
sudo systemctl stop    documentdb-local@18.target

Running SQL against the managed instance

documentdb-setup runs a private instance as the documentdb-local user on a socket, so a bare psql will not find it:

sudo -u documentdb-local psql -h /run/documentdb-local/18/postgresql -p 9718 -d postgres

SELECT extname, extversion FROM pg_extension WHERE extname LIKE 'documentdb%';

Upgrading

A package upgrade only replaces files. Afterwards, update the extensions in every database that has DocumentDB installed:

ALTER EXTENSION documentdb_core UPDATE;
ALTER EXTENSION documentdb UPDATE;
ALTER EXTENSION documentdb_extended_rum UPDATE;  -- only if installed

PostgreSQL applies intermediate upgrade scripts automatically. In-place upgrades are not yet a fully tested path, so take a backup first.

Remove or reset

# Stop the stack first. On systemd hosts:
sudo systemctl stop documentdb-local@18.target
# Without systemd, use an UNSCOPED restore (no --pg-version):
sudo documentdb-setup --restore

sudo documentdb-local-reset --pg-version 18 --confirm-destroy    # DESTROYS the data directory

# Name the package you installed AND the extension: autoremove does not reap
# postgresql-18-documentdb, and 'remove' would leave config behind.
sudo apt purge --autoremove documentdb-18 postgresql-18-documentdb
sudo dnf remove documentdb-18 postgresql18-documentdb && sudo dnf autoremove

Confirm the stack is down first with ss -lnt | grep 10260. A gateway still running when its packages go keeps serving from a deleted binary. On a multi-major host remove one major at a time and re-check the survivor: documentdb-common owns the shared tooling and only documentdb-N holds it.

Known issues in 0.116

These are defects in this release, not expected behaviour. Most need a host without systemd to hit; the two marked any host do not.

Prefer a systemd host for anything you care about, where the service lifecycle is managed by systemd rather than by the setup script.

Multiple PostgreSQL majors

Install the matching documentdb-N for every major you configure. documentdb-setup refuses a major whose extension package is missing:

ERROR: The DocumentDB extension package is not installed for PostgreSQL 17
(/usr/share/postgresql/17/extension/documentdb.control is missing).

Each major also needs its own gateway port — the second one fails on Gateway port 10260 is already in use unless you pass --gateway-port:

sudo documentdb-setup --pg-version 17 --gateway-port 10261 --admin-user admin

Troubleshooting

Failure modes beyond the four in the quick start:

• Bad GPG signature on pgdg-common — wrong architecture in the PGDG repository URL
• apt install hangs in a container — export DEBIAN_FRONTEND=noninteractive first, and drop the leading sudo when running as root (minimal images often have no sudo). Keep sudo -u <user>, which switches user; su documentdb-local -c fails because that account has /usr/sbin/nologin, so use su -s /bin/bash documentdb-local -c '...'
• Debian 11 has PostgreSQL 18 from PGDG but no postgresql-18-postgis-3 for Bullseye, so the dependency set cannot be satisfied; use 16 or 17
• ss: command not found on a minimal RHEL host — install iproute; the DocumentDB packages do not pull it in
• Debian 13 also gets this extension from apt.postgresql.org, whose version sorts higher; pin with apt install postgresql-18-documentdb=<VERSION> for this repository's build
• db.version() and buildInfo in mongosh report the emulated MongoDB wire version, not DocumentDB's — use documentdb-gateway --version

Multiple PostgreSQL majors

Install the matching documentdb-N for every major you configure. documentdb-setup --pg-version N will happily configure a major whose package is absent, and nothing then owns the result — a later autoremove can reap documentdb-common out from under it.

Unattended setup

documentdb-setup prompts for the admin password. For servers and CI, pass --admin-password-file <file> or --admin-password-stdin together with --yes.