gostgrator

gostgrator

gostgrator: A low dependency, go stdlib port of postgrator supporting postgres and sqlite.

Migrations

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.sql

Migration Transactions

gostgrator (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 CLI

gostgrator is intended to be installed and versioned as a go tool.

Each supported database has it's own CLI you can install.

gostgrator/pg

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 version

gostgrator/sqlite

go get -tool github.com/bcomnes/gostgrator/sqlite
go tool github.com/bcomnes/gostgrator/sqlite -help

Quick tour

# migrate to latest in ./migrations using DATABASE_URL
go tool github.com/bcomnes/gostgrator/pg migrate

# 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 list

Library usage

Full API docs live on PkgGoDev.

Why another migrator?

• 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.

License

MIT © Bret Comnes 2025