pgsync

Fast PostgreSQL prod→local sync for developers. Cross-platform single binary.

Status: Phase 4 of 4 complete (embedded pg_tools scaffolding, benchmarks, release pipeline, updater). MVP implementation is in place.

Phases

• ✅ Phase 1 — Foundation: repo, CI with strict 100% coverage, config (TOML + validators), runner/clock/fsx interfaces, logger, models, proxy tunnel, pgschema (FK graph + closure), pgtools locator.
• ✅ Phase 2 — Native engine + CLI sync: pgx-backed pipeline, cobra commands, NDJSON output, integration tests on testcontainers.
• ✅ Phase 3 — TUI + ConfigEditor + NDJSON hardening: default TUI entrypoint, config commands, TUI state machine shell, redacted config display, diagnostic command routing.
• ✅ Phase 4 — Embed pg_tools + bench suite + release pipeline: pgtools manifest/scripts, embedded locator/cache, benchmark scaffold, release workflow, updater client.

See design spec, Phase-1 plan, and Phase-2 plan.

Interactive usage

pgsync          # launch full-screen TUI
pgsync tui      # launch TUI explicitly
pgsync config   # open config editor flow
pgsync config show
pgsync config path

Config is managed by pgsync config and the TUI; the TOML file is internal storage.

CLI sync usage

Release builds use embedded PostgreSQL 18 client tools by default. --use-system-pgtools is an explicit escape hatch when you want pg_dump / pg_restore from PATH instead.

pgsync --config ~/.config/pgsync/config.toml sync my_database --threads=8
pgsync --config ~/.config/pgsync/config.toml sync my_database --use-system-pgtools
pgsync --config ./ci-pgsync.toml --output=json sync my_database  # NDJSON
pgsync sync my_database --tables users,orders --dry-run
pgsync doctor --output=json
pgsync upgrade --check-only

When the database name is not provided via [remote] database / [local] database in the config, --remote-database / --local-database flags, PGSYNC_REMOTE_DATABASE / PGSYNC_LOCAL_DATABASE env vars, or a positional pgsync sync <db> argument, pgsync resolves it from Infisical: it walks up from the current working directory to find .infisical.json, runs infisical export --env=dev --format=dotenv --silent, and extracts the DB name from POSTGRES_URL (path component) or DB_DATABASE. Requires infisical on $PATH and an active infisical login. Fails fast with an actionable message if either is missing.

Build / dev

make help             # list targets
make test             # unit tests with coverage
make coverage-gate
make lint
make test-integration # requires Docker and cgo/toolchain for -race
make build
make pgtools-prepare-release # stage verified embedded PostgreSQL tools
make release-local VERSION=v0.0.0-dev
make bench

For release packaging, platform payloads are fetched from conda-forge PostgreSQL packages into internal/engine/pgtools/bin/<platform>/; packaging fails if pg_dump / pg_restore are missing.

CI and releases

Every push runs build, lint, unit, race, coverage-gate, and integration jobs through GitHub Actions. After CI passes on main, .github/workflows/version-bump.yml computes the next semantic version, updates VERSION, creates a vX.Y.Z tag, and pushes it. Tags trigger .github/workflows/release.yml, which builds release artifacts with version metadata and publishes a GitHub Release.

See docs/release.md for the release checklist and docs/versioning.md for bump rules.

License

MIT — see LICENSE.