st-migrate-go

README

Report Bug · Request Feature

SuperTokens role/permission migrations with golang-migrate style sources, as an SDK and CLI.

About The Project

st-migrate-go lets you manage SuperTokens roles and permissions using golang-migrate–style migration sources. It keeps migrate’s filename-based ordering, adds schema-versioned YAML for future evolution, and ships as both a Go SDK and a CLI.

• SDK (st-migrate/) to embed in Go services.
• CLI (cmd/st-migrate-go) for terminal or CI/CD use.

Key behaviors:

• Order is defined by filenames (0001_name.up.yaml / .down.yaml).
• YAML version is the schema version (v1 today); filenames control execution order.
• Works with golang-migrate sources; state can be file-based (default) or any migrate DB driver (postgres/mysql/sqlite registered in the CLI).
• Default executor calls supertokens-golang; you can plug in your own.

(back to top)

Built With

• Go
• Cobra
• golang-migrate
• SuperTokens Go SDK

(back to top)

Getting Started

Follow these steps to install and run the CLI, or embed the SDK in your Go application.

Prerequisites

• Go 1.20+ (tested with 1.24)
• Access to your SuperTokens instance for applying role changes

Installation

1. Clone the repo

   git clone https://github.com/BeardedWonderDev/st-migrate-go.git
   cd st-migrate-go
   

2. Install the CLI (or download a release binary)

   go install ./cmd/st-migrate-go
   

3. (Optional) Vendor dependencies

   go mod tidy
   

4. Verify

   st-migrate-go --help
   

(back to top)

Usage

CLI

# Show current and pending migrations
st-migrate-go --source file://backend/migrations/auth status

# Apply all pending migrations
st-migrate-go up

# Apply up to a target version
st-migrate-go up 5

# Roll back one migration (default) or N steps
st-migrate-go down
st-migrate-go down 2

# Migrate automatically to a target version (up or down)
st-migrate-go migrate 5

# Generate paired up/down files with the next version number
st-migrate-go create add-reporting-roles

Flags:

• --source migrate-style source URL (default file://backend/migrations/auth)
• --database migrate database driver URL for state tracking (postgres, mysql, sqlite registered in CLI build)
• --state-file path to a JSON state store used when --database is empty (default .st-migrate/state.json)
• --dry-run log actions without executing or mutating state
• --verbose enable debug logging

Typical workflows:

• Bootstrap everything: st-migrate-go up
• Targeted deploy: st-migrate-go up 7
• Move to a specific version: st-migrate-go migrate 5
• Rollback last step: st-migrate-go down
• Create a new migration pair: st-migrate-go create add-audit-role

SDK

cfg := stmigrate.Config{
    SourceURL: "file://backend/migrations/auth",
    // Optional: Store, Executor, Logger, DryRun, Registry
}
r, err := stmigrate.New(cfg)
if err != nil {
    // handle
}
defer r.Close()
if err := r.Up(context.Background(), nil); err != nil {
    // handle
}

// Auto-migrate to a specific version (up or down)
if err := r.Migrate(context.Background(), 5); err != nil {
    // handle
}

Initialize the SuperTokens Go SDK in your application (e.g., supertokens.Init(...)) before constructing the runner so role/permission calls can reach your SuperTokens core.

Using a golang-migrate database driver (example: Postgres):

import (
    "github.com/BeardedWonderDev/st-migrate-go/st-migrate"
    _ "github.com/lib/pq"
)

// create or reuse *sql.DB ...
db, _ := sql.Open("postgres", "<dsn>")
cfg := stmigrate.Config{
    SourceURL: "file://backend/migrations/auth",
    DB:        db,
    DBDriver:  "postgres",
}
r, _ := stmigrate.New(cfg)
defer r.Close()
_ = r.Up(context.Background(), nil)

YAML schema v1:

version: 1          # schema version
actions:
  - role: app:admin
    ensure: present  # present|absent (default present)
    add: [app:read, app:write]
    remove: []

(back to top)

Roadmap

• Add additional sources (embed, git, s3)
• Schema v2 exploration (richer permission metadata)
• Advisory locking strategy for multi-runner safety

See the open issues for a full list of proposed features and known issues.

(back to top)

Contributing

Contributions are welcome! Please open an issue to discuss changes before submitting a PR. Keep changes small and covered by tests.

(back to top)

License

This project is licensed under the Apache License 2.0. See LICENSE.txt for details.

(back to top)

Contact

Project Link: https://github.com/BeardedWonderDev/st-migrate-go.
If you need to reach us, please open an issue describing your question or request.

(back to top)

Acknowledgments

• golang-migrate
• SuperTokens
• Cobra
• Best-README-Template

(back to top)