godwit

The bar-tailed godwit holds the world record for the longest non-stop migration: ~13,500 km without landing. Your database migrations should be as reliable.

godwit is a crash-safe PostgreSQL migration service for pipelines. Migrations are plain SQL files; they run under a statement-level journal in the target database, so a replica killed mid-run is taken over by another and resumed from the last committed statement. There is no dirty state and no repair. Apache 2, PostgreSQL only, one binary that is both the service and the CLI.

Flyway, Liquibase and Atlas moved undo, dry runs, lint and drift detection behind paid tiers, and none of them is a service: every pipeline rebuilds the same glue around a CLI. godwit is that glue done once. The honest side-by-side, including what godwit lacks, is in docs/start/comparison.md.

Three things that are actually different

The journal is in the target database, committed with the DDL. A tx statement and its done row commit together; a CREATE INDEX CONCURRENTLY gets a write-ahead intent and a verifier that inspects pg_index after a crash; a backfill commits its rows and its cursor in the same transaction. So kill -9 at any point leaves a state the next attempt can read and continue from, and nothing has to be repaired by hand. The point-by-point crash timeline is in the journal page.

A directive is a change godwit executes, not a recipe it prints. A -- godwit: comment line says what the migration wants; godwit renders the lock-safe statements against the target's own catalog at plan time — the real primary key, column type and nullability — and freezes them onto the plan, so the run applies what the pull request showed:

-- 20260901121000_customer_id_text.up.sql
-- godwit: change-type orders.customer_id text using='customer_id::text'
-- godwit: assert 'SELECT count(*) FROM orders WHERE customer_id IS NULL' = 0

$ godwit plan --target app --dir db/migrations --rollout expand-contract
1 migration will be applied to app. This runs in two halves. Now, godwit applies only what adds: new
columns, indexes and constraints, which the application it is already running does not have to know
about. A generated column change writes into a new column and holds the two in step with a trigger, so
writes never stop while it fills. Nothing is renamed and nothing is dropped yet. When you confirm,
godwit runs the rest: the renames, and the drops it held back. Until you confirm, the old columns are
still there holding the data you started with, and that is the way back. The run waits at
awaiting_contract; confirm it with godwit confirm on the pull request.

godwit will perform the following actions:

  # 20260901121000_customer_id_text  (written by a directive)
  -- godwit: change-type orders.customer_id text using='customer_id::text'
  -- godwit: assert 'SELECT count(*) FROM orders WHERE customer_id IS NULL' = 0
  ~ table "public"."orders" {
      ~ customer_id     = bigint -> text
      + customer_id_old = bigint NOT NULL
        # (3 unchanged attributes hidden)
    }
  note: leaves public.orders.customer_id_old for rollback; drop it with `-- godwit: drop-column public.orders.customer_id_old`

Plan: 0 to add, 1 to change, 0 to destroy.

That is fourteen statements. --plan-format statements prints them: the trigger keeps both columns in sync while the batches walk the table, the batches resume from their journalled cursor after a crash, one statement is godwit's own count of the rows the backfill has still to reach so a using= that never converges cannot become the irreversible swap, and the rename waits in awaiting_contract — where the count is asked again — until a human confirms it. Ten operations exist; everything godwit will not do safely is refused by name. directives.

The plan is a contract, and it applies before the merge. godwit plan --target --save stores the admitted plan with an observation of the live target; migrate binds to that plan and refuses with the exact diff when the target moved underneath. On a pull request the GitHub Action turns that into: lint and plan as a sticky comment, godwit apply bound to the reviewed plan, godwit confirm for the contract phase, and a godwit/applied commit status that stays pending until the whole migration is on the database. By the time the branch lands, main describes a schema the target already has. plans, the GitHub Action.

Quickstart

go install github.com/SamuelMolling/godwit/cmd/godwit@main   # needs gcc (libpg_query) and Go 1.26
docker pull ghcr.io/samuelmolling/godwit:main               # or the image: linux/amd64 + arm64, distroless

# the service's own store, and a database to migrate
psql -U postgres \
  -c "CREATE ROLE godwit LOGIN PASSWORD 'godwit' CREATEDB" \
  -c "CREATE DATABASE godwit_store OWNER godwit" \
  -c "CREATE ROLE app LOGIN PASSWORD 'app'" \
  -c "CREATE DATABASE app OWNER app"

export GODWIT_MASTER_KEY=$(openssl rand -hex 32) GODWIT_TOKENS='admin:admin:s3cret'
godwit serve --store-dsn postgres://godwit:godwit@localhost/godwit_store &

export GODWIT_SERVER=http://localhost:8474 GODWIT_TOKEN=s3cret
godwit target add app --provider static --dsn postgres://app:app@localhost/app
godwit lint --dir db/migrations                     # hazards, parse errors, malformed directives
godwit plan --target app --dir db/migrations        # what would run, against the live target (--save stores it)
godwit migrate --target app --dir db/migrations     # streams the run; exit 0 when applied
godwit target status app --dir db/migrations

That single-server form executes submitted SQL on the store server as the store role, which is why it needs CREATEDB and why serve warns about it on every start. Anywhere a token is shared, add --scratch-dsn pointing at a PostgreSQL that holds nothing (security). The full walkthrough — the local up/status/down loop with no service at all, writing a migration from an ORM schema, and the first CI step — is docs/start/getting-started.md.

What's inside

Documentation

The manual is docs/, grouped by what you are doing.

Also: examples (copy-ready pipelines), examples/deploy (the service on ingress-nginx, ECS, Docker Compose and a plain VM), deploy/helm/godwit, deploy/argocd, the two-replica crash demo, and AGENTS.md for contributors.

Design principles

1. The journal is the truth. Progress lives in the target database, committed with the DDL.
2. Plain SQL. Any stack can produce it; godwit runs it.
3. Roll forward. Down migrations are required, but the production path is expand → contract, and godwit schedules the contract.
4. Safety is not a paid tier.

Status

v1 in progress: PostgreSQL only, API-first. Version stays 0.0.1 until v1 has run in production — nothing here has.

make all (lint, proto lint, the suites at 100% statement coverage, build) is the gate on every commit. Outside it, make e2e drives the built binary against PostgreSQL in Docker while SIGKILLing replicas mid-statement, make load measures a ten-million-row backfill and a thousand-migration target, and make chaos kills godwit in the gaps the crash rig cannot reach. Their numbers and knobs are in docs/internals/testing.md.