pgb is a local PostgreSQL database-branching CLI. It creates full, independent database copies with PostgreSQL's CREATE DATABASE ... TEMPLATE ... mechanism and tracks logical branch names by database OID.
The current version supports two modes:
- Checkout mode keeps an application's database name unchanged.
pgb checkoutatomically parks the current database and renames the selected branch to the canonical name. It is intended for one running application at a time. - Worktree mode gives every branch a stable database name.
pgb attachupdates one configured Git-ignored dotenv key, whilepgb runinjects the connection into a child process without writing a file. Multiple worktrees can run concurrently. Your agents will love it.
The modes are mutually exclusive within a project.
- PostgreSQL 14 or newer.
- Permission to connect to the standard
postgresdatabase. CREATEDB, plus ownership or sufficient privileges for database renames, drops, and optional backend termination.- Go 1.26 or newer when building from source. The resulting binary does not require Go,
libpq, orpsql.
Build from the repository root:
make build
./bin/pgb versionInitialize a reusable connection profile once:
pgb init
# or
pgb init personalThe command prompts for host, port, user, SSL mode, and an optional password, then tests a connection before saving anything. Administrative operations always connect to postgres; this is not configurable.
Profiles use PostgreSQL's native files:
| Platform | Service profiles | Passwords |
|---|---|---|
| macOS/Linux | ~/.pg_service.conf |
~/.pgpass |
| Windows | %APPDATA%\postgresql\.pg_service.conf |
%APPDATA%\postgresql\pgpass.conf |
Passwords are never accepted as command-line flags or stored in pgb's project registry. On Unix, password files are written with mode 0600. Existing unrelated profile entries, password entries, and comments are preserved.
Use a saved non-default profile with --profile personal. For automation, --url accepts a one-command connection override and is never persisted by pgb itself. A credential-bearing URL can still be visible to the current process environment or process launcher, so saved profiles are preferable for interactive use.
Mutating operations only accept loopback hosts and Unix sockets by default. --allow-remote is an explicit escape hatch; it should only be used for a server you intend to modify.
Adopt an existing database:
pgb project init --database myapp_dev --mode checkout --branch mainInside a Git worktree, --branch defaults to the current Git branch. Outside Git, identify the project explicitly on every command:
pgb --project myapp project init \
--database myapp_dev \
--mode checkout \
--branch mainCreate and select branches:
pgb branch feature/login
pgb list
pgb checkout feature/loginThe application continues to connect to myapp_dev. It must disconnect before checkout and reconnect afterward. If sessions are still connected, pgb refuses without making changes:
pgb checkout feature/login --force--force explicitly authorizes pgb to terminate sessions on the affected databases. The two database renames occur in one PostgreSQL transaction.
First ensure the chosen dotenv file is ignored by Git:
.env.localThen initialize the project and its narrow dotenv adapter:
pgb project init \
--database myapp_dev \
--mode worktree \
--branch main \
--env-file .env.local \
--env-key DATABASE_URLCreate and attach a database branch:
pgb branch feature/login --from main
pgb attach feature/loginattach changes exactly the configured key, preserves unrelated lines and comments, rejects duplicate definitions, and refuses to write a file Git does not report as ignored.
For a file-free workflow:
pgb run feature/login -- ./bin/devThe child receives the configured connection variable and PGDATABASE. The parent environment is unchanged, arguments are executed directly without shell interpolation, and child exit status is propagated.
pgb list
pgb list --all-databases
pgb drop old-branchInteractive drop requires typing the exact logical branch label. Non-interactive use requires --yes:
pgb drop old-branch --yes
pgb drop old-branch --force --yesThe active checkout branch, the project's only branch, unregistered databases, and PostgreSQL's postgres, template0, and template1 databases cannot be dropped through pgb.
Project registries are non-secret JSON files below the platform's user configuration directory (os.UserConfigDir()). Git projects are keyed by the canonical Git common directory, so linked worktrees share one registry. Database branch identity uses PostgreSQL OIDs, which remain stable across renames.
Before every mutation, pgb checks the registry against pg_database. Project mutations are serialized with a PostgreSQL session advisory lock, and local registry files are replaced atomically.
Each database branch is a full physical copy. Expect approximately the source database's size in additional disk usage. pgb currently has no copy-on-write storage, merge operation, snapshot retention, or rollback history.
PostgreSQL database-level grants and ALTER DATABASE settings are not copied by CREATE DATABASE ... TEMPLATE .... Roles are cluster-wide and remain available on database branches.
make test
make test-race
make buildThe integration suite expects a disposable PostgreSQL server and intentionally creates only test-prefixed databases:
PGB_TEST_HOST=localhost \
PGB_TEST_PASSWORD=pgbtest \
make test-integrationThe checked-in integration test exercises profile setup, project adoption, active-session refusal and forced termination, cloning, checkout, listing, guarded deletion, dotenv attachment, and child-process environment selection.