golang-migrate
Database migration library and CLI for Go supporting 20+ databases including PostgreSQL, MySQL, SQLite, MongoDB, CockroachDB, and cloud databases. Migrations are versioned SQL or Go files (up/down). Available as both a CLI tool and Go library for embedding in applications. Widely used as the standard migration tool in Go microservices.
Score Breakdown
⚙ Agent Friendliness
🔒 Security
Database credentials in DSN/env vars — follow standard database credential security practices. Migrations run with the connection's permissions — use a restricted migration user.
⚡ Reliability
Best When
You're managing database schema changes in Go services with numbered SQL migration files and want a simple, reliable migration runner that works as both a CLI and embedded library.
Avoid When
You want code-first schema definition (like Ent) or complex data transformation pipelines — golang-migrate is SQL-file based schema versioning.
Use Cases
- • Manage database schema versioning in Go applications with numbered up/down SQL migration files
- • Run database migrations as part of Go application startup or CI/CD pipelines using the embedded library
- • Apply or rollback migrations via CLI in deployment scripts without writing custom migration tooling
- • Migrate between database versions in agent infrastructure where schema evolution is needed
- • Support multiple database backends with a single migration workflow across dev, staging, and production environments
Not For
- • Teams preferring Go struct-based schema definitions — use Ent or GORM AutoMigrate for code-first schema management
- • Complex data transformations requiring application logic — pure SQL migrations limit transformation complexity
- • Cross-database migration (migrating data between database types) — golang-migrate handles schema versioning, not data ETL
Interface
Authentication
Authentication is via database connection string (DSN) — supports all auth methods the underlying database driver supports. No library-level auth.
Pricing
MIT license. Community maintained open source.
Agent Metadata
Known Gotchas
- ⚠ Dirty migration state (schema_migrations.dirty=true) after a failed migration must be manually resolved with migrate force <version> — agents must handle this recovery path
- ⚠ Migration files must follow strict naming convention (000001_name.up.sql / 000001_name.down.sql) — incorrect naming silently skips migrations
- ⚠ Database connection strings vary by driver — PostgreSQL uses 'postgres://', MySQL requires 'mysql://', and DSN format differs per database type
- ⚠ golang-migrate acquires an advisory lock during migration — concurrent migration attempts (multiple app replicas starting) may deadlock or queue
- ⚠ Down migrations are optional but required for rollback — skipping down migration files prevents rollback capabilities
- ⚠ Source URLs support multiple backends (file://, github://, s3://) — file:// path resolution is relative to working directory, not binary location
Alternatives
Full Evaluation Report
Comprehensive deep-dive: security analysis, reliability audit, agent experience review, cost modeling, competitive positioning, and improvement roadmap for golang-migrate.
AI-powered analysis · PDF + markdown · Delivered within 30 minutes
Package Brief
Quick verdict, integration guide, cost projections, gotchas with workarounds, and alternatives comparison.
Delivered within 10 minutes
Score Monitoring
Get alerted when this package's AF, security, or reliability scores change significantly. Stay ahead of regressions.
Continuous monitoring
Scores are editorial opinions as of 2026-03-07.