What the agent does
The alert says database is locked, and the agent's first job is to make that happen on demand. In a GORM app like realworld-apps/golang-gin-realworld-example-app, Init in common/database.go calls sqlite.Open(dbPath) with a bare file path, ./data/gorm.db unless DB_PATH says otherwise, sets SetMaxIdleConns(10) and leaves the number of open connections unlimited. go.mod pins gorm.io/gorm v1.25.12 and gorm.io/driver/sqlite v1.5.7, which brings in mattn/go-sqlite3. That driver needs cgo, so the agent makes sure the sandbox has a C compiler before anything else. Then it writes a test that opens a database exactly as Init does and runs several goroutines against it.
The reproduction separates two shapes of write, and they behave differently. Goroutines that each issue a single Create do not fail on this setup: SQLite lets one writer in at a time and the others wait their turn. Goroutines that read and then write inside one db.Transaction do fail, a share of them at once, with exactly the error in the alert. The driver begins a transaction as deferred, which takes no write lock until the first write. Two transactions can therefore both read, and when the second tries to write after the first has, SQLite refuses it immediately, because waiting could never succeed. That is why the usual advice does not help. With the same test, adding _journal_mode=WAL and _busy_timeout=5000 to the connection string leaves the failures in place. Adding _txlock=immediate, which makes every transaction take the write lock when it begins, removes them.
With the cause known, the agent looks for that shape in the code and reads every Begin and Transaction. This repository has one today, in GetArticleFeed in articles/models.go, and it only reads; the handlers' writes, such as SaveOne and Update, are single statements outside any transaction. So the failing path in a codebase like this is whichever handler was most recently wrapped in a transaction that checks before it saves, and the alert payload, which names the endpoint, tells the agent where to look. The same reading rules out the other common fix. SetMaxOpenConns(1) also makes the test pass, but GetArticleFeed opens a transaction and then calls GetFollowings, which goes back to the global handle from common.GetDB(). With a single connection that inner query waits for the connection its own transaction is holding, and the feed endpoint would hang.
The fix is in how the database is opened. The agent builds the connection string in one helper used by both Init and TestDBInit, appending _txlock=immediate, _journal_mode=WAL so readers are not blocked while a write is in progress, and an explicit _busy_timeout. WAL mode keeps two extra files next to the database, so it extends TestDBFree, which removes only the .db file, and adds the -wal and -shm names to .gitignore, whose patterns cover *.db alone. The concurrent test stays in the suite as the regression guard, in both shapes, and go test ./... and scripts/gofmt.sh run before the pull request opens.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "An alert fired for this GORM and SQLite application: requests are failing with the error database is locked. The alert payload follows this prompt. Read go.mod, common/database.go, every use of Begin and Transaction, and every function that writes, first. The SQLite driver needs cgo, so make sure a C compiler is installed. Reproduce the error before changing anything: write a test that opens a database exactly as the application does and runs concurrent goroutines, once where each issues a single write and once where each reads and then writes inside one transaction. Record which shape fails, how quickly, and with what error. Then test each candidate fix separately with the same test and report the result of each: a busy timeout, WAL journal mode, immediate transaction locking, and limiting the pool to one open connection. Before recommending a pool limit, check whether any code path opens a transaction and then uses the package-level database handle inside it, and say what would happen to that path. Apply the fix that removes the failures without breaking any path, in the one place the connection is opened, for both the main and the test database. Clean up any extra files the new journal mode creates in tests and ignore them in git. Keep the concurrent test in the suite. Name the code path that matches the alert, or say that none in the repository does and what kind of change would introduce one. Run go test ./... and scripts/gofmt.sh and open a pull request with the reproduction output before and after and the result of every candidate you tried.",
"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 common/database.go, adds a concurrency test to common, and touches .gitignore. The description starts with the reproduction: the test, the two write shapes, and its output on the code as it was, with the failing transactions and their error. Under it is a small table with one row per candidate fix and whether the failures remained, so a reader can see that the timeout and WAL were tried and were not the answer.
The next section ties the finding to the code. It lists each transaction in the repository, says whether it reads before writing, and names the path that matches the alert. If nothing in the repository matches, it says so plainly and describes what would: a handler wrapped in db.Transaction that looks something up and then saves. The note on SetMaxOpenConns(1) and the feed query is there as well, because someone will suggest it in review.
What the reviewer weighs is the journal mode. WAL changes what has to be backed up and does not work on some network filesystems, so a team that copies the single database file somewhere needs to know. The immediate locking setting has a cost too, which the description states: read-only transactions now queue with writers, so they should stay short or use plain queries.
Run it on every alert on a lock error in the logs
Add an automation to the Project in the console with a webhook trigger and keep the secret it shows once. A Grafana alert rule on log lines containing database is locked can call the trigger's URL itself, since a Grafana webhook contact point can send a custom Authorization: Bearer <secret> header. The alert's JSON body, up to 64 KB, is placed after the saved prompt as the event. If your alerting tool cannot set that header, a small handler on your server receives its webhook and forwards the body with the header added.
An alert that keeps firing should not start a run per evaluation. A Grafana contact point sends the same headers on every call, so deduplication needs the handler: have it send an Idempotency-Key header on the trigger's URL, built from the alert's fingerprint, so repeats answer deduped. Without a handler, the automation's max_runs_per_hour bounds the repeats.
The use case this job follows, with its automation and trigger: Fix a bug from an alert.
Why run it on Rush?
A lock error is a concurrency bug, and those are settled by running many writers at once and counting failures, then changing one setting and counting again. The agent does that in its own sandbox with the driver and GORM versions from go.mod, and each test run is kept with its output in the transcript at GET /o/{org}/sessions/{id}/messages. The finding that a busy timeout does not help is an observation from that sandbox, which is worth more in review than a link to a forum answer.
The alert arrives when nobody has time for an experiment. Started from the alert, the run does the experiment while the on-call engineer handles the incident, and what they get back is a pull request that names the cause, shows every remedy that was tried, and carries a test that fails if the setting is ever removed.
Frequently asked questions
Why does a longer busy timeout not fix it?
The timeout applies when a connection waits for a lock it can eventually get. A deferred transaction that has already read and then needs to write behind another writer is in a different position: its view of the database is stale, so SQLite fails it straight away without waiting. Taking the write lock at the start of the transaction avoids ever being in that position.
Should I switch to PostgreSQL instead?
If the application needs many concurrent writers, yes, and that is a larger migration with its own page of work. For one process with modest write volume, SQLite with immediate locking and WAL is a sound setup. The agent fixes what the alert is about and says where the limit is.
Does this apply to the pure-Go SQLite driver?
The cause is SQLite's and applies to any driver, but the setting is spelled differently. The connection string options in this change belong to mattn/go-sqlite3; other drivers take pragmas or their own parameter for the transaction mode. The agent reads which driver go.mod resolves to and uses its syntax.
Will the tests become flaky with a concurrency test in them?
The test asserts zero failures across a fixed number of transactions, and with immediate locking the writers queue, so the outcome does not depend on timing. It uses its own database file. If it ever fails, the setting was removed or a new path bypasses the helper.