What the agent does
gopkg.in/mgo.v2 has been unmaintained for years, and the practical consequence is that it cannot talk to a current server. The agent establishes that before it writes any code. In a job scheduler like ajvb/kala, go.mod requires gopkg.in/mgo.v2 v2.0.0-20160818020120-3f83fa500528, and the driver is used in three files: job/storage/mongo/mongo.go, the storage backend; its test file beside it; and cmd/serve.go, which builds an mgo.Credential from the --jobdb-username and --jobdb-password flags. The agent downloads a MongoDB 7 server tarball into the sandbox, starts mongod on localhost, and runs the backend's existing tests. They end at mgo.Dial with no reachable servers.
The port itself is contained, because the backend is 92 lines behind a small interface. mgo.Dial and session.Login become mongo.Connect with client options and a credential. session.DB(database).C(collection) becomes client.Database(...).Collection(...), EnsureIndexKey("id") becomes Indexes().CreateOne, Find(...).All and Find(...).One become Find with a cursor and FindOne(...).Decode, Insert becomes InsertOne, and every call gains a context.Context. Three behaviours need a decision instead of a rename. mgo's Remove returns an error when nothing matched and DeleteOne does not, so the agent returns an error when DeletedCount is zero to keep what callers of Delete observe. The README documents --jobdb-address=server1.example.com,server2.example.com, a bare host list that mgo.Dial accepted, and the official driver wants a mongodb:// URI, so the agent adds the scheme when the flag has none. And session.SetMode(mgo.Monotonic, true) has no direct equivalent; the agent states the read preference it chose in its place.
It checks the stored document shape, since a driver swap that renames fields orphans existing data. The Job struct in job/job.go carries only json tags. Both drivers ignore those by default and store each exported field under its lowercased name, so Id stays id and the {"id": ...} filter keeps matching. The agent confirms this by saving a job and reading the raw document back.
The larger surprises are in the toolchain, and the agent reports them in the order it met them. Run with the newest Go, this repository's tests crash in packages the migration never touches: the boltdb storage suite dies with fatal error: unexpected signal during runtime execution on a clean checkout. The same suite passes on Go 1.20. So the baseline has to be taken on a Go version the project works with, which CI pins as cimg/go:1.17.13 in .circleci/config.yml. The driver version follows from that. The newest release of the official driver declares go 1.25.0 in its own go.mod and supports MongoDB 4.4 and later; the 2.0.0 release declares go 1.18 and supports 3.6 and later. The agent takes a 2.x release this code base can build with, and on Go 1.20 against the MongoDB 7 server all four tests in job/storage/mongo pass, as does the boltdb suite. It then lists what CI needs: a Go image of at least 1.18, and a newer database than the mongo:3.4 image named in both .circleci/config.yml and docker-compose.yml.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Migrate this Go repository from gopkg.in/mgo.v2 to the official MongoDB Go driver (go.mongodb.org/mongo-driver/v2). First list every file that imports mgo or mgo/bson and every mgo call it makes. Read go.mod and the CI configuration for the Go version and MongoDB image in use. Install a MongoDB server in the sandbox from MongoDB's release tarball, start mongod on localhost, and run the existing tests for the Mongo code before changing anything; record the result. Run the rest of the test suite too, on the Go version CI uses or the nearest one you can install, so you know which failures predate your change. Port the code call by call. Keep the exported API of the storage package unless a type from mgo appears in it; where one does, replace it with the driver's equivalent and update the callers. Preserve behaviour where the drivers differ: not-found on delete, address formats the CLI flags and README document, consistency mode, and index creation. Confirm that documents keep the same field names by reading a raw document back. Choose the newest driver release whose Go requirement and minimum MongoDB version this project can meet, and say which constraint decided it; do not raise the go directive further than that release needs. Run go vet and the tests after the port. Do not edit CI files; list the image changes CI needs in the pull request. Remove mgo from go.mod with go mod tidy and open a pull request.",
"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 that changes five files: job/storage/mongo/mongo.go, job/storage/mongo/mongo_test.go, cmd/serve.go, go.mod and go.sum. The description maps each mgo call to its replacement in a table and gives the three behavioural decisions their own paragraphs, with the reasoning for each, so a reviewer can overrule one without rereading the diff.
The verification section names versions, because here they decide the result: the Go toolchain used, the MongoDB server version started in the sandbox, the driver release chosen, and the test output for the Mongo package before and after. It records separately that unrelated suites crash under the newest Go on an untouched checkout, so nobody attributes that to the driver.
The last section is the work the pull request does not do. CI will not pass until its Go image and its mongo image are raised, and those edits are listed with the file and line. If your production cluster is older than the driver's minimum server version, that is a blocker to merging, and the description says which driver release would still support it.
Run it on every Linear issue labelled driver-migration
A driver migration is planned work, so a tracker label is a natural trigger. Create an automation in the repository's Project with a linear trigger on that label and this prompt. Labelling an issue starts a run, and the issue's text arrives after the saved prompt as event data. The trigger needs a Linear connection for the automation's runner, added in the console under Settings → Connections, and it fires only when the person who applied the label is in your Rush org.
With several services to migrate, give each its own Project and automation. Each run gets its own sandbox and its own mongod, so they do not share a database.
The use case this job follows, with its automation and trigger: Upgrade dependencies weekly.
Why run it on Rush?
This migration cannot be judged from a compile. Whether the new code works depends on a server being there, and whether the old code still worked depends on which server. The agent runs a real mongod beside the code in its sandbox, runs the tests against it before and after, and installs more than one Go toolchain to separate failures caused by the port from failures that were already present. Setting that up locally is an afternoon of version juggling. In a run it is a sequence of commands whose output is kept.
That record is what makes the pull request reviewable. The claims a reviewer most needs, that the old driver could not connect, that the new one passes the same tests, that the crash under the newest Go predates the change, each point to a command and its output in the session's transcript.
Frequently asked questions
Should I move to globalsign/mgo instead of the official driver?
The globalsign fork extended mgo's life for a while and is also no longer developed. The official driver is the one MongoDB maintains and the only one that follows new server releases. The agent ports to the official driver; the API is different enough that the work is a port, not an import rename.
Will my existing documents still load?
Field names are the thing to check. Without bson struct tags, both drivers store a field under its lowercased Go name, so untagged structs keep working. Where your structs use bson tags, the official driver reads the same tags. The agent reads a raw document back after a save and compares it with what mgo wrote where an old document is available.
Does the agent need access to my MongoDB cluster?
No. It starts its own mongod inside the sandbox and runs the tests against that. Nothing in the run connects to your infrastructure, and the pull request is the only thing that reaches your repository.
Why does the driver version depend on my Go version?
Each driver release declares a minimum Go version in its go.mod. In ajvb/kala, adding the newest release makes the go command raise the module's go line from 1.13 to 1.25.0, and a higher go line can change how the rest of your code builds and runs. The agent picks the newest driver release your project can meet and reports what a newer one would require.
More jobs like this: Upgrade dependencies weekly
- Replace minimist With util.parseArgs in a Node.js CLI (minimist)
- Migrate From mitchellh/mapstructure to go-viper/mapstructure v2 (mapstructure)
- Replace the mock Backport With unittest.mock (mock)
- Migrate From mysql to mysql2 in a Node.js App (mysql (Node.js))
- Migrate from node-sass to Dart Sass in a Webpack Project (webpack)
- Migrate a Python Project From oauth2client to google-auth (oauth2client)