All jobs

Add Versioned Database Migrations to a Gin App

Yes. An agent replaces GORM AutoMigrate calls with numbered gormigrate migrations, keeps the SQLite test setup working, adds a migrate command and opens a PR.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent reads how the schema is created today before adding a migration tool. In an API shaped like gothinkster/golang-gin-realworld-example-app, go.mod is at Go 1.21 with gin-gonic/gin v1.10.0, gorm.io/gorm v1.25.12 and gorm.io/driver/sqlite v1.5.7. hello.go holds main and a Migrate function that calls users.AutoMigrate() and then db.AutoMigrate for ArticleModel, TagModel, FavoriteModel, ArticleUserModel and CommentModel, in that order, on every start. common/database.go opens ./data/gorm.db from DB_PATH and a separate test database from TEST_DB_PATH, and both users/unit_test.go and articles/unit_test.go call common.TestDBInit() in TestMain and then AutoMigrate themselves. Nothing records which schema version a database file is at.

The agent adds github.com/go-gormigrate/gormigrate/v2 and a migrations package with one numbered migration, 202601010001_initial, whose Migrate function creates the same six tables through the existing GORM models and whose Rollback drops them in reverse order. gormigrate writes a migrations table with each applied id, so a second start applies nothing. Migrate in hello.go becomes a call to migrations.Run(db), and InitSchema is set so a fresh database is created in one step rather than replaying every migration. A new cmd/migrate/main.go runs up, down and status against DB_PATH, which is what a deploy script calls before the API starts.

The tests are the delicate part. TestDBInit builds a throwaway SQLite file, and both suites expect their tables to exist after AutoMigrate. The agent points those calls at migrations.Run too, so the tests exercise the real migration list, and adds migrations/migrations_test.go that runs the list up on a fresh file, checks the migrations table holds the one id, runs it down, and checks the tables are gone. go vet, bash scripts/gofmt.sh and golangci-lint with the repository's .golangci.yml are run as .github/workflows/ci.yml runs them on Go 1.21, 1.22 and 1.23, and bash scripts/coverage.sh produces the per-package coverage the workflow uploads.

The pull request also updates readme.md and AGENTS.md, which both describe GORM as migrating on start, with the new go run ./cmd/migrate up step and the rule that a schema change is a new file in migrations/, never an edit to an applied one. The Postman collection under api/ and scripts/run-api-tests.sh are untouched because the HTTP surface does not change.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Add versioned database migrations to this Gin app and open a pull request. Read go.mod, hello.go, common/database.go, users/models.go, articles/models.go, users/unit_test.go, articles/unit_test.go, scripts/coverage.sh and .github/workflows/ci.yml first. Add github.com/go-gormigrate/gormigrate/v2 and a migrations package with a single numbered initial migration that creates the users, follows, articles, tags, favorites, article_users and comments tables through the existing models, with a rollback that drops them, and set InitSchema for fresh databases. Replace the AutoMigrate calls in hello.go and in both TestMain functions with migrations.Run. Add cmd/migrate/main.go with up, down and status subcommands that read DB_PATH. Add migrations/migrations_test.go covering up, the recorded id, and down on a fresh SQLite file. Run go build ./..., bash scripts/gofmt.sh, golangci-lint run and bash scripts/coverage.sh, and paste the output in the pull request. Update readme.md and AGENTS.md to describe the migrate command. Do not change any route, model field or the Postman tests.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

What comes back is a pull request with go.mod and go.sum gaining one module, a new migrations/ package with the initial migration and its test, cmd/migrate/main.go, and small edits to hello.go, users/unit_test.go, articles/unit_test.go, readme.md and AGENTS.md. The description shows the output of scripts/coverage.sh with the per-package go test lines, the gofmt check, and a transcript of go run ./cmd/migrate status on a fresh file followed by up.

On a repository with the realworld app's workflow, the pull request runs the test matrix on three Go versions, golangci-lint v1.61, the gosec scan and the Newman API tests against the running server, so a migration that fails to create a table the handlers need shows up in the API job rather than at deploy time.

A reviewer checks that the initial migration creates exactly the columns and indexes AutoMigrate created before, including the unique index on email, slug and tag, that Rollback drops the join table before the tables it references, and that an existing gorm.db file from before the change is recorded as migrated by InitSchema rather than recreated. Then they add the migrate up call to their deploy step.

Run it on every Linear issue labelled agent

A Rush automation with a linear trigger starts one run for each issue that gets the label, with this prompt as the instructions and the issue's title and description added after it. An issue that says which table needs a new column becomes a run that writes the next numbered migration file in migrations/ and the test for it, and opens a pull request that links the issue.

Each run is independent and has its own max_runs_per_hour cap on the automation, so a batch of schema issues labelled at once becomes a batch of separate pull requests, each with its own migration and its own test output.

The use case this job follows, with its automation and trigger: Hand off a long task.

Why run it on Rush?

Replacing AutoMigrate is the kind of change a developer postpones because it touches startup, both test suites and the deploy script at once, and because the proof that an existing database survives it means actually running the old binary, then the new one, against the same file. In a Rush sandbox the agent does exactly that, keeps every go command and its output in the run's record, and shows the before-and-after status in the pull request.

The same request works on every Go service a team owns that still relies on AutoMigrate, and because each run opens a pull request through the Rush GitHub App, the migration tool arrives as a reviewable diff with the suite already green, not as a tool a person has to wire in by hand on a Friday.

Frequently asked questions

What happens to a database that already has the tables?

gormigrate's InitSchema runs only when the migrations table does not exist. The pull request handles the existing-file case by recording the initial migration as applied when the users table is already present, so a running deployment is not recreated. The reviewer should confirm that branch against a copy of production.

Why gormigrate rather than golang-migrate?

The models already describe the schema in GORM tags, and gormigrate lets the initial migration reuse them while later ones can be plain SQL through tx.Exec. golang-migrate would mean maintaining SQL files from day one and a second connection; the pull request notes the trade-off.

Do the existing tests still create their own schema?

Yes, through the same migration list the server uses, so a migration that breaks a handler fails in users or articles tests, not only in production. TestDBInit and TestDBFree in common/database.go are unchanged.

Does the API change?

No route, model field or JSON shape changes. The Postman collection in api/ runs unchanged, which the API Integration Test job proves on the pull request.

More Gin jobs

The same job on other stacks

Keep reading