Instances

An instance is a named Postgres server with its own data folder. It is created on first start and keeps its version, port and settings, so later commands only need its name.

Start

pgembed start app --version 17          # background; prints the connection string
pgembed start app                       # already running? attaches and prints it again
pgembed start ci --version 16,17,18     # three instances side by side: ci-16, ci-17, ci-18

^{snippet source | anchor}

An instance keeps its major version: its data can only be opened by that major. To move to another major, create a new instance. Starting an instance that is already running, whether started by pgembed, by the MCP server or by a test, attaches to it instead of starting another server.

Settings and a fixed port:

pgembed start tuned --version 17 --port 5433 \
  --param shared_buffers=256MB --param max_connections=300

^{snippet source | anchor}

Option	Meaning
-v, --version	Exact (17.6.0), major (17), minor (17.6) or latest; comma-separated for several
-p, --port	Port; default 5432 when free, otherwise any free port. Kept for later starts
--param KEY=VALUE	A server setting. Repeatable
--extension URL	An extension zip to install; add #sha256=<hex> to verify it. Repeatable
--locale	Locale for a new instance's data; default en_US.UTF-8, or C.UTF-8 on Linux systems without it
--foreground	Stay attached to the terminal instead of running in the background

To keep Postgres in the foreground, for systemd, supervisord or a container's main process:

pgembed start dev --version 17 --foreground   # streams the log; Ctrl+C stops Postgres cleanly

^{snippet source | anchor}

Inspect

pgembed status                          # version, port, process, state, uptime, data size
pgembed connstr app                     # every format: npgsql, uri, libpq, jdbc, env
pgembed connstr app --format uri        # just one, for scripts
pgembed logs app --tail 20

^{snippet source | anchor}

  NAME   VERSION   PORT   PID     STATE     UPTIME   DATA
 ───────────────────────────────────────────────────────────
  app    17.11.0   5432   78419   running   2h 14m   46 MB

Connection strings in scripts

connstr prints every format, or just one with --format: npgsql, uri, libpq, jdbc or env.

export DATABASE_URL="$(pgembed connstr app --format uri)"
pgembed connstr app --format env > .env                      # PGHOST, PGPORT, PGUSER, PGDATABASE
set -a; eval "$(pgembed connstr app --format env)"; set +a   # or export them in this shell

^{snippet source | anchor}

Stop and remove

pgembed restart app
pgembed stop app
pgembed stop 'ci-*'                     # wildcards; or: pgembed stop --all
pgembed rm tuned --force --yes          # delete an instance and its data

^{snippet source | anchor}

rm asks before deleting an instance's data, and needs --force for a running one. When stop does not work:

pgembed kill app                        # last resort, when stop does not work

^{snippet source | anchor}