Modernc SQLite

https://pkg.go.dev/modernc.org/sqlite
Admin
A pure Go SQL database driver providing a CGo-free port of SQLite3 with support for virtual tables...
Tokens:214,123
Snippets:1,576
Trust Score:9.6
Update:11 hours ago
Show doc for...
Tokens:
Raw
### Run the connector example

Source: https://pkg.go.dev/modernc.org/sqlite/examples/connector

Run the example with `go run ./examples/connector` from the module root.

```bash
go run ./examples/connector
```

--------------------------------

### Open database with NewConnector and sql.OpenDB

Source: https://pkg.go.dev/modernc.org/sqlite

Example of using NewConnector to open a database with sql.OpenDB, including error handling and deferring the close.

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

```

--------------------------------

### Benchmark results output

Source: https://pkg.go.dev/modernc.org/sqlite/benchmark

Example output from running the benchmarks, showing performance ratios and timings for each benchmark operation.

```text
=== RUN   Test_BenchmarkSQLite

goos:   darwin
goarch: amd64
cpu:    Intel(R) Core(TM) i7-9750H CPU @ 2.60GHz
repeat: 1 time(s)
in-memory SQLite: false

bench_create_index                  |  1.80x | CGo: 120.880 ms/op | Pure-Go: 217.574 ms/op
bench_select_on_string_comparison   |  2.25x | CGo:  19.326 ms/op | Pure-Go:  43.498 ms/op
bench_select_with_index             |  5.84x | CGo:   0.002 ms/op | Pure-Go:   0.014 ms/op
bench_select_without_index          |  1.50x | CGo:   6.071 ms/op | Pure-Go:   9.111 ms/op
bench_insert                        |  1.17x | CGo:   0.481 ms/op | Pure-Go:   0.565 ms/op
bench_insert_in_transaction         |  1.78x | CGo:   0.004 ms/op | Pure-Go:   0.006 ms/op
bench_insert_into_indexed           |  1.62x | CGo:   0.008 ms/op | Pure-Go:   0.013 ms/op
bench_insert_from_select            |  1.80x | CGo:  30.409 ms/op | Pure-Go:  54.703 ms/op
bench_update_text_with_index        |  3.26x | CGo:   0.004 ms/op | Pure-Go:   0.013 ms/op
bench_update_with_index             |  4.20x | CGo:   0.003 ms/op | Pure-Go:   0.011 ms/op
bench_update_without_index          |  1.40x | CGo:   6.421 ms/op | Pure-Go:   9.010 ms/op
bench_delete_without_index          |  1.28x | CGo: 180.734 ms/op | Pure-Go: 231.105 ms/op
bench_delete_with_index             |  1.85x | CGo:  34.284 ms/op | Pure-Go:  63.569 ms/op
--- PASS: Test_BenchmarkSQLite (171.62s)
```

--------------------------------

### Wrap Connector with tracer for sql.OpenDB

Source: https://pkg.go.dev/modernc.org/sqlite

Example of embedding the returned Connector and overriding Connect to wrap connections, then passing the wrapper to sql.OpenDB.

```go
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})

```

--------------------------------

### RegisterPageCache

Source: https://pkg.go.dev/modernc.org/sqlite

Installs a process-global SQLite page cache. Must be called before the first sql.Open or driver.Open in the program.

```APIDOC
## RegisterPageCache

### Description
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. 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.

### Function Signature
```go
func RegisterPageCache(m PageCache) error
```

### Parameters
- **m** (PageCache) - Required - The page cache implementation to install.

### Return Value
- **error** - Returns an error if installation fails.
```

--------------------------------

### Connect to SQLite with database/sql using modernc.org/sqlite

Source: https://pkg.go.dev/modernc.org/sqlite

Shows the minimal import and connection setup for opening a SQLite database with the modernc.org/sqlite driver. The dsnURI can be a plain file name or a file: URI with optional query parameters. The driver is registered via the blank import.

```go
import (
	"database/sql"

	_ "modernc.org/sqlite"
)

...

db, err := sql.Open("sqlite", dsnURI)

...
```

--------------------------------

### Using DBStatus via sql.Raw

Source: https://pkg.go.dev/modernc.org/sqlite

Shows how to access DBStatus through the database/sql escape hatch using sql.Conn.Raw. The example retrieves the cache spill counter without resetting it.

```go
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
})
```

--------------------------------

### Import modernc.org/sqlite/vec for side effect

Source: https://pkg.go.dev/modernc.org/sqlite/vec

Import the package for its side effect, which installs the extension with sqlite3_auto_extension so every connection opened afterwards has it loaded.

```go
import (
	"database/sql"

	_ "modernc.org/sqlite"
	_ "modernc.org/sqlite/vec"
)
```

--------------------------------

### Xvec0_get_auxiliary_value_for_rowid

Source: https://pkg.go.dev/modernc.org/sqlite/vec

Gets the value of an auxiliary column for the given rowid.

```APIDOC
## Xvec0_get_auxiliary_value_for_rowid

### Description
Gets the value of an auxiliary column for the given rowid.

### Function Signature
```go
func Xvec0_get_auxiliary_value_for_rowid(tls *libc.TLS, pVtab uintptr, rowid Ti64, auxiliary_idx int32, outValue uintptr) (r int32)
```

### Parameters
- **tls** (*libc.TLS) - Required - Thread-local storage pointer.
- **pVtab** (uintptr) - Required - Pointer to the vec0_vtab.
- **rowid** (Ti64) - Required - The rowid of the row to lookup.
- **auxiliary_idx** (int32) - Required - Aux index of the column we care about.
- **outValue** (uintptr) - Required - Output sqlite3_value to store.

### Return Value
- **r** (int32) - SQLITE_OK on success, error code otherwise.
```

--------------------------------

### Set up go.work to use local libc

Source: https://pkg.go.dev/modernc.org/sqlite

Commands to set up a go.work file that includes the local patched libc and the current sqlite repository, so the build system uses the modified libc.

```shell
0:jnml@e5-1650:~/src/modernc.org/sqlite$ go work use $(go env GOPATH)/src/modernc.org/libc
0:jnml@e5-1650:~/src/modernc.org/sqlite$ go work use .
```

--------------------------------

### Register an fs.FS as a SQLite VFS and open a database

Source: https://pkg.go.dev/modernc.org/sqlite/vfs

Shows how to register a directory as a read-only VFS and open a database using the returned name in the DSN query parameter. The VFS is read-only and refuses to create a journal.

```go
name, fsvfs, err := vfs.New(os.DirFS(dir))
if err != nil {
	return err
}

defer fsvfs.Close()

db, err := sql.Open("sqlite", "file:test.db?vfs="+name)
```

--------------------------------

### type Error

Source: https://pkg.go.dev/modernc.org/sqlite

Error type represents a SQLite error and provides methods to get the error code and message.

```APIDOC
## type Error

### Description
Error type represents a SQLite error and provides methods to get the error code and message.

### Methods

#### func (e *Error) Code() int

Returns the SQLite error code.

#### func (e *Error) Error() string

Returns the error message.
```

--------------------------------

### Run benchmarks with go test

Source: https://pkg.go.dev/modernc.org/sqlite/benchmark

Command to run the benchmark suite. Use `-mem` flag to use in-memory SQLite, `-rep` to repeat benchmarks for stability.

```bash
go test -v .
```

--------------------------------

### ErrNotImplemented variable definition

Source: https://pkg.go.dev/modernc.org/sqlite/vtab

Defines the ErrNotImplemented variable, returned by RegisterModule when the underlying engine has not yet installed a registration hook.

```go
var ErrNotImplemented = errors.New("vtab: RegisterModule not wired into engine")
```

--------------------------------

### Driver.Open method

Source: https://pkg.go.dev/modernc.org/sqlite

Signature for the Open method, which opens a connection.

```go
func (d *Driver) Open(name string) (conn driver.Conn, err error)
```

--------------------------------

### Function: New

Source: https://pkg.go.dev/modernc.org/sqlite/vfs

New creates a new sqlite VFS and registers it. If successful, the file system can be used with the URI parameter `?vfs=<returned name>`.

```go
func New(fs fs.FS) (name string, _ *FS, _ error)
```

--------------------------------

### Xsqlite3_snapshot_get

Source: https://pkg.go.dev/modernc.org/sqlite/lib

Gets a database snapshot. This function is part of the SQLite C API bindings exposed by the modernc.org/sqlite package.

```APIDOC
## Xsqlite3_snapshot_get

### Description
Gets a database snapshot.

### Signature
func Xsqlite3_snapshot_get(tls *libc.TLS, db uintptr, zDb uintptr, ppSnapshot uintptr) (r int32)

### Parameters
- **tls** (*libc.TLS) - TLS context
- **db** (uintptr) - Database handle
- **zDb** (uintptr) - Database name
- **ppSnapshot** (uintptr) - Pointer to snapshot pointer

### Returns
- **r** (int32) - SQLite result code
```

--------------------------------

### Initial git status and test run with debug logs

Source: https://pkg.go.dev/modernc.org/sqlite

Shows the initial repository state and running a test with the libc.dmesg tag to create /tmp/libc.log. The log is empty because no debug messages are enabled in libc.

```shell
0:jnml@e5-1650:~/src/modernc.org/sqlite$ git status
On branch master
Your branch is up to date with 'origin/master'.

nothing to commit, working tree clean
0:jnml@e5-1650:~/src/modernc.org/sqlite$ git log -1
commit df33b8d15107f3cc777799c0fe105f74ef499e62 (HEAD -> master, tag: v1.21.1, origin/master, origin/HEAD, wips, ok)
Author: Jan Mercl <0xjnml@gmail.com>
Date:   Mon Mar 27 16:18:28 2023 +0200

    upgrade to SQLite 3.41.2
0:jnml@e5-1650:~/src/modernc.org/sqlite$ rm -f /tmp/libc.log ; go test -v -tags=libc.dmesg -run TestScalar ; ls -l /tmp/libc.log
test binary compiled for linux/amd64
=== RUN   TestScalar
--- PASS: TestScalar (0.09s)
PASS
ok  modernc.org/sqlite 0.128s
-rw-r--r-- 1 jnml jnml 76 Apr  6 11:22 /tmp/libc.log
0:jnml@e5-1650:~/src/modernc.org/sqlite$ cat /tmp/libc.log
[10723 sqlite.test] 2023-04-06 11:22:48.288066057 +0200 CEST m=+0.000707150
0:jnml@e5-1650:~/src/modernc.org/sqlite$
```

--------------------------------

### Limit

Source: https://pkg.go.dev/modernc.org/sqlite

Calls sqlite3_limit to get or set a limit on a specific database connection. The limit is bound to the connection instance, so it is most useful for querying default values.

```APIDOC
## Limit

### Description
Calls sqlite3_limit, see the docs at https://www.sqlite.org/c3ref/limit.html for details. 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.

### Function Signature
```go
func Limit(c *sql.Conn, id int, newVal int) (r int, err error)
```

### Parameters
- **c** (*sql.Conn) - Required - The database connection on which to set or get the limit.
- **id** (int) - Required - The SQLite limit identifier (e.g., SQLITE_LIMIT_LENGTH).
- **newVal** (int) - Required - The new value for the limit. Use -1 to query the current limit.

### Return Values
- **r** (int) - The current or new limit value.
- **err** (error) - An error if the operation fails.
```

--------------------------------

### Register pcache with sqlite in init

Source: https://pkg.go.dev/modernc.org/sqlite/pcache

Typical usage: import the sqlite and pcache packages, then call sqlite.MustRegisterPageCache(pcache.New()) in an init function. Call New once and reuse the result; two distinct *Pool values compare unequal and would trip sqlite.ErrPageCacheConflict if both were registered.

```go
import (
    "modernc.org/sqlite"
    "modernc.org/sqlite/pcache"
)

func init() {
    sqlite.MustRegisterPageCache(pcache.New())
}
```

--------------------------------

### Create vec0 virtual table

Source: https://pkg.go.dev/modernc.org/sqlite/vec

After importing the package, the vec0 virtual table module is available. This example creates a table with an embedding column of type float[8].

```sql
CREATE VIRTUAL TABLE vec_examples USING vec0(embedding float[8])
```

--------------------------------

### Xsqlite3_collation_needed16

Source: https://pkg.go.dev/modernc.org/sqlite/lib

Registers a collation sequence factory callback with the database handle db. Replaces any previously installed collation sequence factory.

```APIDOC
## Xsqlite3_collation_needed16

### Description
Registers a collation sequence factory callback with the database handle db. Replaces any previously installed collation sequence factory.

### Function Signature
`func Xsqlite3_collation_needed16(tls *libc.TLS, db uintptr, pCollNeededArg uintptr, __ccgo_fp_xCollNeeded16 uintptr) (r int32)`

### Parameters
- **tls** (*libc.TLS) - Required - TLS context.
- **db** (uintptr) - Required - Database connection handle.
- **pCollNeededArg** (uintptr) - Required - Argument to pass to the callback.
- **__ccgo_fp_xCollNeeded16** (uintptr) - Required - Pointer to the collation needed callback (UTF-16 version).

### Return Value
- **r** (int32) - Result code.
```

--------------------------------

### func NewSqlDb(driverName string, db *sql.DB) *SqlDb

Source: https://pkg.go.dev/modernc.org/sqlite-bench/app

Creates a new SqlDb instance.

```APIDOC
## func NewSqlDb

### Description
Creates a new SqlDb with the given driver name and database handle.

### Signature
`func NewSqlDb(driverName string, db *sql.DB) *SqlDb`

### Parameters
- **driverName** (string) - The database driver name.
- **db** (*sql.DB) - The database handle.

### Returns
- **\*SqlDb** - The new SqlDb instance.
```

--------------------------------

### func NewSqlDb(driverName string, db *sql.DB) *SqlDb

Source: https://pkg.go.dev/modernc.org/sqlite-bench2/app

Creates a new SqlDb instance.

```APIDOC
## func NewSqlDb

### Description
Constructs a SqlDb with the given driver name and database handle.

### Signature
```go
func NewSqlDb(driverName string, db *sql.DB) *SqlDb
```

### Parameters
- **driverName** (string) - The database driver name.
- **db** (*sql.DB) - The underlying database handle.

### Returns
- **\*SqlDb** - The new SqlDb instance.
```

--------------------------------

### Xsqlite3_reset

Source: https://pkg.go.dev/modernc.org/sqlite/lib

Terminates the current execution of an SQL statement and resets it back to its starting state so that it can be reused. Returns a success code from the prior execution.

```APIDOC
## Xsqlite3_reset

### Description
Terminates the current execution of an SQL statement and resets it back to its starting state so that it can be reused. Returns a success code from the prior execution.

### Function Signature
```go
func Xsqlite3_reset(tls *libc.TLS, pStmt uintptr) (r int32)
```

### Parameters
- **tls** (*libc.TLS) - Required - Thread-local storage context.
- **pStmt** (uintptr) - Required - Pointer to the prepared statement to reset.

### Return Value
- **r** (int32) - Result code from the prior execution.
```

--------------------------------

### Create method on Pool

Source: https://pkg.go.dev/modernc.org/sqlite/pcache

Create allocates a fresh per-database cache. It is the sqlite.PageCache entry point; SQLite calls it through the binding each time a new database connection's page cache is wired up.

```go
func (p *Pool) Create(pageSize, extraSize int, purgeable bool) (sqlite.Cache, error)
```

--------------------------------

### Xsqlite3_release_memory

Source: https://pkg.go.dev/modernc.org/sqlite/lib

Attempts to release up to n bytes of non-essential memory currently held by SQLite. An example of non-essential memory is memory used to cache database pages that are not currently in use.

```APIDOC
## Xsqlite3_release_memory

### Description
Attempts to release up to n bytes of non-essential memory currently held by SQLite. An example of non-essential memory is memory used to cache database pages that are not currently in use.

### Function Signature
```go
func Xsqlite3_release_memory(tls *libc.TLS, n int32) (r int32)
```

### Parameters
- **tls** (*libc.TLS) - Required - Thread-local storage context.
- **n** (int32) - Required - Number of bytes to release.

### Return Value
- **r** (int32) - Result code.
```

--------------------------------

### func Run(makeDb func(dbfile string) Db)

Source: https://pkg.go.dev/modernc.org/sqlite-bench/app

Runs the application with a database factory function.

```APIDOC
## func Run

### Description
Runs the application, using the provided factory function to create a Db instance.

### Signature
`func Run(makeDb func(dbfile string) Db)`

### Parameters
- **makeDb** (func(dbfile string) Db) - A function that takes a database file path and returns a Db implementation.
```

--------------------------------

### func Run(makeDb func(dbfile string) Db)

Source: https://pkg.go.dev/modernc.org/sqlite-bench2/app

Runs the application with a database factory function.

```APIDOC
## func Run

### Description
Runs the application, using the provided makeDb function to create a Db instance from a database file path.

### Signature
```go
func Run(makeDb func(dbfile string) Db)
```

### Parameters
- **makeDb** (func(dbfile string) Db) - A function that takes a database file path and returns a Db implementation.
```

--------------------------------

### Example of code that silently strips SQLite locks

Source: https://pkg.go.dev/modernc.org/sqlite

Illustrates how a POSIX record lock is dropped when any file descriptor of the same file is closed. This code, placed anywhere in the process (even in a third-party library), will silently remove SQLite's transaction locks, leaving the database unprotected. This is the problem that OFD locking solves.

```go
f, _ := os.Open(dbPath) // hash, back up, inspect, ...
f.Close()
```

--------------------------------

### Xsqlite3_expired

Source: https://pkg.go.dev/modernc.org/sqlite/lib

Returns TRUE (non-zero) if the statement supplied as an argument needs to be recompiled. A statement needs to be recompiled whenever the execution environment changes in a way that would alter the program that sqlite3_prepare() generates. For example, if new functions or collating sequences are registered or if an authorizer function is added or changed.

```APIDOC
## Xsqlite3_expired

### Description
Returns TRUE (non-zero) if the statement supplied as an argument needs to be recompiled. A statement needs to be recompiled whenever the execution environment changes in a way that would alter the program that sqlite3_prepare() generates. For example, if new functions or collating sequences are registered or if an authorizer function is added or changed.

### Function Signature
```go
func Xsqlite3_expired(tls *libc.TLS, pStmt uintptr) (r int32)
```

### Parameters
- **tls** (uintptr) - TLS context pointer.
- **pStmt** (uintptr) - Pointer to the prepared statement.

### Return Value
- **r** (int32) - Non-zero if the statement needs recompilation, zero otherwise.
```

--------------------------------

### Constants: ILL_*

Source: https://pkg.go.dev/modernc.org/sqlite/vfs

Illegal instruction codes.

```go
const (
	ILL_ILLOPC   = 1
	ILL_ILLOPN   = 2
	ILL_ILLADR   = 3
	ILL_ILLTRP   = 4
	ILL_PRVOPC   = 5
	ILL_PRVREG   = 6
	ILL_COPROC   = 7
	ILL_BADSTK   = 8
	ILL_BADIADDR = 9
)
```

--------------------------------

### Function: Xsqlite3_fsFS

Source: https://pkg.go.dev/modernc.org/sqlite/vfs

Exported function signature for the SQLite VFS registration callback.

```go
func Xsqlite3_fsFS(tls *libc.TLS, zName uintptr, pAppData uintptr) uintptr
```

--------------------------------

### Xsqlite3changeset_start_strm

Source: https://pkg.go.dev/modernc.org/sqlite/lib

Streaming version of sqlite3changeset_start().

```APIDOC
## Xsqlite3changeset_start_strm

### Description
Streaming version of sqlite3changeset_start().

### Function Signature
```go
func Xsqlite3changeset_start_strm(tls *libc.TLS, pp uintptr, __ccgo_fp_xInput uintptr, pIn uintptr) (r int32)
```

### Parameters
- **tls** (*libc.TLS) - Required - TLS context.
- **pp** (uintptr) - Required - Pointer to a variable to receive the iterator handle.
- **__ccgo_fp_xInput** (uintptr) - Required - Pointer to the input callback function.
- **pIn** (uintptr) - Required - Pointer to the input context.

### Return Value
- **r** (int32) - SQLITE_OK or an error code.
```

--------------------------------

### Type: VFSFile

Source: https://pkg.go.dev/modernc.org/sqlite/vfs

Alias for VFSFile1.

```go
type VFSFile = VFSFile1
```

--------------------------------

### Type: VFSFile1

Source: https://pkg.go.dev/modernc.org/sqlite/vfs

Structure for VFS file handle.

```go
type VFSFile1 = struct {
	// contains filtered or unexported fields
}
```

--------------------------------

### Xsqlite3_backup_init

Source: https://pkg.go.dev/modernc.org/sqlite/lib

Creates an sqlite3_backup process to copy the contents of zSrcDb from connection handle pSrcDb to zDestDb in pDestDb. If successful, returns a pointer to the new sqlite3_backup object.

```APIDOC
## Xsqlite3_backup_init

### Description
Creates an sqlite3_backup process to copy the contents of zSrcDb from connection handle pSrcDb to zDestDb in pDestDb. If successful, returns a pointer to the new sqlite3_backup object.

### Function Signature
```go
func Xsqlite3_backup_init(tls *libc.TLS, pDestDb uintptr, zDestDb uintptr, pSrcDb uintptr, zSrcDb uintptr) (r uintptr)
```

### Parameters
- **tls** (*libc.TLS) - TLS context
- **pDestDb** (uintptr) - Destination database connection handle
- **zDestDb** (uintptr) - Name of destination database
- **pSrcDb** (uintptr) - Source database connection handle
- **zSrcDb** (uintptr) - Name of source database

### Return Value
- **r** (uintptr) - Pointer to the new sqlite3_backup object, or NULL on error
```

--------------------------------

### Method: (*FS).Close

Source: https://pkg.go.dev/modernc.org/sqlite/vfs

Close unregisters f and releases its resources. Every database opened through f must be closed first; otherwise it returns an error wrapping ErrInUse.

```go
func (f *FS) Close() error
```

--------------------------------

### Open

Source: https://pkg.go.dev/modernc.org/sqlite

Opens a new connection to a SQLite database. The name is a DSN string that can be a plain file path or a SQLite URI. The driver interprets various parameters and PRAGMAs from the DSN.

```APIDOC
## Open

### Description
Opens a new connection to a SQLite database. The name is a DSN string that can be a plain file path or a SQLite URI. The driver interprets various parameters and PRAGMAs from the DSN.

### Method
Open

### Signature
func (*Driver) Open(name string) (driver.Conn, error)

### Parameters
- **name** (string) - Required - The DSN string. Can be a plain file path (e.g., "/tmp/mydata.sqlite") or a SQLite URI (e.g., "file:///tmp/mydata.sqlite"). The DSN may include query parameters and PRAGMA settings.

### Description of DSN Parameters
- **Plain file name**: If the name is a plain file path, the driver interprets it as a file name. If the file does not exist, it is created.
- **SQLite URI**: If the name starts with "file:", it is passed to sqlite3_open_v2 with SQLITE_OPEN_URI, so SQLite applies its own URI parameters (mode, cache, immutable, nolock, psow, modeof, vfs).
- **PRAGMA keys**: The driver interprets underscore-prefixed keys as PRAGMAs. For example, `_pragma=foreign_keys(1)` sets the foreign_keys PRAGMA. The keys are applied in a fixed order: `_busy_timeout`, `_auto_vacuum`, `_foreign_keys`, `_journal_mode`, `_synchronous`, `_query_only`, and `_time_format`.
- **Shorthand keys**: The following shorthand keys set common PRAGMAs:
  - `_busy_timeout` -> PRAGMA busy_timeout (integer)
  - `_foreign_keys` -> PRAGMA foreign_keys (0/1, false/true, no/yes, off/on)
  - `_journal_mode` -> PRAGMA journal_mode (DELETE, TRUNCATE, PERSIST, MEMORY, WAL, OFF)
  - `_synchronous` -> PRAGMA synchronous (0/OFF, 1/NORMAL, 2/FULL, 3/EXTRA)
  - `_auto_vacuum` -> PRAGMA auto_vacuum (0/NONE, 1/FULL, 2/INCREMENTAL)
  - `_query_only` -> PRAGMA query_only (0/1, false/true, no/yes, off/on)
- **Time format**: The `_time_format` parameter specifies the format used when writing time values to the database. Supported values are "sqlite" (YYYY-MM-DD HH:MM:SS.SSS[+-]HH:MM) and "datetime" (YYYY-MM-DD HH:MM:SS). If not specified, the default String() format is used.

### Notes
- The driver maintains a pool of idle connections for efficient reuse.
- The returned connection is only used by one goroutine at a time.
- PRAGMA values are executed as SQL text, not as a single PRAGMA. Anything after a ';' is executed as a separate statement.
- A DSN that includes a PRAGMA must come from a trusted source.
- If a PRAGMA value is invalid, the connection fails with an error.

### Example DSNs
- Plain file: `/tmp/mydata.sqlite`
- SQLite URI: `file:///tmp/mydata.sqlite`
- With parameters: `file:///tmp/mydata.sqlite?_pragma=foreign_keys(1)&_time_format=sqlite`

### Response
Returns a driver.Conn connection to the database.
```

--------------------------------

### Database schema for benchmarks

Source: https://pkg.go.dev/modernc.org/sqlite-bench

SQL statements to create the benchmark database schema, including PRAGMA settings and tables for users, articles, and comments with indices.

```sql
PRAGMA journal_mode=DELETE;
PRAGMA synchronous=FULL;
PRAGMA foreign_keys=1;
PRAGMA busy_timeout=5000;

CREATE TABLE users (
    id INTEGER PRIMARY KEY NOT NULL,
    created INTEGER NOT NULL,
    email TEXT NOT NULL,
    active INTEGER NOT NULL);
CREATE INDEX users_created ON users(created);

CREATE TABLE articles (
    id INTEGER PRIMARY KEY NOT NULL,
    created INTEGER NOT NULL,  
    userId INTEGER NOT NULL REFERENCES users(id),
    text TEXT NOT NULL);
CREATE INDEX articles_created ON articles(created);
CREATE INDEX articles_userId ON articles(userId);

CREATE TABLE comments (
    id INTEGER PRIMARY KEY NOT NULL,
    created INTEGER NOT NULL,
    articleId INTEGER NOT NULL REFERENCES articles(id),
    text TEXT NOT NULL);
CREATE INDEX comments_created ON comments(created);
CREATE INDEX comments_articleId ON comments(articleId);
```

--------------------------------

### Xsqlite3_open

Source: https://pkg.go.dev/modernc.org/sqlite/lib

Opens a new database handle.

```APIDOC
## Xsqlite3_open

### Description
Open a new database handle.

### Function Signature
```go
func Xsqlite3_open(tls *libc.TLS, zFilename uintptr, ppDb uintptr) (r int32)
```

### Parameters
- **tls** (*libc.TLS) - Required - Thread-local storage context.
- **zFilename** (uintptr) - Required - Pointer to the filename of the database to open.
- **ppDb** (uintptr) - Required - Pointer to a pointer that will receive the database handle.

### Return Value
- **r** (int32) - SQLite result code (e.g., SQLITE_OK).
```

--------------------------------

### Xsqlite3changeset_start_v2_strm

Source: https://pkg.go.dev/modernc.org/sqlite/lib

Streaming version of sqlite3changeset_start_v2().

```APIDOC
## Xsqlite3changeset_start_v2_strm

### Description
Streaming version of sqlite3changeset_start_v2().

### Function Signature
```go
func Xsqlite3changeset_start_v2_strm(tls *libc.TLS, pp uintptr, __ccgo_fp_xInput uintptr, pIn uintptr, flags int32) (r int32)
```

### Parameters
- **tls** (*libc.TLS) - Required - TLS context.
- **pp** (uintptr) - Required - Pointer to a variable to receive the iterator handle.
- **__ccgo_fp_xInput** (uintptr) - Required - Pointer to the input callback function.
- **pIn** (uintptr) - Required - Pointer to the input context.
- **flags** (int32) - Required - Flags controlling iterator behavior.

### Return Value
- **r** (int32) - SQLITE_OK or an error code.
```

--------------------------------

### Xsqlite3_step

Source: https://pkg.go.dev/modernc.org/sqlite/lib

Top-level implementation of sqlite3_step().

```APIDOC
## Xsqlite3_step

### Description
Top-level implementation of sqlite3_step().

### Function Signature
```go
func Xsqlite3_step(tls *libc.TLS, pStmt uintptr) (r int32)
```

### Parameters
- **tls** (*libc.TLS) - TLS context
- **pStmt** (uintptr) - Prepared statement handle

### Return Value
- **r** (int32) - Result code
```

--------------------------------

### func New(fs fs.FS) (name string, _ *FS, _ error)

Source: https://pkg.go.dev/modernc.org/sqlite/vfs

Creates a new SQLite VFS backed by the provided fs.FS and registers it with SQLite. Returns the name to use in the vfs DSN parameter, the FS instance, and an error if registration fails.

```APIDOC
## func New

### Description
Creates a new SQLite VFS backed by the provided fs.FS and registers it with SQLite. Returns the name to use in the vfs DSN parameter, the FS instance, and an error if registration fails.

### Signature
`func New(fs fs.FS) (name string, _ *FS, _ error)`

### Parameters
- **fs** (fs.FS) - Required - The file system to back the VFS. Any fs.FS implementation, including embed.FS, can be used.

### Returns
- **name** (string) - The name to use in the `vfs` DSN query parameter to open a database through this VFS.
- **_ *FS** - The FS instance representing the registered VFS.
- **_ error** - An error if registration fails.

### Usage Example
```go
name, fsvfs, err := vfs.New(os.DirFS(dir))
if err != nil {
    return err
}
defer fsvfs.Close()

db, err := sql.Open("sqlite", "file:test.db?vfs="+name)
```
```

--------------------------------

### Xsqlite3_backup_init

Source: https://pkg.go.dev/modernc.org/sqlite/lib

Initializes a backup operation between two database connections. This function prepares the backup process and returns a backup object.

```APIDOC
## Xsqlite3_backup_init

### Description
Initializes a backup operation between two database connections. This function prepares the backup process and returns a backup object.

### Method
Function

### Signature
func Xsqlite3_backup_init(tls *libc.TLS, pDestDb uintptr, zDestDb uintptr, pSrcDb uintptr, ...) (r uintptr)

### Parameters
- **tls** (*libc.TLS) - Required - Thread-local storage pointer.
- **pDestDb** (uintptr) - Required - Pointer to the destination database connection.
- **zDestDb** (uintptr) - Required - Name of the destination database.
- **pSrcDb** (uintptr) - Required - Pointer to the source database connection.
- **...** - Optional - Additional arguments.

### Return Value
- **r** (uintptr) - Pointer to the backup object, or NULL on failure.
```

--------------------------------

### Constants: SS_*

Source: https://pkg.go.dev/modernc.org/sqlite/vfs

Signal stack flags.

```go
const (
	SS_ONSTACK = 1
	SS_DISABLE = 2
)
```

--------------------------------

### Driver.MustRegisterCollationUtf8 method

Source: https://pkg.go.dev/modernc.org/sqlite

Signature for MustRegisterCollationUtf8, which registers a collation and panics on error.

```go
func (d *Driver) MustRegisterCollationUtf8(
	zName string,
	impl func(left, right string) int,
)
```

--------------------------------

### func (p *Pool) Create(pageSize, extraSize int, purgeable bool) (sqlite.Cache, error)

Source: https://pkg.go.dev/modernc.org/sqlite/pcache

Create allocates a fresh per-database cache. It is the sqlite.PageCache entry point; SQLite calls it through the binding each time a new database connection's page cache is wired up.

```APIDOC
## func (p *Pool) Create(pageSize, extraSize int, purgeable bool) (sqlite.Cache, error)

### Description
Create allocates a fresh per-database cache. It is the sqlite.PageCache entry point; SQLite calls it through the binding each time a new database connection's page cache is wired up.

### Signature
`func (p *Pool) Create(pageSize, extraSize int, purgeable bool) (sqlite.Cache, error)`

### Parameters
- **pageSize** (int) - Required - The page size for the cache.
- **extraSize** (int) - Required - The extra size per page.
- **purgeable** (bool) - Required - Whether the cache is purgeable.

### Returns
- **sqlite.Cache** - A new per-database cache.
- **error** - An error if creation fails.

```

--------------------------------

### type Context

Source: https://pkg.go.dev/modernc.org/sqlite/vtab

Provides methods for declaring schema and handling configuration during virtual table creation.

```APIDOC
## type Context

### Description
Provides methods for declaring schema and handling configuration during virtual table creation.

### Functions
#### func NewContext(declare func(string) error) Context

##### Description
Creates a new Context with the given declare function.

##### Parameters
- **declare** (func(string) error) - Required - Function to declare the schema.

#### func NewContextWithConfig(declare func(string) error, constraintSupport func() error, ...) Context

##### Description
Creates a new Context with the given declare function and constraint support function, plus additional variadic options.

##### Parameters
- **declare** (func(string) error) - Required - Function to declare the schema.
- **constraintSupport** (func() error) - Required - Function to enable constraint support.
- **...** - Additional options.

#### func NewContextWithConstraintSupport(declare func(string) error, constraintSupport func() error) Context

##### Description
Creates a new Context with the given declare function and constraint support function.

##### Parameters
- **declare** (func(string) error) - Required - Function to declare the schema.
- **constraintSupport** (func() error) - Required - Function to enable constraint support.

### Methods
#### func (c Context) Config(op int32, args ...int32) error

##### Description
Handles configuration operations.

##### Parameters
- **op** (int32) - Required - Operation code.
- **args** (...int32) - Optional - Additional arguments.

##### Return Value
- **error** - Returns an error if the operation fails.

#### func (c Context) Declare(schema string) error

##### Description
Declares the schema for the virtual table.

##### Parameters
- **schema** (string) - Required - The schema definition.

##### Return Value
- **error** - Returns an error if declaration fails.

#### func (c Context) EnableConstraintSupport() error

##### Description
Enables constraint support for the virtual table.

##### Return Value
- **error** - Returns an error if enabling fails.
```

--------------------------------

### func OutputFiles(root string) ([]string, error)

Source: https://pkg.go.dev/modernc.org/sqlite/internal/vendorstamp

OutputFiles lists the files matching OutputPatterns under root, sorted, with slash-separated paths relative to root.

```APIDOC
## func OutputFiles

### Description
OutputFiles lists the files matching OutputPatterns under root, sorted, with slash-separated paths relative to root.

### Function Signature
func OutputFiles(root string) ([]string, error)

### Parameters
- **root** (string) - The repository root directory.

### Returns
- **[]string** - The list of output file paths.
- **error** - An error if the listing fails.
```

--------------------------------

### func NewArticle(id int, created time.Time, userId int, text string) Article

Source: https://pkg.go.dev/modernc.org/sqlite-bench2/app

Creates a new Article instance.

```APIDOC
## func NewArticle

### Description
Constructs an Article with the given fields.

### Signature
```go
func NewArticle(id int, created time.Time, userId int, text string) Article
```

### Parameters
- **id** (int) - The article ID.
- **created** (time.Time) - The creation time.
- **userId** (int) - The ID of the user who wrote the article.
- **text** (string) - The article text.

### Returns
- **Article** - The new Article.
```
Tokens:
Raw