GoToSocial/vendor/github.com/ncruces/go-sqlite3/README.md

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 runtime 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.

Extensions

• github.com/ncruces/go-sqlite3/ext/array provides the array table-valued function.
• github.com/ncruces/go-sqlite3/ext/blobio simplifies incremental BLOB I/O.
• github.com/ncruces/go-sqlite3/ext/bloom provides a Bloom filter virtual table.
• github.com/ncruces/go-sqlite3/ext/csv reads comma-separated values.
• github.com/ncruces/go-sqlite3/ext/fileio reads, writes and lists files.
• github.com/ncruces/go-sqlite3/ext/hash provides cryptographic hash functions.
• github.com/ncruces/go-sqlite3/ext/lines reads data line-by-line.
• github.com/ncruces/go-sqlite3/ext/pivot creates pivot tables.
• github.com/ncruces/go-sqlite3/ext/regexp provides regular expression functions.
• github.com/ncruces/go-sqlite3/ext/statement creates parameterized views.
• github.com/ncruces/go-sqlite3/ext/stats provides statistics functions.
• github.com/ncruces/go-sqlite3/ext/unicode provides Unicode aware functions.
• github.com/ncruces/go-sqlite3/ext/uuid generates UUIDs.
• github.com/ncruces/go-sqlite3/ext/zorder maps multidimensional data to one dimension.
• github.com/ncruces/go-sqlite3/vfs/adiantum wraps a VFS to offer encryption at rest.
• github.com/ncruces/go-sqlite3/vfs/memdb implements an in-memory VFS.
• github.com/ncruces/go-sqlite3/vfs/readervfs implements a VFS for immutable databases.

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
• encryption at rest
• 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.

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/s390x), macOS (amd64/arm64), Windows (amd64), FreeBSD (amd64), OpenBSD (amd64), NetBSD (amd64), illumos (amd64), and Solaris (amd64).

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

Performance

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

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

Alternatives

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

---

1. anything else you find in go.mod is either a test dependency, or needed by one of the extensions. ↩︎