Go bindings to SQLite using wasm2go

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 wasm2go to translate it to Go.
Go 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"

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).
• github.com/ncruces/go-sqlite3/driver provides a database/sql driver (example).
• 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 (example)
• nested transactions (example)
• custom functions (example)
• virtual tables (example)
• custom VFSes (examples)
• online backup (example)
• JSON support (example)
• math functions
• Unicode support
• statistics functions
• encryption at rest
• many extensions

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 thorough testing.

Every commit is tested on:

• Linux: amd64, arm64, 386, arm, riscv64, ppc64le, loong64, s390x
• macOS: amd64, arm64
• Windows: amd64, arm64
• BSD:
  • FreeBSD: amd64, arm64
  • NetBSD: amd64, arm64
  • DragonFly BSD: amd64
  • OpenBSD: amd64
• illumos: amd64
• Solaris: amd64

Certain operating system and CPU combinations have some limitations. See the support matrix for a complete overview.

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.

---

Hanzo fork

github.com/hanzoai/sqlite3 is the canonical Hanzo SQLite — a fork of ncruces/go-sqlite3 (MIT) adding the hanzovfs native encrypted VFS for per-tenant SQLite ⇒ hanzoai/vfs ⇒ S3 (HIP-0302 / HIP-0107), no FUSE, no cgo.

import (
    "github.com/hanzoai/sqlite3"
    _ "github.com/hanzoai/sqlite3/hanzovfs" // registers vfs=hanzo
    _ "github.com/hanzoai/sqlite3/embed"
)
db, _ := sqlite3.Open("file:/orgs/acme/app.db?vfs=hanzo")

Deprecates modernc.org/sqlite (no custom-VFS hook) and direct use of ncruces/go-sqlite3. Benchmarked 3.6× faster writes / ~92× faster point-reads than the FUSE-mounted path; per-page AEAD encryption costs ~0.