| name | use-sqlmigrate |
| description | Database migration tools for Go projects. Use when writing migrations, running sql-migrate CLI, embedding migrations in Go apps, or setting up new database schemas. Covers PostgreSQL, MySQL/MariaDB, SQLite, SQL Server. |
| depends | ["go-stack"] |
Overview
sqlmigrate is a feature-branch-friendly SQL migration system with two modes:
- CLI (
sql-migrate) — generates shell scripts that pipe to sh
- Go library (
sqlmigrate + backend) — embed migrations in Go binaries
Both use the same migration file format and _migrations tracking table.
Focused skills
| Skill | When to use |
|---|
use-sql-migrate-cli | CLI tool: init, create, up, down, sync, status |
use-sql-migrate-golang | Go library: embed migrations, Migrator interface, auto-migrate on startup |
use-sql-migrate-postgres | PostgreSQL: pgx connection, schema multi-tenancy, PGOPTIONS |
use-sql-migrate-mysql | MySQL/MariaDB: multiStatements DSN, MY_CNF, mariadb vs mysql |
use-sql-migrate-sqlite | SQLite: foreign keys pragma, modernc.org/sqlite driver |
use-sql-migrate-sqlserver | SQL Server: sqlcmd, TDS 8.0 encryption, SQLCMD* env vars |
Migration file format
<yyyy-mm-dd>-<number>_<name>.<up|down>.sql
2026-04-05-001000_create-todos.up.sql
2026-04-05-001000_create-todos.down.sql
- Numbers increment by 1000 (allows inserting between)
- Initial migration:
0001-01-01-001000_init-migrations
- Each
.up.sql MUST end with INSERT INTO _migrations (name, id) VALUES ('<name>', '<8-hex-id>');
- Each
.down.sql MUST end with DELETE FROM _migrations WHERE id = '<8-hex-id>';
Key design decisions
- Feature-branch friendly: no sequential numbering, no conflicts
- ID-based matching: migrations matched by 8-char hex ID, not name — safe to rename
- Shell-first CLI: generates reviewable scripts, never executes directly
- Separate Go modules: each backend is its own module to avoid pulling unnecessary drivers