gostgrator: A low dependency, go stdlib port of postgrator supporting postgres and sqlite.
Migrations can live in any folder in your project. The default is ./migrations.
Migration files are named 001.do.some-optional-description.sql and 001.undo.some-optional-description.sql and come in up and down pairs.
The files should contain SQL appropriate for the database you are running them
./migrations
├── 001.do.sql
├── 001.undo.sql
├── 002.do.some-description.sql
├── 002.undo.some-description.sql
├── 003.do.sql
├── 003.undo.sql
├── 004.do.sql
├── 004.undo.sql
├── 005.do.sql
├── 005.undo.sql
├── 006.do.sql
└── 006.undo.sqlgostgrator (like postgrator), applies no special or magic transaction around your migrations, other than running multiple statements from a file in one execution which postgres will treat as a transaction. If you need stricter behavior than this, or are migrating databases that don't have this behavior, wrap your migrations in explicite BEGIN/END blocks.
gostgrator is intended to be installed and versioned as a go tool.
Each supported database has it's own CLI you can install.
The gostgrator/pg cli provides migration support for Postgres.
go get -tool github.com/bcomnes/gostgrator/pg
go tool github.com/bcomnes/gostgrator/pg -help
Usage:
gostgrator-pg [command] [arguments] [options]
Commands:
migrate [target] Migrate the schema to a target version (default: "max").
down [steps] Roll back the specified number of migrations (default: 1).
new <desc> Create a new empty migration pair with the provided description.
drop-schema Drop the schema version table.
list List available migrations and annotate the migration matching the database version.
Options:
-config string
Path to JSON configuration file (optional)
-conn string
PostgreSQL connection URL. Can be set with DATABASE_URL env var.
-help
Show help message
-migration-pattern string
Glob pattern for migration files when running up or down migrations (default "migrations/*.sql")
-mode string
Migration numbering mode ("int" or "timestamp") when creating new migrations (default "int")
-schema-table string
Name of the schema table migration state is stored in (default "schemaversion")
-version
Show versiongo get -tool github.com/bcomnes/gostgrator/sqlite
go tool github.com/bcomnes/gostgrator/sqlite -help
Usage:
gostgrator-sqlite [command] [arguments] [options]
Commands:
migrate [target] Migrate the schema to a target version (default: "max").
down [steps] Roll back the specified number of migrations (default: 1).
new <desc> Create a new empty migration pair with the provided description.
drop-schema Drop the schema version table.
list List available migrations and annotate the migration matching the database version.
Options:
-config string
Path to JSON configuration file (optional)
-conn string
SQLite connection URL (typically a file path, e.g., "./db.sqlite"). Can also be set via SQLITE_URL env var.
-help
Show help message
-migration-pattern string
Glob pattern for migration files (default "migrations/*.sql")
-mode string
Migration numbering mode ("int" or "timestamp") for new command (default "int")
-schema-table string
Name of the schema table (default "schemaversion")
-version
Show version# migrate to latest in ./migrations using DATABASE_URL
go tool github.com/bcomnes/gostgrator/pg migrate
833F
# rollback the last two migrations
go tool github.com/bcomnes/gostgrator/pg down 2
# create a timestamp‑based pair
go tool github.com/bcomnes/gostgrator/pg -mode timestamp new "add-users-table"
# list all migrations and mark current
gostgrator-pg listFull API docs live on PkgGoDev.
- CLI ‑ first – instant productivity; no boilerplate code required.
- Typed Go API – embed migrations programmatically when you need to.
- Checksum validation – MD5 guardrails ensure applied migrations never drift.
- Up ⬆ / Down ⬇ parity – every migration pair keeps rollbacks honest.
- Zero dependencies – a single static binary per database driver.
MIT © Bret Comnes 2025