# Migrate From the Archived github.com/boltdb/bolt to go.etcd.io/bbolt in a Go Service

Yes. An agent swaps the archived boltdb/bolt import for etcd's bbolt fork, tidies go.mod, runs the Go tests against the same bucket code and opens a PR.

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

## What the agent does

The agent clones the repository into its own cloud sandbox and reads where Bolt is used before changing the module. In a Go service like git-lfs/lfs-test-server, the example Git LFS API server, `go.mod` requires `github.com/boltdb/bolt v1.3.1` beside `gorilla/mux` 1.8.1 and `gorilla/context`, with a `go 1.20` directive, and the `Dockerfile` builds from `golang:1.20`. One file imports it, `meta_store.go`, line 14: `MetaStore` holds a `*bolt.DB`, `NewMetaStore` opens the file with `bolt.Open(dbFile, 0600, &bolt.Options{Timeout: 1 * time.Second})` and creates the `users`, `objects` and `locks` buckets, and the rest of the file is `db.View` and `db.Update` closures over `*bolt.Tx`, from `Get` at line 74 to the lock listing at line 432. `meta_store_test.go`, `content_store_test.go` and `server_test.go` exercise it, and `script/release` runs `go build` and `go test` before cutting a release.

Then it confirms the reason to move. The GitHub API reports `boltdb/bolt` as archived, with its last push in March 2018, while `etcd-io/bbolt`, the fork etcd maintains, is active, its latest release v1.5.0. Bolt's own README says its API and file format are fixed, and bbolt kept both: `Open`, `Options`, `DB`, `Tx`, `Bucket` and `Cursor` carry the same names and signatures the file uses. `go build ./...` and `go test ./...` pass on the original, which the agent records as the baseline.

The migration is one import and a module update. `meta_store.go` line 14 becomes `bolt "go.etcd.io/bbolt"`, aliased so none of the `bolt.` references in the file change, then `go get go.etcd.io/bbolt@latest` and `go mod tidy` replace the requirement, drop the old `go.sum` lines and raise the `go` directive, because bbolt v1.5.0 requires Go 1.25; pinning `go.etcd.io/bbolt@v1.3.11` instead still lifts it to `go 1.22`. On either release `go build ./...` and `go test ./...` pass, and `go vet ./...` is clean, so the agent takes the current release and moves the `Dockerfile` base image to the matching `golang` tag in the same change, since a `go 1.25` directive will not build on the 1.20 image.

It writes down what it checked rather than assumed: that the database file format is unchanged, so an existing `lfs.db` opens under bbolt without conversion, which the test suite's `setupMeta` round-trips through `NewMetaStore` on a fresh file; and that the `Timeout` option, bucket creation and cursor iteration behave the same, which the three test files cover. The diff is two lines in `meta_store.go` and `go.mod` plus `go.sum` and the `Dockerfile` tag.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Replace github.com/boltdb/bolt with go.etcd.io/bbolt. Read go.mod, the Dockerfile and every Go file that imports bolt, and list each file with the Bolt types and functions it uses. Run go build ./... and go test ./... first and record the result. Change the import to an aliased go.etcd.io/bbolt so the call sites stay as they are, run go get for the current bbolt release and go mod tidy, and report what the go directive becomes; if the Dockerfile or CI pins an older Go than that directive, move it to the matching version in the same change. Run go build, go vet and go test again and quote the results. Say whether an existing database file needs any conversion. Open a pull request that quotes both test runs.",
  "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 touching `meta_store.go`, `go.mod`, `go.sum` and the `Dockerfile`: the aliased import, `go.etcd.io/bbolt` at its current release in place of `boltdb/bolt v1.3.1`, the `go` directive raised to what bbolt requires, and the `golang` base image tag moved to match. The description quotes `go test ./...` passing before and after, names the archived status and last push date of the old module, and states that the on-disk format is unchanged.

A reviewer checks that the alias leaves every `bolt.` call site untouched, that the `go` directive, the Dockerfile tag and any CI Go version agree, and that `go.sum` no longer lists the old module. The run's record holds the build, vet and test runs on both sides, so the claim that nothing but the module moved can be read in the output.

## Run it on every Monday morning

Add an automation to the repository's Project with this prompt and a `schedule` trigger, `cron` set to `0 9 * * 1` in your `timezone`. The prompt can name any module you want checked for archival; each Monday one run reads the module's repository status, and opens a pull request only when a dependency has been archived or marked deprecated and a maintained fork exists. A week with nothing to move opens nothing.

The same body works from your own server with `POST /o/{org}/sessions` and an API key when a vulnerability scanner flags an unmaintained module; the key's `webhook_url` receives `run.completed` or `run.failed` with the session URL and the pull request when the run ends.

## Why run it on Rush?

An archived dependency builds fine for years, so the move keeps getting deferred until a security fix is needed and there is nobody to ship it. The agent runs the real build and tests on both sides in its own sandbox and quotes them, so the pull request is a verified swap rather than a hopeful one, and every command with its output stays in the run's record.

The part that bites on a laptop is the `go` directive: a current bbolt pulls the module to a newer Go than the Dockerfile builds with, and the failure shows up in CI after merge. Because the agent reads the Dockerfile and reports what `go mod tidy` wrote, that mismatch lands in the same change.

## Frequently asked questions

### Is bbolt a drop-in replacement for boltdb/bolt?

For this code, yes. bbolt is etcd's fork of Bolt and keeps the `Open`, `DB`, `Tx`, `Bucket` and `Cursor` API and the file format, so an aliased import leaves every call site as it is and an existing database file opens without conversion. bbolt adds options and fixes Bolt never got, none of which this change uses.

### Why does go.mod's go directive change?

Because `go mod tidy` raises it to the minimum the new dependency declares: bbolt v1.5.0 requires Go 1.25, and even v1.3.11 requires 1.22. That is why the agent reads the Dockerfile and CI and moves their Go version in the same pull request rather than leaving a module that will not build on the pinned image.

### Can I pin an older bbolt to keep my Go version?

You can pin v1.3.x, which still needs Go 1.22, so a 1.20 pin has to move either way. The agent takes the current release by default and says in the description which older release would do if a smaller Go bump is wanted.

### What does the test suite prove here?

That opening the file, creating the three buckets, writing and reading objects, users and locks, and iterating with cursors behave the same under bbolt. Those are the operations `meta_store.go` performs, and the tests create a fresh database file for each run, so the proof is independent of any database left on a developer's machine.

## More jobs like this: Upgrade dependencies weekly

- [Migrate From boto to boto3 in a Python Service](https://getrush.ai/run/migrate-boto-to-boto3/boto/)
- [Convert a CoffeeScript Project to Modern JavaScript With decaffeinate](https://getrush.ai/run/migrate-coffeescript-to-javascript/coffeescript/)
- [Migrate a Go Project From dep (Gopkg.toml) to Go Modules](https://getrush.ai/run/migrate-dep-to-go-modules/dep/)
- [Migrate From drf-yasg to drf-spectacular in Django REST Framework](https://getrush.ai/run/migrate-drf-yasg-to-drf-spectacular/drf-yasg/)
- [Migrate From faker to @faker-js/faker in a Node.js Project](https://getrush.ai/run/migrate-faker-to-faker-js/faker/)
- [Migrate From Flask-Cache to Flask-Caching](https://getrush.ai/run/migrate-flask-cache-to-flask-caching/flask-cache/)

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