supabase/pg-toolbelt

README

pg-toolbelt

Monorepo for Supabase PostgreSQL tooling.

Packages

Package	Description	npm
`@supabase/pg-delta`	PostgreSQL schema diff and migration tool
`@supabase/pg-topo`	Topological sorting for SQL DDL statements

Documentation

Start at docs/, which routes by what you need:

I want to…	Read
Use it — CLI and programmatic API	docs/getting-started.md
Understand why the engine was rebuilt	docs/overview.md
Understand how it works	docs/architecture/README.md
Work on it	docs/architecture/onboarding.md
Know what it models and excludes	packages/pg-delta/COVERAGE.md
See what's next	docs/roadmap/

Development

Prerequisites

Bun (latest)
Docker (for integration tests)
Node.js >= 20 (for TypeScript compilation)

Setup

bun install

Commands

bun run build           # Build all packages
bun run test            # Test all packages
bun run test:pg-delta   # Test pg-delta only
bun run test:pg-topo    # Test pg-topo only
bun run coverage        # Test coverage report (all packages)
bun run check-types     # Type check all packages
bun run format-and-lint # Format and lint all code

Test coverage

bun run coverage runs both packages' suites with Istanbul instrumentation and writes an HTML/lcov report to .coverage-artifacts/ (open .coverage-artifacts/index.html). Docker is required (the suites use testcontainers).

bun run coverage                               # everything (unit + integration + corpus)
bun run coverage --unit-only                   # skip pg-delta's slow integration + corpus suites
bun run coverage --pg-image postgres:17-alpine # pin the PostgreSQL image for pg-delta
bun run coverage --skip-tests                  # regenerate the report from the last run

New code is expected to come with test coverage — see CONTRIBUTING.md.

Working with individual packages

# pg-delta
cd packages/pg-delta
bun run test src/       # Unit tests only
bun run test tests/     # Integration tests only (requires Docker)

# pg-topo
cd packages/pg-topo
bun run test            # All tests (requires Docker)

Releasing

This monorepo uses changesets for versioning.

bunx changeset          # Create a changeset
bun run version         # Apply changesets to update versions
bunx changeset publish  # Publish to npm

Contributing

See CONTRIBUTING.md before opening a pull request.

Open an issue first.
Wait for a maintainer to triage it and add the open-for-contribution label.
Then open a pull request that links the issue (for example Closes #123).

Use ISSUES.md for issue-writing guidance, especially for pg-delta reproductions.

License

PostgreSQL License