Go bindings to SQLite using Wazero

Go module github.com/ncruces/go-sqlite3 is 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.

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/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/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/zorder maps multidimensional data to one dimension.
• 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
• and more…

Caveats

This module replaces the SQLite OS Interface (aka VFS) with a pure Go implementation. This has benefits, but also comes with some drawbacks.

Write-Ahead Logging

Because Wasm does not support shared memory, WAL support is limited.

To work around this limitation, SQLite is patched to always use EXCLUSIVE locking mode for WAL databases.

Because connection pooling is incompatible with EXCLUSIVE locking mode, to use the database/sql driver with WAL mode databases you should disable connection pooling by calling db.SetMaxOpenConns(1).

File Locking

POSIX advisory locks, which SQLite uses on Unix, are broken by design.

On Linux, macOS and illumos, this module uses OFD locks to synchronize access to database files. OFD locks are fully compatible with POSIX advisory locks.

On BSD Unixes, this module uses BSD locks. On BSD Unixes, BSD locks are fully compatible with POSIX advisory locks.

On Windows, this module uses LockFileEx and UnlockFileEx, like SQLite.

On all other platforms, file locking is not supported, and you must use nolock=1 (or immutable=1) to open database files. You can use vfs.SupportsFileLocking to check if your platform supports file locking.

To use the database/sql driver with nolock=1 you must disable connection pooling by calling db.SetMaxOpenConns(1).

Testing

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

The pure Go VFS is tested by running SQLite's mptest on Linux, macOS, Windows and FreeBSD.

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