# Replace mattn/go-sqlite3 With modernc.org/sqlite for a cgo-Free Go Build

Yes. An agent swaps the cgo SQLite driver for the pure Go one, renames the driver, checks every DSN, and shows both builds write the same rows.

[Run this on Rush](https://cloud.getrush.ai/run/migrate-go-sqlite3-to-modernc-sqlite/go-sqlite3/). Opens the console with this prompt ready to send, in a Project that has your repository.

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

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

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

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.

## 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](https://getrush.ai/run/migrate-go-yaml-v2-to-v3/go-yaml/)
- [Migrate From github.com/golang/protobuf to google.golang.org/protobuf](https://getrush.ai/run/migrate-golang-protobuf-to-google-protobuf/golang-protobuf/)
- [Replace Deprecated golint With revive, go vet and staticcheck in a Go Project](https://getrush.ai/run/migrate-golint-to-revive/golint/)
- [Migrate a Custom Environment From OpenAI Gym to Gymnasium](https://getrush.ai/run/migrate-gym-to-gymnasium/gym/)
- [Migrate From the Deprecated @hapi/joi Package to joi](https://getrush.ai/run/migrate-hapi-joi-to-joi/hapi-joi/)
- [Migrate an Express App From Jade to Pug](https://getrush.ai/run/migrate-jade-to-pug/jade/)

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