Skip to content
peterorPublic

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

1 Commit

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

pgb

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 checkout atomically 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 attach updates one configured Git-ignored dotenv key, while pgb run injects 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.

Requirements

  • PostgreSQL 14 or newer.
  • Permission to connect to the standard postgres database.
  • 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, or psql.

Build from the repository root:

make build
./bin/pgb version

Connection setup

Initialize a reusable connection profile once:

pgb init
# or
pgb init personal

The 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.

Checkout mode

Adopt an existing database:

pgb project init --database myapp_dev --mode checkout --branch main

Inside 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 main

Create and select branches:

pgb branch feature/login
pgb list
pgb checkout feature/login

The 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.

Worktree mode

First ensure the chosen dotenv file is ignored by Git:

.env.local

Then 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_URL

Create and attach a database branch:

pgb branch feature/login --from main
pgb attach feature/login

attach 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/dev

The 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.

Inspection and deletion

pgb list
pgb list --all-databases
pgb drop old-branch

Interactive drop requires typing the exact logical branch label. Non-interactive use requires --yes:

pgb drop old-branch --yes
pgb drop old-branch --force --yes

The active checkout branch, the project's only branch, unregistered databases, and PostgreSQL's postgres, template0, and template1 databases cannot be dropped through pgb.

Storage and consistency

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.

Development

make test
make test-race
make build

The integration suite expects a disposable PostgreSQL server and intentionally creates only test-prefixed databases:

PGB_TEST_HOST=localhost \
PGB_TEST_PASSWORD=pgbtest \
make test-integration

The 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.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages