gograte

A powerful database migration library for Go applications with CLI support.

Features

• Go Migrations: Type-safe migrations with full Go power
• SQL Migrations: Plain SQL files with -- +gograte Up/Down directives
• Multiple Databases: PostgreSQL and TimescaleDB drivers included
• Library & CLI: Use as an embedded library or standalone CLI tool
• Transaction Support: Each migration runs in a transaction (configurable)
• Self-Registering: Go migrations register themselves via init()

Installation

CLI

go install codeberg.org/jentevh/gograte/cmd/gograte@latest

Library

go get codeberg.org/jentevh/gograte

Quick Start

CLI Usage

# Create a new migration
gograte create create_users --type sql

# Apply all pending migrations
gograte up --dsn "postgres://user:pass@localhost:5432/mydb"

# Check migration status
gograte status --dsn "postgres://user:pass@localhost:5432/mydb"

# Rollback last migration
gograte down --dsn "postgres://user:pass@localhost:5432/mydb"

# Rollback all migrations
gograte down --dsn "postgres://..." --all

Library Usage

package main

import (
    "context"
    "log"

    "codeberg.org/jentevh/gograte/pkg/gograte"
    _ "codeberg.org/jentevh/gograte/pkg/gograte/driver" // Register drivers
    _ "yourapp/migrations" // Import to register Go migrations
)

func main() {
    cfg := gograte.DefaultConfig().
        WithDSN("postgres://user:pass@localhost:5432/mydb").
        WithMigrationsDir("./migrations")

    m, err := gograte.New(cfg)
    if err != nil {
        log.Fatal(err)
    }
    defer m.Close()

    // Apply all pending migrations
    if err := m.Up(context.Background()); err != nil {
        log.Fatal(err)
    }
}

Writing Migrations

Go Migrations

Go migrations implement the Migration interface and register themselves:

package migrations

import (
    "context"
    "codeberg.org/jentevh/gograte/pkg/gograte"
)

func init() {
    gograte.Register(&Migration20260110120000CreateUsers{})
}

type Migration20260110120000CreateUsers struct{}

func (m *Migration20260110120000CreateUsers) Version() string {
    return "20260110120000"
}

func (m *Migration20260110120000CreateUsers) Name() string {
    return "create_users"
}

func (m *Migration20260110120000CreateUsers) Up(ctx context.Context, db gograte.DB) error {
    return db.Exec(ctx, `
        CREATE TABLE users (
            id SERIAL PRIMARY KEY,
            email VARCHAR(255) NOT NULL UNIQUE,
            created_at TIMESTAMPTZ DEFAULT NOW()
        )
    `)
}

func (m *Migration20260110120000CreateUsers) Down(ctx context.Context, db gograte.DB) error {
    return db.Exec(ctx, `DROP TABLE users`)
}

SQL Migrations

SQL migrations use directives to separate up and down sections:

-- +gograte Up
CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    email VARCHAR(255) NOT NULL UNIQUE,
    created_at TIMESTAMPTZ DEFAULT NOW()
);

-- +gograte Down
DROP TABLE users;

CLI Reference

Global Flags

Flag	Default	Description
--dsn	-	Database connection string
--driver	postgres	Database driver (postgres, timescale)
--dir	./migrations	Migrations directory
--table	schema_migrations	Migrations tracking table

Commands

gograte up

Apply pending migrations.

gograte up --dsn "postgres://..." [flags]
  --steps int    Number of migrations to apply (0 = all)

gograte down

Rollback migrations.

gograte down --dsn "postgres://..." [flags]
  --steps int    Number of migrations to rollback (default 1)
  --all          Rollback all migrations

gograte status

Show migration status.

gograte status --dsn "postgres://..."

gograte create

Create a new migration file.

gograte create <name> [flags]
  --type string    Migration type: go, sql (default "go")

Database Drivers

PostgreSQL

The default driver for standard PostgreSQL databases.

gograte up --dsn "postgres://user:pass@localhost:5432/mydb" --driver postgres

TimescaleDB

Extended PostgreSQL driver with TimescaleDB support. Automatically ensures the TimescaleDB extension is installed.

gograte up --dsn "postgres://user:pass@localhost:5432/mydb" --driver timescale

Configuration

type Config struct {
    DSN             string // Database connection string
    Driver          string // postgres, timescale
    MigrationsDir   string // Path to migrations directory
    TableName       string // Migrations tracking table (default: schema_migrations)
    UseTransactions bool   // Wrap each migration in transaction (default: true)
}

Project Structure

your-project/
├── migrations/
│   ├── 20260110120000_create_users.go
│   ├── 20260110130000_add_email_index.sql
│   └── 20260110140000_create_posts.go
└── main.go

License

MIT