crush/vendor/github.com/ncruces/go-sqlite3

Go bindings to SQLite using wazero

Go module github.com/ncruces/go-sqlite3 is a cgo-free SQLite wrapper.\ It provides a database/sql compatible driver, as well as direct access to most of the C SQLite API.

It wraps a Wasm build of SQLite, and uses wazero as the runtime.\ Go, wazero and x/sys are the only direct dependencies.

Getting started

Using the database/sql driver:

import "database/sql"
import _ "github.com/ncruces/go-sqlite3/driver"
import _ "github.com/ncruces/go-sqlite3/embed"

var version string
db, _ := sql.Open("sqlite3", "file:demo.db")
db.QueryRow(`SELECT sqlite_version()`).Scan(&version)

Packages

• github.com/ncruces/go-sqlite3 wraps the C SQLite API (example usage).
• github.com/ncruces/go-sqlite3/driver provides a database/sql driver (example usage).
• github.com/ncruces/go-sqlite3/embed embeds a build of SQLite into your application.
• github.com/ncruces/go-sqlite3/vfs wraps the C SQLite VFS API and provides a pure Go implementation.
• github.com/ncruces/go-sqlite3/gormlite provides a GORM driver.

Advanced features

• incremental BLOB I/O
• nested transactions
• custom functions
• virtual tables
• custom VFSes
• online backup
• JSON support
• math functions
• full-text search
• geospatial search
• Unicode support
• statistics functions
• encryption at rest
• many extensions
• custom VFSes
• and more…

Caveats

This module replaces the SQLite OS Interface (aka VFS) with a pure Go implementation, which has advantages and disadvantages. Read more about the Go VFS design here.

Because each database connection executes within a Wasm sandboxed environment, memory usage will be higher than alternatives.

Testing

This project aims for high test coverage. It also benefits greatly from SQLite's and wazero's thorough testing.

Every commit is tested on Linux (amd64/arm64/386/riscv64/ppc64le/s390x), macOS (arm64/amd64), Windows (amd64), FreeBSD (amd64/arm64), OpenBSD (amd64), NetBSD (amd64/arm64), DragonFly BSD (amd64), illumos (amd64), and Solaris (amd64).

The Go VFS is tested by running SQLite's mptest.

Performance

Performance of the database/sql driver is competitive with alternatives.

The Wasm and VFS layers are also benchmarked by running SQLite's speedtest1.

Concurrency

This module behaves similarly to SQLite in multi-thread mode: it is goroutine-safe, provided that no single database connection, or object derived from it, is used concurrently by multiple goroutines.

The database/sql API is safe to use concurrently, according to its documentation.

FAQ, issues, new features

For questions, please see Discussions.

Also, post there if you used this driver for something interesting ("Show and tell"), have an idea…

The Issue tracker is for bugs, and features we're working on, planning to work on, or asking for help with.

Alternatives

• modernc.org/sqlite
• crawshaw.io/sqlite
• github.com/mattn/go-sqlite3
• github.com/zombiezen/go-sqlite