go-sqlite3 Week: Failed Transaction Cleanup Now Discards Pinned Connections


mattn/go-sqlite3 is the classic cgo SQLite driver for Go. Last week brought 8 commits that touch 17 files, and the headline theme is connection state safety: the driver now tells database/sql to throw away a connection when transaction cleanup fails, instead of letting a half finished transaction get reused. A second theme is callback panic handling on the Exec path.

The most operator visible change landed on November 17. When Commit() hits an error and the driver then runs a cleanup ROLLBACK, or when Rollback() itself fails, the driver now returns driver.ErrBadConn wrapped into the original error with errors.Join. A pooled sql.Conn that is pinned in this state no longer gets handed back out with an unfinished transaction attached.

That matters because the failure mode was nasty and quiet. With SetMaxOpenConns(1) or a single connection pool, a deferred foreign key violation inside a transaction could leave the connection carrying open transaction state. The next query on that connection could see rows that were never committed. The new test in sqlite3_session_test.go pins this exact scenario using an authorizer that denies ROLLBACK, then asserts the pool serves reads through a replacement connection while the pinned one stays unusable.

The commit for that change is 9842363, and the core of it is small:

func (tx *SQLiteTx) Rollback() error {
    if err != nil {
        tx.c.mu.Lock()
        tx.c.rollbackFailed = true
        tx.c.mu.Unlock()
        return errors.Join(err, driver.ErrBadConn)
    }
    return err
}

The comment in the diff is worth reading. database/sql checks connection validity, but a pinned sql.Conn is not in that path, so validity alone cannot stop reuse. Returning ErrBadConn is what forces the pool to discard it. Callers keep the original SQLite error code, such as ErrConstraint or ErrAuth, because errors.Join preserves both. Code that checks errors.Is(err, sqlite3.ErrConstraint) keeps working. Code that treated any rollback failure as retryable now sees ErrBadConn and needs a fresh connection, which is the correct behavior anyway.

The earlier commit db8eb10 started this line of work by preserving connections after transaction cancellation. The new commit closes the other side: when preservation is not safe, discard loudly.

If you call ExecContext with a cancellable context, the driver wraps execution so it can be interrupted, and callback panics raised from SQLite user callbacks previously got swallowed on that path. Commit acbd4cd carries those panics back to the caller. A follow up, 6b1a07f, re-raises panics from the Exec fast path and keeps the first one when several are pending.

Supporting changes include a new callback_panic_test.go file, [c15dd22](https://github.com/mattn/go-sqlite3/commit/c15dd2283fadf0619b8d91331echanges made in callback.go and sqlite3.go carry the plumbing. Net effect for users: a panic inside a registered callback no longer vanishes into a vague error. Your stack trace points at your callback. That is the difference between minutes and hours of debugging on a busy write path.

A quieter refactor worth noting is fdc2823. The driver now registers itself from a register.go file shared by both build modes. Previously the cgo and non cgo files each had their own init() calling sql.Register, which is a footgun if both end up linked into one binary: the second registration panics with a duplicate driver name error.

Nothing changes for applications, since database/sql rejects duplicate registration either way. The value is structural. One call site means one place to audit, and static_mock.go now exists to keep the non cgo build compiling without bindings.

Mostly internal, but it prevents a class of linking bugs that show up as a panic at process start.

Commit 092c6d4 defines _WIN32_WINNT at the Vista level when building for Windows. The SQLite binding uses TryLock style primitives on Windows that reference Vista APIs, and without the define the build can fail on newer toolchains. One line, unblocks Windows CI.

  • Watch how your error handling treats rollback and commit failures. If you retry on any non nil error, ErrBadConn joined into the error will make the pool discard the connection on the next use. Confirm your retry paths wrap errors.Is checks for both driver.ErrBadConn and the SQLite codes.
  • The test for INSERT RETURNING suggests the write transaction release behavior around RETURNING clauses is still being pinned down. If you use INSERT ... RETURNING on hot paths, follow the sqlite3.go history.
  • The repo overall is mattn/go-sqlite3 on branch master. These changes are not yet in a tagged release, so wait for a tag before pinning.