View Source

var ErrPageCacheConflict = errors.New(
	"sqlite: a different page cache module is already registered")

View Source

var ErrPageCacheTooLate = errors.New(
	"sqlite: RegisterPageCache called after first Open; " +
		"SQLITE_CONFIG_PCACHE2 must be installed before any connection is opened")

View Source

var (

	ErrorCodeString = map[int]string{
		sqlite3.SQLITE_ABORT:             "Callback routine requested an abort (SQLITE_ABORT)",
		sqlite3.SQLITE_AUTH:              "Authorization denied (SQLITE_AUTH)",
		sqlite3.SQLITE_BUSY:              "The database file is locked (SQLITE_BUSY)",
		sqlite3.SQLITE_CANTOPEN:          "Unable to open the database file (SQLITE_CANTOPEN)",
		sqlite3.SQLITE_CONSTRAINT:        "Abort due to constraint violation (SQLITE_CONSTRAINT)",
		sqlite3.SQLITE_CORRUPT:           "The database disk image is malformed (SQLITE_CORRUPT)",
		sqlite3.SQLITE_DONE:              "sqlite3_step() has finished executing (SQLITE_DONE)",
		sqlite3.SQLITE_EMPTY:             "Internal use only (SQLITE_EMPTY)",
		sqlite3.SQLITE_ERROR:             "Generic error (SQLITE_ERROR)",
		sqlite3.SQLITE_FORMAT:            "Not used (SQLITE_FORMAT)",
		sqlite3.SQLITE_FULL:              "Insertion failed because database is full (SQLITE_FULL)",
		sqlite3.SQLITE_INTERNAL:          "Internal logic error in SQLite (SQLITE_INTERNAL)",
		sqlite3.SQLITE_INTERRUPT:         "Operation terminated by sqlite3_interrupt()(SQLITE_INTERRUPT)",
		sqlite3.SQLITE_IOERR | (1 << 8):  "(SQLITE_IOERR_READ)",
		sqlite3.SQLITE_IOERR | (10 << 8): "(SQLITE_IOERR_DELETE)",
		sqlite3.SQLITE_IOERR | (11 << 8): "(SQLITE_IOERR_BLOCKED)",
		sqlite3.SQLITE_IOERR | (12 << 8): "(SQLITE_IOERR_NOMEM)",
		sqlite3.SQLITE_IOERR | (13 << 8): "(SQLITE_IOERR_ACCESS)",
		sqlite3.SQLITE_IOERR | (14 << 8): "(SQLITE_IOERR_CHECKRESERVEDLOCK)",
		sqlite3.SQLITE_IOERR | (15 << 8): "(SQLITE_IOERR_LOCK)",
		sqlite3.SQLITE_IOERR | (16 << 8): "(SQLITE_IOERR_CLOSE)",
		sqlite3.SQLITE_IOERR | (17 << 8): "(SQLITE_IOERR_DIR_CLOSE)",
		sqlite3.SQLITE_IOERR | (2 << 8):  "(SQLITE_IOERR_SHORT_READ)",
		sqlite3.SQLITE_IOERR | (3 << 8):  "(SQLITE_IOERR_WRITE)",
		sqlite3.SQLITE_IOERR | (4 << 8):  "(SQLITE_IOERR_FSYNC)",
		sqlite3.SQLITE_IOERR | (5 << 8):  "(SQLITE_IOERR_DIR_FSYNC)",
		sqlite3.SQLITE_IOERR | (6 << 8):  "(SQLITE_IOERR_TRUNCATE)",
		sqlite3.SQLITE_IOERR | (7 << 8):  "(SQLITE_IOERR_FSTAT)",
		sqlite3.SQLITE_IOERR | (8 << 8):  "(SQLITE_IOERR_UNLOCK)",
		sqlite3.SQLITE_IOERR | (9 << 8):  "(SQLITE_IOERR_RDLOCK)",
		sqlite3.SQLITE_IOERR:             "Some kind of disk I/O error occurred (SQLITE_IOERR)",
		sqlite3.SQLITE_LOCKED | (1 << 8): "(SQLITE_LOCKED_SHAREDCACHE)",
		sqlite3.SQLITE_LOCKED:            "A table in the database is locked (SQLITE_LOCKED)",
		sqlite3.SQLITE_MISMATCH:          "Data type mismatch (SQLITE_MISMATCH)",
		sqlite3.SQLITE_MISUSE:            "Library used incorrectly (SQLITE_MISUSE)",
		sqlite3.SQLITE_NOLFS:             "Uses OS features not supported on host (SQLITE_NOLFS)",
		sqlite3.SQLITE_NOMEM:             "A malloc() failed (SQLITE_NOMEM)",
		sqlite3.SQLITE_NOTADB:            "File opened that is not a database file (SQLITE_NOTADB)",
		sqlite3.SQLITE_NOTFOUND:          "Unknown opcode in sqlite3_file_control() (SQLITE_NOTFOUND)",
		sqlite3.SQLITE_NOTICE:            "Notifications from sqlite3_log() (SQLITE_NOTICE)",
		sqlite3.SQLITE_PERM:              "Access permission denied (SQLITE_PERM)",
		sqlite3.SQLITE_PROTOCOL:          "Database lock protocol error (SQLITE_PROTOCOL)",
		sqlite3.SQLITE_RANGE:             "2nd parameter to sqlite3_bind out of range (SQLITE_RANGE)",
		sqlite3.SQLITE_READONLY:          "Attempt to write a readonly database (SQLITE_READONLY)",
		sqlite3.SQLITE_ROW:               "sqlite3_step() has another row ready (SQLITE_ROW)",
		sqlite3.SQLITE_SCHEMA:            "The database schema changed (SQLITE_SCHEMA)",
		sqlite3.SQLITE_TOOBIG:            "String or BLOB exceeds size limit (SQLITE_TOOBIG)",
		sqlite3.SQLITE_WARNING:           "Warnings from sqlite3_log() (SQLITE_WARNING)",
	}
)

Limit calls sqlite3_limit, see the docs at https://www.sqlite.org/c3ref/limit.html for details.

To get a sql.Conn from a *sql.DB, use (*sql.DB).Conn(). Limits are bound to the particular instance of 'c', so getting a new connection only to pass it to Limit is possibly not useful above querying what are the various configured default values.

func MustRegisterCollationUtf8(
	zName string,
	impl func(left, right string) int,
)

MustRegisterCollationUtf8 is like RegisterCollationUtf8 but panics on error.

MustRegisterDeterministicScalarFunction is like RegisterDeterministicScalarFunction but panics on error.

func MustRegisterFunction(
	zFuncName string,
	impl *FunctionImpl,
)

MustRegisterFunction is like RegisterFunction but panics on error.

func MustRegisterPageCache(m PageCache)

MustRegisterPageCache is like RegisterPageCache but panics on any error. Intended for init() use where a missing page cache is fatal. Mirrors the precedent set by MustRegisterDeterministicScalarFunction.

MustRegisterScalarFunction is like RegisterScalarFunction but panics on error.

NewConnector returns a driver.Connector that opens connections to dsn using the driver this package registers as "sqlite" -- the one carrying every function, collation, connection hook and virtual table module registered through RegisterFunction, RegisterScalarFunction, RegisterDeterministicScalarFunction, RegisterCollationUtf8, RegisterConnectionHook and vtab.RegisterModule. The dsn syntax and the supported query parameters are documented on Driver.Open.

The returned value is intended for sql.OpenDB:

c, err := sqlite.NewConnector("file:app.db?_pragma=foreign_keys(1)")
if err != nil {
	return err
}
db := sql.OpenDB(c)
defer db.Close()

For opening a database this is equivalent to sql.Open("sqlite", dsn). It exists for callers that need to interpose on the physical connections database/sql opens -- tracing, metrics, or connection-scoped setup. Such a caller can embed the returned Connector, override Connect, and pass its own wrapper to sql.OpenDB:

type tracer struct{ driver.Connector }
func (t tracer) Connect(ctx context.Context) (driver.Conn, error) {
	conn, err := t.Connector.Connect(ctx)
	// ... wrap conn ...
	return conn, err
}
base, err := sqlite.NewConnector(dsn)
if err != nil {
	return err
}
db := sql.OpenDB(tracer{base})

Reaching the same driver through sql.Open requires sql.Register, which is process-global, rejects a name it has already seen with a panic, and offers no way to undo a registration; a library doing the above would have to invent a unique name per configuration. sql.OpenDB registers nothing.

The dsn is checked here only as far as it can be without opening a database: a query string that does not parse, such as one carrying an invalid percent-escape, and conflicting vfs parameters are reported immediately. Everything else is validated when the connection is opened, so an unknown parameter or an out-of-range value is reported by Connect, and hence by the first use of the sql.DB, rather than by NewConnector.

The returned Connector is safe for concurrent use; database/sql calls Connect from multiple goroutines as it grows the pool. As with sql.Open, it does not itself open a connection.

RegisterCollationUtf8 makes a Go function available as a collation named zName. impl receives two UTF-8 strings: left and right. The result needs to be:

- 0 if left == right - 1 if left < right - +1 if left > right

impl must always return the same result given the same inputs. Additionally, it must have the following properties for all strings A, B and C: - if A==B, then B==A - if A==B and B==C, then A==C - if A<B, then B>A - if A<B and B<C, then A<C.

The new collation will be available to all new connections opened after executing RegisterCollationUtf8.

func RegisterConnectionHook(fn ConnectionHookFn)

RegisterConnectionHook registers a function to be called after each connection is opened. This is called after all the connection has been set up.

RegisterDeterministicScalarFunction registers a deterministic scalar function named zFuncName with nArg arguments. Passing -1 for nArg indicates the function is variadic. A deterministic function means that the function always gives the same output when the input parameters are the same.

The new function will be available to all new connections opened after executing RegisterDeterministicScalarFunction.

RegisterFunction registers a function named zFuncName with nArg arguments. Passing -1 for nArg indicates the function is variadic. The FunctionImpl determines whether the function is deterministic or not, and whether it is a scalar function (when Scalar is defined) or an aggregate function (when Scalar is not defined and MakeAggregate is defined).

The new function will be available to all new connections opened after executing RegisterFunction.

func RegisterPageCache(m PageCache) error

RegisterPageCache installs m as the process-global SQLite page cache via SQLITE_CONFIG_PCACHE2. It MUST be called before the first sql.Open or driver.Open in the program.

Concurrency contract:

• Safe to call concurrently with itself and with other Register* entry points.
• Blocks until any sql.Open calls currently in progress complete. Trade-off: a Register call may block for the duration of an in-flight Open. WAL recovery or cold-file-lock contention can make that wait visible.
• Once any connection has been opened, returns ErrPageCacheTooLate without mutating the global module slot.
• Calling twice with the same module value is a no-op success. Calling twice with a different value returns ErrPageCacheConflict.
• A failed first install is sticky: every subsequent Register call returns the same error. Mutating the module fields after the first successful Register is silently ignored because SQLite has already copied the C methods table.

RegisterScalarFunction registers a scalar function named zFuncName with nArg arguments. Passing -1 for nArg indicates the function is variadic.

The new function will be available to all new connections opened after executing RegisterScalarFunction.

type Backup struct {
}

Backup object is used to manage progress and cleanup an online backup. It is returned by NewBackup or NewRestore.

func (b *Backup) PageCount() int

func (b *Backup) Remaining() int

type Cache interface {


	SetSize(n int)


	PageCount() int


	Fetch(key uint32, mode FetchMode) Page


	Unpin(p Page, discard bool)


	Rekey(p Page, oldKey, newKey uint32)


	Truncate(limit uint32)


	Destroy()


	Shrink()
}

Cache is one database's worth of cached pages. All callbacks for a single Cache are serialised by the SQLite engine: this driver opens every connection SQLITE_OPEN_FULLMUTEX without shared-cache mode, and database/sql never invokes one driver.Conn from two goroutines, so an implementation does not need to synchronise per-Cache state against concurrent calls.

Implementations should NOT call RegisterPageCache directly or transitively. Callbacks run under the openGate read lock that the Open path holds, and a re-entrant Register would deadlock on the gate's write lock.

type CommitHookFn func() int32

ConnectionHookFn function type for a connection hook on the Driver. Connection hooks are called after the connection has been set up.

type DBStatus interface {


	Status(op DBStatusOp, reset bool) (current, high int, err error)
}

DBStatus exposes sqlite3_db_status, the per-connection runtime counters (cache hit/miss/write/spill rates, schema and prepared-statement memory, lookaside usage, deferred foreign keys). Reach it through the database/sql escape hatch, the same way as FileControl:

err := sqlConn.Raw(func(dc any) error {
	cur, _, err := dc.(sqlite.DBStatus).Status(sqlite.DBStatusCacheSpill, false)
	if err != nil {
		return err
	}
	// use cur
	return nil
})

DBStatusOp identifies a per-connection runtime counter readable through DBStatus.Status. The values mirror the SQLITE_DBSTATUS_* verbs of the C API; the distinct type keeps a counter from a different family (for example a file-control or db-config op) from compiling in its place.

See https://www.sqlite.org/c3ref/c_dbstatus_options.html for the per-op semantics.

type Driver struct {
}

Driver implements database/sql/driver.Driver.

Registration functions and methods must be called before the first call to Open.

Most code has no use for this type. sql.Open("sqlite", dsn) and NewConnector both go through the driver this package registers as "sqlite", which carries everything registered with RegisterFunction, RegisterScalarFunction, RegisterDeterministicScalarFunction, RegisterCollationUtf8, RegisterConnectionHook and vtab.RegisterModule.

A Driver a caller constructs is not equivalent to that one. Its fields are unexported, so it starts out with no functions, collations or connection hooks, and the only way to give it any is Driver.RegisterConnectionHook; the package-level registration functions always apply to the registered driver, never to a constructed one. Connections it opens therefore run without the package-level functions and collations -- and where such a registration overrides a SQLite built-in of the same name, they run with SQLite's built-in in force instead. Virtual table modules are the one exception: they are held process-globally and reach every Driver.

Constructing one is supported for the private-hook pattern: a driver registered under a name of its own with sql.Register, so that its connection hooks apply to its own connections rather than to every connection in the process. Prefer sql.Open or NewConnector for anything else.

_busy_timeout, _timeout   -> PRAGMA busy_timeout   (an integer)
_foreign_keys, _fk        -> PRAGMA foreign_keys   (0 1 false true no yes off on)
_journal_mode, _journal   -> PRAGMA journal_mode   (DELETE TRUNCATE PERSIST MEMORY WAL OFF)
_synchronous, _sync       -> PRAGMA synchronous    (0 OFF 1 NORMAL 2 FULL 3 EXTRA)
_auto_vacuum, _vacuum     -> PRAGMA auto_vacuum    (0 NONE 1 FULL 2 INCREMENTAL)
_query_only               -> PRAGMA query_only     (0 1 false true no yes off on)

func (d *Driver) RegisterConnectionHook(fn ConnectionHookFn)

type Error struct {
}

Error represents sqlite library error code.

func (e *Error) Code() int

FetchMode tells Cache.Fetch how aggressively to allocate when the requested key is absent. It matches the createFlag of SQLite's xFetch (https://sqlite.org/c3ref/pcache_methods2.html).

const (


	FetchLookup FetchMode = 0


	FetchCreateEasy FetchMode = 1


	FetchCreateForce FetchMode = 2
)

Access to sqlite3_file_control

type FunctionContext struct {
}

FunctionContext represents the context user defined functions execute in. Fields and/or methods of this type may get addedd in the future.

FunctionImpl describes an application-defined SQL function. If Scalar is set, it is treated as a scalar function; otherwise, it is treated as an aggregate function using MakeAggregate.

type HookRegisterer interface {
	RegisterPreUpdateHook(PreUpdateHookFn)
	RegisterCommitHook(CommitHookFn)
	RegisterRollbackHook(RollbackHookFn)
}

Page is one cache entry. Buf and Extra return pointers into implementation-owned memory that MUST remain valid and at the same addresses for the duration of the pin: from the Fetch that returned the Page until the matching Unpin. While the page is unpinned the implementation is free to release the memory; the next Fetch for the same key will be consulted afresh and may return either the same Page (memory retained) or a different one.

The memory MUST be off-heap: libc.Xmalloc, sqlite3_malloc, mmap, or an equivalent allocator outside the Go heap. Go-heap memory is forbidden, including memory pinned with runtime.Pinner: SQLite stores Extra addresses inside its own C structures and performs interior pointer arithmetic on them (it overlays PgHdr at the head of Extra), which trips Go's checkptr enforcement under -race the moment _sqlite3PcacheFetchFinish runs. Pinned slices preserve the allocation but lose checkptr provenance through the binding's unsafe.Pointer round-trip, so the failure surfaces only under the race detector and not in normal test runs.

Page values are compared by the binding to detect whether the implementation retained or replaced the cached entry across a Fetch cycle, so Page MUST be a comparable type. Pointer-backed implementations (the natural shape) satisfy this automatically.

Buf must be at least pageSize bytes and is where SQLite stores the database page contents. Extra must be at least extraSize bytes (the extraSize passed to PageCache.Create, which already includes SQLite's PgHdr overhead) and is treated by SQLite as opaque scratch space. Implementations should zero Extra on a freshly-allocated Page so SQLite's PgHdr backpointer is read as null; the binding does not touch Extra contents.

type PageCache interface {
	Create(pageSize, extraSize int, purgeable bool) (Cache, error)
}

PageCache is the factory for per-database Cache instances. SQLite calls Create once per open database; each call must return a fresh Cache with the given pageSize and extraSize. The extraSize includes SQLite's private PgHdr overhead and must be honoured as the opaque size of every Page's Extra buffer.

purgeable is advisory: when false (in-memory databases), SQLite will only call Unpin with discard=true and the cache is permitted to free every page on Unpin. When true, the cache may retain unpinned pages for re-use.

type PreUpdateHookFn func(SQLitePreUpdateData)

type RollbackHookFn func()