main ede6efa

Go bindings for SQLite via purego instead of cgo.

purego-sqlite

Go bindings for SQLite via purego instead of cgo.

Linux only. CGO_ENABLED=0.

[!WARNING] This is early stage. The full SQLite C API (~350 functions) is bound, but the database/sql driver covers the common path only. API may change.

Architecture

The binding layer is generated from sqlite3.h. The generator parses the system header and produces:

  • purego function bindings for all ~350 non-variadic SQLite functions
  • Typed SyscallN wrappers for variadic functions at known arities
  • Outbound port interfaces grouped by API surface (Lifecycle, Prepare, Column, Bind, etc.)
  • A composite CAPI interface embedding all port groups
  • Inbound port interfaces (DB, Stmt, Rows, Result) for the public API
  • Public API composition root wiring everything together

A hand-written core domain (~500 LOC) implements the business logic: open, prepare, bind, step, scan, close. A thin database/sql/driver adapter sits on top.

Mocks for all interfaces are generated by Mockery v3 and shipped in sqlite/mocks/.

Usage

database/sql driver

import (
    "database/sql"
    _ "github.com/bnema/purego-sqlite/driver"
)

db, err := sql.Open("sqlite3", "./my.db")

QueryContext, ExecContext, PrepareContext, and BeginTx use direct SQLite paths. Cancelling a context interrupts only its active operation; the connection remains safe to reuse after rows are closed or exhausted.

Direct API

import "github.com/bnema/purego-sqlite/sqlite"

db, err := sqlite.Open("./my.db")
defer db.Close()

stmt, _ := db.Prepare("SELECT name FROM users WHERE id = ?")
rows, _ := stmt.Query(42)

Testing with mocks

The package ships pre-generated Mockery v3 mocks for all public interfaces. Your code accepts sqlite.DB (an interface), and in tests you swap in a mock — no libsqlite3.so needed.

Step 1: Accept the interface in your code

package userrepo

import "github.com/bnema/purego-sqlite/sqlite"

type UserRepo struct {
    db sqlite.DB
}

func New(db sqlite.DB) *UserRepo {
    return &UserRepo{db: db}
}

func (r *UserRepo) GetName(id int) (string, error) {
    rows, err := r.db.Query("SELECT name FROM users WHERE id = ?", id)
    if err != nil {
        return "", err
    }
    defer rows.Close()
    if !rows.Next() {
        return "", fmt.Errorf("user %d not found", id)
    }
    var name string
    if err := rows.Scan(&name); err != nil {
        return "", err
    }
    return name, nil
}

Step 2: Mock it in tests

package userrepo_test

import (
    "testing"

    "github.com/bnema/purego-sqlite/sqlite/mocks"
    "github.com/stretchr/testify/require"
)

func TestGetName(t *testing.T) {
    // Create mocks — expectations are auto-asserted on cleanup
    mockDB := mocks.NewMockDB(t)
    mockRows := mocks.NewMockRows(t)

    // Set up the call chain
    mockDB.EXPECT().
        Query("SELECT name FROM users WHERE id = ?", 42).
        Return(mockRows, nil)
    mockRows.EXPECT().Next().Return(true)
    mockRows.EXPECT().Scan().RunAndReturn(func(dest ...any) error {
        *(dest[0].(*string)) = "Alice"
        return nil
    })
    mockRows.EXPECT().Close().Return(nil)

    // Test
    repo := userrepo.New(mockDB)
    name, err := repo.GetName(42)
    require.NoError(t, err)
    require.Equal(t, "Alice", name)
}

Available mocks in github.com/bnema/purego-sqlite/sqlite/mocks:

Mock Interface Key methods
MockDB sqlite.DB Prepare, Exec, Query, Interrupt, Close
MockStmt sqlite.Stmt Exec, Query, NumInput, Close
MockRows sqlite.Rows Next, Scan, Columns, Err, Close
MockResult sqlite.Result LastInsertId, RowsAffected

All mocks support .EXPECT() for type-safe expectations and .On()/.Return() for classic testify style.

Note: The driver registers as sqlite3, the same name as mattn/go-sqlite3. Do not import both in the same binary.

Requirements

  • Go 1.23+
  • SQLite runtime library: libsqlite3.so or the common versioned SONAME libsqlite3.so.0
  • Optional strict override path: SQLITE_LIB_PATH=/custom/path/libsqlite3.so (when set, no default names are tried)

Building

CGO_ENABLED=0 go build ./...
CGO_ENABLED=0 go test ./...

Integration tests need libsqlite3.so:

go test -tags integration ./integration/

Row decoding

The database/sql driver returns time.Time values only for result columns whose SQLite declared type is DATE, DATETIME, or TIMESTAMP. Date-shaped values in ordinary TEXT columns remain strings. Expressions and columns without a declared type likewise remain their SQLite storage type.

Regenerating bindings

go generate ./...

Or manually:

go run ./cmd/sqlitegen --header /usr/include/sqlite3.h --output-dir .
mockery

Project layout

sqlite/              public API (generated) + mocks
driver/              database/sql adapter (hand-written)
internal/
  ports/in/          inbound port interfaces (generated)
  ports/out/         outbound port interfaces (generated) + mocks
  core/              domain logic: open, prepare, bind, step, scan (hand-written)
  capi/              purego bindings + bridge (generated + hand-written)
  loader/            dlopen libsqlite3.so (hand-written)
cmd/sqlitegen/       binding generator (parser, model, emitter, templates)
integration/         integration tests (require libsqlite3.so)

License

MIT

Keyboard shortcuts

Single-key shortcuts are on. ctrl k and esc work whatever this says.

ctrl k :
go to a section, branch, tag, file or repository
?
this list
j k
move the row cursor down / up
enter
open the row under the cursor; on Files, a directory opens or closes in place
↑ ↓ ← → home end
in the file tree (focus on a row): previous / next row, close / open a directory or go to its parent / first entry, first / last row. They never open a file
l h
on Files: open a directory or a file / close a directory or go up to its parent, then to the parent page. On pages with a side panel: into the panel (on a merge request, its files) / back to the content; there j k move between its controls
g g G
first / last row
/
filter the list; on Files, find a file anywhere in the repository (esc clears, enter opens the best match)
b
switch branch or tag
g s g f g c g b g m g i g r g a
tabs: summary, files, commits, branches & tags, merge requests, issues, releases, actions (when available)
g h
home
w
wide mode: use the whole width of the screen, or not (remembered)
y
copy a permalink pinned to the commit; in a file, click a line number to select it, shift-click for a range
d u x
diff: split / unified / collapse or expand all
e E
diff: the whole file in view / every file, with the lines the hunks hide
n
merge request: next note in the diff
esc
close a dialog, leave a field

Branches 2

Tags 6

↑↓ moveenter openesc close