go get github.com/avalonbits/sqlflow

// mattn (CGo, supports encryption):
import "github.com/avalonbits/sqlflow/drivers/mattn"
db, err := sqlflow.OpenDB(path, querier, mattn.Driver, ...)

// modernc (pure Go):
import "github.com/avalonbits/sqlflow/drivers/modernc"
db, err := sqlflow.OpenDB(path, querier, modernc.Driver, ...)

// ncruces (WebAssembly):
import "github.com/avalonbits/sqlflow/drivers/ncruces"
db, err := sqlflow.OpenDB(path, querier, ncruces.Driver, ...)

Note

mattn and ncruces both register as "sqlite3" — they cannot coexist in the same binary. modernc registers as "sqlite" and can coexist with ncruces.

package main

import (
	"context"
	"fmt"
	"log"
	"os"
	"testing/fstest"

	"github.com/avalonbits/sqlflow"
	"github.com/avalonbits/sqlflow/drivers/mattn" // or modernc / ncruces
	"github.com/avalonbits/sqlflow/migrators"
)

func main() {
	path := "/tmp/plain.db"
	os.Remove(path)

	db, err := sqlflow.OpenDB(
		// the path to your database file.
		path,
		// A Querier function — sqlflow calls it with the open transaction.
		newKV,
		// Select the driver.
		mattn.Driver,
		// migrators.Goose applies migrations on open.
		migrators.Goose(migrations),
	)
	if err != nil {
		log.Fatal(err)
	}
	defer db.Close()

	ctx := context.Background()

	// Write starts an immediate (exclusive) transaction and runs your func
	// inside it. Blocks if another write is in progress.
	err = db.Write(ctx, func(s *kvStore) error {
		return s.Set(ctx, "hello", "world")
	})
	if err != nil {
		log.Fatal(err)
	}

	var val string

	// Read starts a deferred transaction and can run concurrently with other
	// Read calls (but not with a Write).
	err = db.Read(ctx, func(s *kvStore) error {
		var err error
		val, err = s.Get(ctx, "hello")
		return err
	})
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(val) // world
}

// migrations is an in-memory goose migration set. In production use
// //go:embed with fs.Sub, or os.DirFS, to point at real .sql files.
var migrations = fstest.MapFS{
	"001_init.sql": {
		Data: []byte(`
            -- +goose Up
            CREATE TABLE IF NOT EXISTS kv (key TEXT PRIMARY KEY, val TEXT NOT NULL);

            -- +goose Down
            DROP TABLE kv;
        `),
	},
}

// kvStore wraps a DBTX to provide typed query methods for the kv table.
type kvStore struct{ db sqlflow.DBTX }

// newKV is a sqlflow.Querier: sqlflow calls it with the transaction's
// connection so every method on kvStore automatically runs within that
// transaction — no connection is ever passed around manually.
func newKV(db sqlflow.DBTX) *kvStore { return &kvStore{db: db} }

func (s *kvStore) Set(ctx context.Context, key, val string) error {
	_, err := s.db.ExecContext(ctx,
		`INSERT INTO kv(key,val) VALUES(?,?) ON CONFLICT(key) DO UPDATE SET val=excluded.val`,
		key, val)
	return err
}

func (s *kvStore) Get(ctx context.Context, key string) (string, error) {
	var val string
	err := s.db.QueryRowContext(ctx, `SELECT val FROM kv WHERE key=?`, key).Scan(&val)
	return val, err
}

Note

Pass the plain file path — not a DSN URI. Paths containing file: or ? are rejected with an error. Use WithDSNParams or WithPragma to set connection parameters (see Connection parameters).

pool, err := sqlflow.NewPool(
    dir,                         // directory where per-user .db files are stored
    newKV,                       // same Querier factory as OpenDB
    1_000,                       // max cached open databases
    mattn.Driver,                // select driver
    migrators.Goose(migrations), // options — same as OpenDB
)
if err != nil {
    log.Fatal(err)
}
pool.SetInactivityTimeout(5 * time.Minute) // evict after 5 min idle
defer pool.Close()

ctx := context.Background()

// Read and Write take an extra key argument that selects the database.
if err := pool.Write(ctx, "alice", func(s *kvStore) error {
    return s.Set(ctx, "hello", "world")
}); err != nil {
    log.Fatal(err)
}

var val string
if err := pool.Read(ctx, "alice", func(s *kvStore) error {
    var err error
    val, err = s.Get(ctx, "hello")
    return err
}); err != nil {
    log.Fatal(err)
}

fmt.Println(val) // world

replace github.com/mattn/go-sqlite3 => github.com/jgiannuzzi/go-sqlite3 v1.14.35-0.20260227142656-2c447b9a2806

import "github.com/avalonbits/sqlflow/drivers/mattn" // must use the jgiannuzzi fork

key := make([]byte, 32) // fill with your 32-byte key

db, err := sqlflow.OpenEncryptedDB(
    path, querier, key,
    mattn.Driver,
    migrators.Goose(fsys),
)

version: "2"
sql:
  - engine: "sqlite"
    queries: "queries.sql"
    schema:  "migrations/"
    gen:
      go:
        package:     "store"
        out:         "store"
        sql_package: "database/sql"

Note

Set sql_package: "database/sql" so sqlc generates a DBTX interface backed by the standard library — this is what sqlflow's DBTX is compatible with.

-- queries.sql

-- name: GetUser :one
SELECT id, name FROM users WHERE id = ?;

-- name: CreateUser :exec
INSERT INTO users (id, name) VALUES (?, ?);

import (
    "github.com/avalonbits/sqlflow"
    "github.com/avalonbits/sqlflow/drivers/mattn"
    "github.com/avalonbits/sqlflow/migrators"
    "myapp/store"
)

db, err := sqlflow.OpenDB(
    "/var/data/app.db",
    store.New,                   // sqlc-generated constructor, no wrapper needed
    mattn.Driver,
    migrators.Goose(migrationsFS),
)

err = db.Write(ctx, func(q *store.Queries) error {
    return q.CreateUser(ctx, store.CreateUserParams{ID: 1, Name: "Alice"})
})

err = db.Read(ctx, func(q *store.Queries) error {
    user, err := q.GetUser(ctx, 1)
    fmt.Println(user.Name) // Alice
    return err
})