What the agent does
The agent starts by finding the column that is an enum in everything but name. In a project like techschool/simplebank, migration 000005_add_role_to_users.up.sql adds "role" varchar NOT NULL DEFAULT 'depositor' to users, and util/role.go holds the two values the code accepts, DepositorRole and BankerRole, as untyped string constants. sqlc, configured in sqlc.yaml for the postgresql engine with sql_package: "pgx/v5", generated Role string on the User struct in db/sqlc/models.go. Nothing stops a third value from being written, by a typo in Go or by an UPDATE in a console, and hasPermission in gapi/authorization.go would simply never match it.
The migration is where the first surprise is, and the agent finds it by running the statements, not by writing them. It installs PostgreSQL from system packages, creates the root role and simple_bank database that app.env points to, and applies the five existing migrations. Creating the type and then altering the column in one step fails: PostgreSQL answers default for column "role" cannot be cast automatically to type user_role, because the varchar default is still attached. So 000006 creates user_role, drops the default, changes the type with USING "role"::"user_role", and sets the default again. The agent also tests the case that bites in production. With one row holding a value outside the list, the cast stops with invalid input value for enum user_role, so the pull request includes a query that lists the distinct roles in the table, to be run before deploying. The down file reverses each step and drops the type.
Then it regenerates with the sqlc release named in the generated headers, 1.22.0, after confirming that a regeneration of the untouched repository is a no-op. sqlc reads the up migrations in db/migration as the schema, so the new file is all it needs. The only generated file that changes is models.go: it gains type UserRole string, the constants UserRoleDepositor and UserRoleBanker, a Scan method, a NullUserRole wrapper, and Role UserRole on User. Two options in sqlc.yaml, emit_enum_valid_method and emit_all_enum_values, add a Valid() method and an AllUserRoleValues() function, which the agent turns on because request validation needs them.
The new type then fails the build exactly where a string was assumed, and the compiler's list is the work list. api/user.go and gapi/rpc_login_user.go each pass user.Role to tokenMaker.CreateToken, whose role parameter is a string, in two places apiece. Test files break as well: api/account_test.go and gapi/rpc_update_user_test.go hand the role to helpers that take a string, and gapi/rpc_create_user_test.go puts a string into a db.User literal. The agent has a choice at the boundary and states it. The token payload in token/payload.go stays a string, since a token is serialized text and old tokens must still verify, and the conversion happens once on each side of it. util/role.go is reduced to the generated constants so there is a single list. It runs go build ./..., go vet ./... and make test against the migrated database.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Convert the users.role column in this Go project from a string to a PostgreSQL enum and let sqlc generate the Go type. Read sqlc.yaml, the Makefile, every migration, every query, the generated and hand-written files in db/sqlc, and every use of the role in the api, gapi, token and util packages and their tests first. Install the sqlc version named in the generated files' headers and confirm that sqlc generate on the untouched repository produces no diff. Install PostgreSQL from system packages, say which version, create the role and database the test config expects and apply the existing migrations with the tool the Makefile uses. Write the next numbered migration: create the enum type from the values the code accepts today, convert the column and keep its default. Run it against the migrated database and fix whatever PostgreSQL refuses, quoting the error. Also run it against a table that contains a value outside the enum and record what happens, and add to the pull request a query that finds such rows so it can be run before deploying. Write the down migration and apply up, down and up. Regenerate, turn on sqlc's enum helper options, and fix every compile error in code and tests without hand-editing generated files. Keep the serialized token format unchanged and say where strings are converted to the enum and back. Remove any second list of the same values. Run go build, go vet and make test, and open a pull request with the migration, the errors you hit, the generated diff, the list of call sites changed and the test output.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- 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.
- 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.
- 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
A pull request with one migration pair, two lines added to sqlc.yaml, a regenerated db/sqlc/models.go, and small edits where the role crosses into a string. The description gives the migration first, with the PostgreSQL error that shaped it quoted beside the statement order that works, and the result of applying it up, down and up in the sandbox.
A section headed before deploying has the query for values outside the enum and says what the migration does when one exists: the cast fails, the column keeps its varchar type, and golang-migrate leaves the version marked dirty until someone forces it back. Then comes the list of call sites, grouped as conversions to a string at the token boundary and places that now use the generated constants, and the make test output with the PostgreSQL version it ran on.
A reviewer checks the boundary decision, since it is the part with consequences: tokens issued before the deploy carry the role as text and must still be accepted afterwards, which is why the payload type did not change. They also confirm the enum's values are the complete list. Adding one later is another migration, and removing one is harder than adding it.
Run it on every string column that should be an enum
A developer usually spots this while reading a struct and hands it off instead of context-switching. They send this body to POST /o/{org}/sessions from a terminal or an editor's MCP client, changing the table and column in the first sentence, and continue with their own branch. A request_id, a UUID generated once for the job, makes a retried call return the run that already started.
Several columns can go out as several requests, each with its own UUID as request_id, and a key starts as many together as its max_concurrent allows. They will all add the next migration number and all regenerate models.go, so merge them one at a time and send a follow-up to the remaining sessions asking them to rebase and renumber.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
The two facts that decide this change are both things PostgreSQL says when asked: that the default has to come off before the type changes, and that one stray value stops the conversion. The agent has a server in its own sandbox with the project's migrations applied, runs the statements, and keeps the errors and the fixed order in the transcript at GET /o/{org}/sessions/{id}/messages. A migration written from memory finds these out on the staging database.
The rest is a compiler-driven sweep through packages and tests, tedious and well suited to being done somewhere else. The sandbox installs the generator version the repository pins, so the generated diff is one file and not a rewrite of all of them, and the developer who asked gets back a branch that builds, vets and passes the suite.
Frequently asked questions
Why an enum type and not a CHECK constraint?
Both stop bad values in the database. Only the enum gives sqlc something to generate from: with a CHECK the Go field stays a plain string and the list of values lives in a second place. If you expect the values to change often, say so, because a constraint is easier to alter and the agent will weigh that.
How do I add a value later?
With a migration that runs ALTER TYPE ... ADD VALUE, followed by sqlc generate, which adds the constant. The new value cannot be used in the same transaction that adds it, so it goes in its own migration ahead of any data change that needs it. Removing a value has no direct statement and means building a new type.
Does pgx need extra setup to read the enum?
Not for this use. The generated type is a string underneath and carries a Scan method, and the existing query tests in db/sqlc pass against the migrated database without registering anything. Arrays of an enum are the case that needs type registration, and the agent says so if a query uses one.
Will the JSON my API returns change?
No. The generated type marshals as the same string, and the struct tag on the field is unchanged. The agent runs the existing tests in the api package against the change to show it.
More sqlc jobs
More jobs like this: Hand off a long task
- Move Hard-Coded Values in a Compose File into a .env File (Docker Compose)
- Read Typer CLI Options From Environment Variables (Typer)
- Add Error Boundaries to a React Router App (React Router)