Disclaimer: Built with Claude Code
Introducing azsql-migration-test, a small open-source CLI that validates your Azure SQL Database migrations against a local Azure SQL Database Developer container — the same engine as the cloud, running on your machine.
The problem: proving a migration works shouldn’t require the cloud
If you run Azure SQL Database, you want to know a schema migration will succeed before you apply it in production. But the honest way to be sure has always meant testing against a live Azure SQL Database — which means a subscription, cloud spend, and slow round-trips every time you tweak the migration.
So validation gets rushed, done once instead of continuously, or skipped until staging — and the surprises show up late, mid-release, when they’re most expensive.
What’s been missing is a way to validate a migration against the actual Azure SQL Database engine, locally, repeatably, and for free.
What it is
Azure SQL Developer is the Azure SQL Database engine packaged as a local container. It’s the real thing running on your laptop — what works there deploys seamlessly to Azure SQL Database. More info on SQL Database Developer can be found here. Youtube Demo provided by MSFT can be found here.
azsql-migration-test automates the validation loop against it:
- Pull and start the Developer container.
- Extract your source schema (with sqlpackage).
- Deploy it into the container — the real compatibility test: if the engine won’t accept the schema, the deploy fails and so does validation.
- Replay your queries against the deployed schema.
- Tear everything down.
No cloud account. No cloud cost. Zero-to-answer in a couple of minutes — and because it’s the same engine you deploy to, a clean pass means a clean deploy.
The three commands
validate — the full pass
Extract the source schema, deploy it into the container (the compatibility test), then replay your queries against it:
azsql-migration-test validate
--source "Server=;Database=;User Id=;Password="
--queries ./queries.sql? Schema deployed to Azure SQL Database Developer (compatible)
? Query replay complete: 12 passed, 0 failed
Migration validation completed successfully
If the schema is rejected or a query fails, it exits non-zero — so it drops straight into a script or a CI job.
compare — a non-destructive deployment dry-run
Report exactly what deploying your schema would do — every operation sqlpackage would run against the Azure SQL Database engine — without applying anything:
azsql-migration-test compare
--source "Server=;Database=;User Id=;Password="? Schema comparison complete
You get a report.md summary and the raw schema-diff.xml:
Schema
Changes: 4 (breaking: false)
DeployReport: schema-diff.xml
Against a fresh target this is the full create plan; against a database that already has a schema (e.g. from a prior validate --keep) it’s the incremental diff — creates, alters, and drops. It exits non-zero when the plan contains a breaking operation — a drop or a data-loss alert — so it makes a clean pre-merge gate.
It exits non-zero when the diff contains a breaking operation — a drop or a data-loss alert — so it makes a clean pre-merge gate.
replay — run a query set
Run a set of GO-separated batches against a database and get per-batch pass/fail and timing:
azsql-migration-test replay --queries ./smoke.sql --database MyDb? Query replay complete: 8 passed, 0 failed
A failing batch exits non-zero and the SQL error is captured in the report:
[FAIL] SELECT * FROM dbo.Orders_old; (168ms)
Msg 208, Level 16, State 1 — Invalid object name 'dbo.Orders_old'.
Where it fits: use cases
- A pre-deploy gate on your laptop. Before you open the PR, confirm the migration will be accepted by the Azure SQL Database engine.
- A CI/CD check. Every command exits non-zero on failure, so you can wire it into a pipeline that blocks a merge or a deploy on a migration that won’t apply.
- Repeatable validation across a migration project. Instead of a one-time cloud assessment, re-run it on every change — locally, for free.
- Vetting third-party or generated migration scripts. Point it at a schema you didn’t write and see whether the engine accepts it before it reaches production.
- Fast iteration. Change the migration, re-validate in a couple of minutes, no cloud round-trip.
Honest about what it does
Good tooling tells you where it stops. The breaking-change flag is derived from the sqlpackage DeployReport (drops and data-loss alerts); the full XML report is always written, so you can inspect the deployment plan yourself. As with any pre-deploy check, keep your normal staged rollout — but you’ll catch the schema problems that otherwise surface at deploy time, right on your laptop.
Try it in two minutes
Download a binary from the latest release (https://github.com/MarlonRibunal/azsql-migration-test/releases) (each ships with checksums), or:
go install github.com/MarlonRibunal/azsql-migration-test@latestPoint it at an Azure SQL Database Developer container image you have access to (and its registry credentials, if needed) via environment variables, then run validate. Full quickstart and flags are in the README (https://github.com/MarlonRibunal/azsql-migration-test#readme).
You’ll need Docker and sqlpackage on your PATH. (sqlcmd runs inside the container, so you don’t need it on the host.)
Contribute — it’s small on purpose
azsql-migration-test is a compact, dependency-free Go CLI. That’s deliberate: it’s easy to read, easy to build, and easy to contribute to. If you work with Azure SQL migrations, there’s low-hanging fruit here:
- Richer DeployReport parsing and smarter breaking-change classification.
- A first-class GitHub Action wrapper for the CI use case.
- More output formats (JSON, SARIF) for pipeline integration.
- Real-world schema fixtures and edge cases worth validating against.
Issues and PRs are welcome — see CONTRIBUTING (https://github.com/MarlonRibunal/azsql-migration-test/blob/main/CONTRIBUTING.md). If it saved you a bad deploy, a 
on the repo helps others find it.
? https://github.com/MarlonRibunal/azsql-migration-test
azsql-migration-test is an independent, community project. It is not affiliated with, endorsed by, or sponsored by Microsoft. “Azure” and “Azure SQL Database” are trademarks of Microsoft Corporation.
The post Introducing azsql-migration-test: Test and Validate Azure SQL Database Migrations first appeared on SQL, Code, Coffee, Etc..