What the agent does
github.com/mattn/go-sqlite3 compiles SQLite's C source through cgo, so a build needs a C compiler and a cross-compile needs a C toolchain for the target. The agent first finds out how the project is built and whether anything depends on that. In a tool like technosophos/dashing, which writes the SQLite index inside a Dash docset, the whole build is one Makefile line, go build -o dashing -ldflags "-X main.version=${VERSION}" dashing.go, and the README tells users to install with Homebrew, MacPorts or go get. The driver is imported once, as _ "github.com/mattn/go-sqlite3" at the top of dashing.go, and opened once, in initDB, with sql.Open("sqlite3", dbname).
Then it reproduces the failure this migration is usually about. With CGO_ENABLED=0 the program still compiles, because the driver ships a stub for that case. The error arrives at run time, on the first statement: Binary was compiled with 'CGO_ENABLED=0', go-sqlite3 requires cgo to work. This is a stub. In this repository build and update print Failed to create database: with that message and then return nil, so the command exits with status 0 and leaves a docset with no index. The agent records that, since a release script that checks only the exit code would publish the broken binary.
The change itself is two lines. The import becomes _ "modernc.org/sqlite" and the driver name becomes "sqlite", because the pure Go driver registers under that name; leaving "sqlite3" gives sql: unknown driver "sqlite3" (forgotten import?). The agent then reads every string passed to sql.Open. Here it is a bare file path. Where a project appends go-sqlite3 options such as _busy_timeout or _foreign_keys, it rewrites them to the _pragma=busy_timeout(5000) form the new driver reads, and it searches for sqlite3.Error and sqlite3.ErrConstraint in error handling, which need the new package's error type.
Last, it compares the two drivers on real input. With a C compiler installed in the sandbox it builds the original, runs dashing build in examples/busybox, and keeps the resulting docSet.dsidx. It builds the migrated program with CGO_ENABLED=0, runs the same command, and compares the searchIndex rows and the schema of the two files. It also builds for darwin/arm64, windows/amd64 and linux/arm64 with cgo off. It reports what go get did to go.mod beyond the swap: this file declares go 1.13 and pins golang.org/x/net at a 2019 commit, and adding the new module raises both.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Replace github.com/mattn/go-sqlite3 with modernc.org/sqlite in this Go project so it builds with CGO_ENABLED=0. First read go.mod, the Makefile, any Dockerfile, goreleaser config and CI workflows, and list every place that sets CGO_ENABLED, installs gcc or a cross toolchain, or passes build tags meant for go-sqlite3 (sqlite_fts5, sqlite_json, libsqlite3 and similar). If a build tag enables an SQLite feature, check that modernc.org/sqlite has it before going on, and stop with a report if it does not. Before changing code: build the project as it is with cgo on (install gcc with apt if the machine has none), run the tests and one real command from the README or examples that writes a database, and keep the database file. Also build it once with CGO_ENABLED=0, run the same command, and record the message and the exit status. Then make the change: the blank import, the driver name in every sql.Open and sqlx or gorm call (sqlite3 becomes sqlite), every DSN option (rewrite _busy_timeout, _foreign_keys, _journal_mode and the like to _pragma=name(value)), and every use of sqlite3.Error or its constants. Run go mod tidy and list each line of go.mod that changed, including the go directive and any unrelated module that moved. Build with CGO_ENABLED=0, run the tests and the same command, and compare the two database files table by table: schema from sqlite_master and row counts, plus a sorted dump of each table. Then open the file the old build wrote with the new build and run one command that reads and writes it. Cross-compile with cgo off for darwin/arm64, windows/amd64 and linux/arm64. Run go vet before and after and report findings that were already there separately; do not fix them. Remove gcc and CGO_ENABLED=1 from build files only where nothing else needs cgo. Open a pull request with all of this 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 that edits dashing.go in two places and rewrites go.mod and go.sum. The description carries the evidence in order: the stub error and exit status from the cgo-off build of the old code, the row count and schema of searchIndex from each driver's docSet.dsidx, the result of comparing a sorted dump of the rows, and the three cross-compile commands with their results. It says plainly that the two database files are not byte-identical and need not be: each driver embeds its own SQLite release and the files can differ in size and header while holding the same rows.
The reviewer spends most of the time on go.mod. The go directive moves up from 1.13 to what the new module graph requires, golang.org/x/net moves with it, and a block of indirect modernc.org modules appears. Anyone who builds this tool with an older Go release is affected by that line, so the pull request names the new minimum. The pin being removed is v2.0.1+incompatible, one of the v2 tags the go-sqlite3 README says not to use, which is one more reason to stop depending on it.
Two go vet findings are listed as present before and after: a malformed struct tag on the externalURL field and an unused fmt.Errorf result. They are in the description, not in the diff.
Run it on every release that failed to cross-compile
The usual moment for this job is a release workflow that cannot produce a binary for a second platform. Add an automation in the Project with this prompt and a github trigger on workflow_run.failure; the failed run's details are added after the prompt as event data, so the agent sees which workflow and commit failed. Set its max runs per hour low, since one broken release can fail several jobs at once.
To do it on purpose across many repositories, call POST /o/{org}/sessions once per repository whose go.mod names github.com/mattn/go-sqlite3, with a request_id that is a UUID v5 of the repository name. Each call answers 202 at once; read each session for its pull request when it completes.
The use case this job follows, with its automation and trigger: Upgrade dependencies weekly.
Why run it on Rush?
Proving this swap takes both worlds on one machine: a C compiler to build the old driver, and a build with cgo off to show the new one needs none. The sandbox starts without gcc, which is the exact environment that produces the stub error, and the agent installs it only for the baseline. Both binaries run the same command against the same input, and both database files are kept for the comparison. Every one of those commands and its output is in the session's transcript.
The exit status finding is the kind that gets missed on a laptop, where cgo works and nobody runs the CGO_ENABLED=0 binary. Here the failing run is part of the record. The comparison is also on rows, not on a passing build, which matters for a project like this one that has no test files: go test ./... has nothing to say about whether the index is right.
Frequently asked questions
Why does my Go binary say "go-sqlite3 requires cgo to work. This is a stub"?
It was built with CGO_ENABLED=0, which is also what Go falls back to when it finds no C compiler. The build succeeds because go-sqlite3 includes a placeholder driver for that case, and the placeholder returns this error on first use. Either build with cgo and a C compiler, or move to a driver written in Go.
Do I have to change my SQL?
No. Both drivers run SQLite itself, so statements such as INSERT OR IGNORE and CREATE UNIQUE INDEX behave the same. What changes is around the SQL: the driver name passed to sql.Open, option names in the DSN, and the Go type of driver errors.
Will the database files my users already have still open?
Yes. The on-disk format is SQLite's and both drivers read it. The agent's comparison opens a file written by the old build with the new build's driver as part of the check, and reports the schema and row counts from each.
Is the pure Go driver slower?
It can be, since it is a translation of the C code and not the C code itself. Whether that matters depends on the workload: a tool that writes a few hundred rows once will not show it, a write-heavy service might. If the repository has benchmarks the agent runs them on both builds and includes the output; it does not guess.
What if my project uses gorm or sqlx?
sqlx takes the driver name the same way database/sql does, so it is the same two edits. gorm's gorm.io/driver/sqlite imports go-sqlite3 itself, so the agent replaces that dialector with a cgo-free one and says which module it chose and why. It checks go mod why github.com/mattn/go-sqlite3 afterwards to confirm nothing still pulls it in.
More jobs like this: Upgrade dependencies weekly
- Migrate From gopkg.in/yaml.v2 to yaml.v3 in a Go Project (go-yaml)
- Migrate From github.com/golang/protobuf to google.golang.org/protobuf (golang/protobuf)
- Replace Deprecated golint With revive, go vet and staticcheck in a Go Project (golint)
- Migrate a Custom Environment From OpenAI Gym to Gymnasium (OpenAI Gym)
- Migrate From the Deprecated @hapi/joi Package to joi (@hapi/joi)
- Migrate an Express App From Jade to Pug (Jade)