Idempotent Schema Management with sqldef v4.0

The Pitch

Sqldef synchronises your database schema state using plain SQL DDL instead of a proprietary DSL. It appeals to engineers who want to declare a desired state and let a diff engine handle the reconciliation across MySQL, PostgreSQL, SQLite, or SQL Server (Official Docs).

Under the Hood

Takashi Kokubun, a Ruby Core committer, maintains the project, which recently hit version 4.0 in late 2025 (GitHub). This release introduced a critical change by making --dry-run the default mode to prevent accidental data loss during schema application (GitHub Release #1094).

The tool integrates with modern LLM workflows, specifically including commands for 'Claude Code' automated reviews (GitHub Issue #1048). This allows teams to automate the validation of generated diffs within their CI/CD pipelines using these integrated review features.

However, the diff engine is purely structural and does not handle complex data-motion migrations. If you need to populate a new non-nullable column with existing data before applying a constraint, sqldef will not orchestrate those intermediate steps (HN 2026).

Further technical debt exists for PostgreSQL users following the removal of the libpg_query fallback parser in v4. Certain niche PG-specific syntax might now trigger parsing errors if not supported by the core internal parser (GitHub v4-migration.md).

We don't know yet if the project will ever offer enterprise support, as it remains strictly community-driven. There is also no public roadmap regarding native support for "online" migrations that move data between columns or tables (UsedBy Dossier).

Marcus's Take

Sqldef is the correct choice for teams who refuse to learn another abstraction like Prisma's DSL or Atlas's HCL. It is reliable for standard schema synchronisation, provided you manually handle data backfills for complex transitions. Use it in production for standard services, but do not trust the diff engine blindly with DROP statements in high-stakes environments.

Ship clean code,
Marcus.