Announcing Swellow v0.2.0: The SQL-First Migration Tool

sql
migration
database
python
SQL-first migrations
Published

February 15, 2026

Take flight with swellow!

I’m excited to introduce swellow, the simple, SQL-first CLI tool for managing database migrations, now reaching its v0.2.0 milestone!

What is swellow?

Imagine you’re an amateur bird watcher who’s built a simple database to track all the feathered friends you’ve spotted in the wild. At first, your birds table just included common names (like the swallow). But as you dive deeper into ornithology, you decide to add scientific names for precision and credibility.

So, you update the schema: rename the old name column to common_name and add a new latin_name column. Straightforward enough in a single database, right?

ALTER TABLE bird_watch.birds
RENAME COLUMN name TO common_name;

ALTER TABLE bird_watch.birds
ADD COLUMN latin_name VARCHAR(255);

Now, let’s say your hobby has evolved - you’re collaborating with a birding club and want to share your database. You maintain a local development version on your laptop for experimenting, a staging environment for testing updates with a small group, and a production setup hosted in the cloud for everyone to access. Applying these schema changes manually across all these environments would be a nightmare: time-consuming, and prone to errors and inconsistencies (like accidentally renaming a column twice and breaking queries!).

This is where swellow swoops in to make your life easier. It treats your SQL queries as the source of truth for database migrations - simply organize your migration scripts in a dedicated directory within your repository (e.g., migrations/), and swellow handles the rest. It maintains a lightweight records table in each database to track which migrations have already been applied in that environment.

  • Ran your CI pipeline twice by accident? No sweat - swellow skips duplicates to avoid errors like “column already exists”.
  • Need to rollback a faulty change? Just write a plain SQL rollback script, add it to your migrations, and let swellow execute it safely.
  • Deploying to multiple environments? swellow ensures consistent, idempotent migrations without manual tracking or custom scripting.

Why swellow 🐦‍⬛?

If you can write SQL for your database, you already know how to use swellow.

Most migration tools force you to learn a complex DSL, hide logic behind abstractions, or generate SQL that you never get to see. swellow takes a different approach. It acts as a thin wrapper over your database engine.

  • ❌ No generated SQL.
  • ❌ No implicit transformations.
  • ✅ Migrations are just plain SQL files.

If you can write SQL for your database, you already know how to use swellow.

What runs in production is exactly what you wrote in your migration directory. This makes swellow transparent, predictable, and safe - because knowing exactly what runs against your data matters more than convenient abstractions.

What’s New in swellow v0.2.0?

⚡ Data Lake Support: Databricks, Delta & Iceberg

v0.2.0 adds support to leading data lake catalogs in the industry: Databricks, Delta and Iceberg. It does so by integrating a lightweight Spark Connect client, allowing you to manage migrations for Delta Lake and Apache Iceberg tables via Spark runtimes.

New --engine argument supports postgres, spark-delta, spark-iceberg, and databricks-delta!

📸 Database Snapshots

You can now baseline your database schema using the snapshot command. Snapshots are automatically versioned alongside your standard migrations. This should make it extremely easy to change over to swellow.

📄 JSON Interface

You can now use the --json flag to output machine-readable logs, perfect for integrating swellow into your own CI/CD tooling.

🔒 Concurrency & Safety

  • Locking: swellow manages a concurrency lock to prevent multiple migration processes from running simultaneously, even in databases that don’t support locking.
  • Transaction Control: Added a --no-transaction flag for engines or specific operations that cannot run inside a transaction block. You can now CREATE DATABASE in PostgreSQL with swellow!
  • Error Handling: Removed usage of panicking APIs across the codebase to ensure graceful failures instead of panics.

🛠️ Quality of Life Improvements

  • Zero-Padding: Migration versions are now standardized with zero-padding (e.g., 000123), making directory sorting predictable.
  • Metadata Table: Refactored internal tracking to use swellow.records instead of swellow_records, leaving the swellow schema reserved for future use.

What’s Next for swellow?

  • More Database Support: We’re working on adding support for other data platforms, including Snowflake.
  • Dynamic Migrations: We’re exploring ways to support more dynamic migration patterns and templating while maintaining the SQL-first philosophy.

What’s Next for You?