# 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 Rush](https://cloud.getrush.ai/run/add-database-migrations/gin/). Opens 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`

```json
{
  "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.

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

- [Add a Feature to a Gin App from a Customer Spec](https://getrush.ai/run/add-feature-per-customer/gin/)
- [Add Graceful Shutdown to a Gin API](https://getrush.ai/run/add-graceful-shutdown/gin/)
- [Add Health Check Endpoints to a Gin App](https://getrush.ai/run/add-health-checks/gin/)

## The same job on other stacks

- [Add Database Migrations to a GORM App](https://getrush.ai/run/add-database-migrations/gorm/)
- [Add Knex Migrations to an Express App](https://getrush.ai/run/add-database-migrations/knex/)
- [Add TypeORM Migrations to a Koa API](https://getrush.ai/run/add-database-migrations/koa/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
