seqwall

Seqwall is a tool for PostgreSQL migrations testing.
Ensure that every migration is reversible, idempotent, compatible with others in sequence, structurally sound and verifiable.

📦 Installation

Docker images

Package: https://github.com/realkarych/seqwall/pkgs/container/seqwall.

docker run --rm --network=host \
  ghcr.io/realkarych/seqwall:latest staircase --help

Homebrew (macOS & Linux)

brew tap realkarych/tap
brew install seqwall        # first install
brew upgrade seqwall        # later updates

Debian / Ubuntu (APT)

# Import the GPG key
curl -fsSL https://realkarych.github.io/seqwall-apt/public.key \
  | sudo tee /etc/apt/trusted.gpg.d/seqwall.asc

# Add the repository
echo "deb [arch=$(dpkg --print-architecture)] \
  https://realkarych.github.io/seqwall-apt stable main" \
  | sudo tee /etc/apt/sources.list.d/seqwall.list

# Install / update
sudo apt update
sudo apt install seqwall          # first install
sudo apt upgrade  seqwall         # later updates

Other distros / Windows

Download the pre‑built archive from the Releases page, unpack, add the binary to your PATH.

On Windows, you may need Unblock-File .\seqwall.exe before first run.

Go install (Go ≥ 1.17)

go install github.com/realkarych/seqwall@latest
# make sure $GOBIN (default ~/go/bin) is on your PATH

✅ Once installed, verify it works

❯ seqwall staircase --help
Launch staircase testing

Usage:
  seqwall staircase [flags]

Flags:
      --postgres-url string           PostgreSQL URL (required or fallback: $DATABASE_URL environment variable)
      --migrations-path string        Path to migrations. Migrations must be in lexicographical order (required)
      --upgrade string                Shell command that applies next migration (required)
      --downgrade string              Shell command that reverts current migration (required)
      --migrations-extension string   Extension of migration files (default: .sql)
      --schema stringArray            Schemas to test (default [public])
      --test-snapshots                Compare schema snapshots. If false, only checks fact that migrations are applied
                                      / reverted with no errors (default true)
      --depth int                     Depth of staircase testing (0 = all)
      --help                          help for staircase

🧬 Methodology & Core Principles

Migrations are contracts

Each migration must be reversible and must not break the schema if applied, reverted, and reapplied.

Snapshots reveal the truth

After each migration, Seqwall captures the schema using information_schema views, adhering to the ISO/IEC 9075-11 SQL standard.

This includes tables, columns, constraints, indexes, views, triggers, functions, enums, sequences, and foreign keys. The snapshots are then compared using structured diffs, allowing detection of even subtle schema differences or mismatches.

Staircase testing guarantees schema consistency

We use a 3-phase strategy:

1. actualize — applying all migrations and captures etalon schema snapshot for each migration.

2. down → up → down — starting from the latest migration, step backwards:

   • downgrade one migration,
   • upgrade it again,
   • then downgrade once more (down step).
   • At each step, the schema is compared with previously captured etalon snapshots — both before and after — ensuring reversibility and no drift.

3. re-actualize — starting from the lower point reached in step 2 (after several rollbacks):

   • re-apply each migration one by one
   • compare each re-applied migration with etalon

This ensures that the migration chain is robust in both directions, even when recovering from mid-chain downgrades.

Standalone by design

Seqwall is a single-purpose CLI tool — it requires no server, no daemon, no embedded framework, and no special runtime.

You can run it locally or in CI/CD (recommended), with just your migrations and a database connection string. No vendor lock-in, no config-files, no dependencies beyond PostgreSQL.

Test migrations as they really run

Seqwall runs your actual migration scripts and commands — no wrapper DSLs, no abstractions, no mocks.

You bring your own migration runner (dbmate, alembic, goose, sqlx, atlas, etc.). Seqwall just executes shell commands.

Limitations & Scope

Does this mean Seqwall is the only tool you need for testing migrations?

No — databases involve a spectrum of concerns, and a complete testing strategy should include:

• Load testing — to observe performance & regressions
• Lock behavior analysis — to catch deadlocks and blocking issues
• Data state testing — to ensure data survives or transforms as expected
• Static analysis — to catch anti-patterns or unsafe operations before runtime
• Integration tests — to validate application logic against migrated schemas
• ...

Seqwall focuses on schema-level structural correctness — nothing more, nothing less.

🙏 Contribution

Found a bug?

• Please open an issue with a clear description, reproduction steps (if possible), and expected vs. actual behavior.

Have a question?

• Please open a discussion in QA section. Or feel free to message me on Telegram: @karych.

Want to suggest a feature?

• If you have a concrete and well-scoped idea — feel free to open a feature request.
• If the idea is more exploratory — start a discussion instead.

Ready to contribute code?

• Look for issues marked with help wanted or good first issue. In fact, you can pick any issue without Assignees 😊️️️️️️.
• Fork the repo, create a branch, and open a pull request when ready (and tag @realkarych for review).

Your feedback and contributions are always welcome 💙.