Menu
sql-migrate CLI tool for database migrations. Use when initializing migrations, creating migration files, running up/down, checking status, or generating migration scripts. Covers psql, mariadb, mysql, sqlite, sqlcmd.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
PostgreSQL migrations with sql-migrate and pgmigrate. Use when setting up PostgreSQL migrations, schema multi-tenancy, or pgx connection for migrations.
Embed SQL migrations in Go applications using sqlmigrate library. Use when writing Go code that runs migrations on startup, implements auto-migrate, or uses the Migrator interface. Covers pgmigrate, mymigrate, litemigrate, msmigrate.
MySQL and MariaDB migrations with sql-migrate and mymigrate. Use when setting up MySQL/MariaDB migrations, configuring multiStatements, or MY_CNF credentials.
SQLite migrations with sql-migrate and litemigrate. Use when setting up SQLite migrations, configuring foreign keys, or using modernc.org/sqlite driver.
SQL Server migrations with sql-migrate and msmigrate. Use when setting up SQL Server migrations, configuring sqlcmd, TDS 8.0 encryption, or SQLCMD environment variables.
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.
| name | use-sql-migrate-cli |
| description | sql-migrate CLI tool for database migrations. Use when initializing migrations, creating migration files, running up/down, checking status, or generating migration scripts. Covers psql, mariadb, mysql, sqlite, sqlcmd. |
| depends | ["use-sqlmigrate"] |
webi go
go install github.com/therootcompany/golib/cmd/sql-migrate/v2@latest
sql-migrate -d ./sql/migrations/ init --sql-command <psql|mariadb|mysql|sqlite|sqlcmd>
Creates: migrations directory, 0001-01-01-001000_init-migrations.{up,down}.sql,
migrations.log, _migrations.sql query file.
MUST: Run the generated init script to create the _migrations table:
sql-migrate -d ./sql/migrations/ up | sh
sql-migrate -d ./sql/migrations/ create add-user-tables
Generates a canonically-named up/down pair with a random 8-hex-char ID:
2026-04-09-001000_add-user-tables.up.sql
2026-04-09-001000_add-user-tables.down.sql
If files for today already exist, the number increments by 1000.
# apply ALL pending migrations
sql-migrate -d ./sql/migrations/ up | sh
# apply next 2 pending
sql-migrate -d ./sql/migrations/ up 2 | sh
# roll back 1 (default)
sql-migrate -d ./sql/migrations/ down | sh
# roll back 3
sql-migrate -d ./sql/migrations/ down 3 | sh
Output is a shell script. Review before piping to sh.
sql-migrate -d ./sql/migrations/ status
Shows applied (reverse order) and pending migrations. Does not execute anything.
sql-migrate -d ./sql/migrations/ sync | sh
Reloads migrations.log from the database. Run after upgrading sql-migrate.
sql-migrate -d ./sql/migrations/ list
Lists all up/down migration files found.
| Flag | Default | Purpose |
|---|---|---|
-d <dir> | ./sql/migrations/ | Migrations directory |
--sql-command | psql | SQL command template (init only) |
--migrations-log | ../migrations.log | Log file path relative to migrations dir (init only) |
| Alias | Expands to |
|---|---|
psql, postgres, postgresql, pg, plpgsql | psql "$PG_URL" -v ON_ERROR_STOP=on --no-align --tuples-only --file %s |
mariadb | mariadb --defaults-extra-file="$MY_CNF" --silent --skip-column-names --raw < %s |
mysql, my | mysql --defaults-extra-file="$MY_CNF" --silent --skip-column-names --raw < %s |
sqlite, sqlite3, lite | sqlite3 "$SQLITE_PATH" < %s |
sqlcmd, mssql, sqlserver | sqlcmd --exit-on-error --headers -1 --trim-spaces --encrypt-connection strict --input-file %s |
Custom commands: pass any string with %s as the file placeholder.
Stored in the initial migration file as comments:
-- sql_command: psql "$PG_URL" -v ON_ERROR_STOP=on --no-align --tuples-only --file %s
-- migrations_log: ../migrations.log
These are read by the CLI on every run. Edit them to change the sql command or log path.