Go bindings to SQLite using Wazero

Go module github.com/ncruces/go-sqlite3 wraps a WASM build of SQLite, and uses wazero to provide cgo-free SQLite bindings.

• Package github.com/ncruces/go-sqlite3 wraps the C SQLite API (example usage).
• Package github.com/ncruces/go-sqlite3/driver provides a database/sql driver (example usage).
• Package github.com/ncruces/go-sqlite3/embed embeds a build of SQLite into your application.
• Package github.com/ncruces/go-sqlite3/vfs wraps the C SQLite VFS API and provides a pure Go implementation.
• Package github.com/ncruces/go-sqlite3/vfs/memdb implements an in-memory VFS.
• Package github.com/ncruces/go-sqlite3/vfs/readervfs implements a VFS for immutable databases.
• Package github.com/ncruces/go-sqlite3/ext/unicode registers Unicode aware functions.
• Package github.com/ncruces/go-sqlite3/ext/stats registers statistics functions.
• Package github.com/ncruces/go-sqlite3/gormlite provides a GORM driver.

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 databases you should disable connection pooling by calling db.SetMaxOpenConns(1).

POSIX Advisory Locks

POSIX advisory locks, which SQLite uses, 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 process-associated POSIX advisory locks.

On BSD Unixes, this module uses BSD locks. BSD locks may not be compatible with process-associated POSIX advisory locks (they are on FreeBSD).

TL;DR

In all platforms for which this package builds, it is safe to use it to access databases concurrently from multiple goroutines.

Additionally, on Windows, Linux, macOS, illumos and FreeBSD, it is also safe to use it to access databases concurrently with other implementations of SQLite.

On other BSDs, where this might be unsafe, this test should fail.

Testing

The pure Go VFS is tested by running SQLite's mptest on Linux, macOS and Windows; BSD code paths are tested on macOS using the sqlite3_bsd build tag. Performance is tested by running speedtest1.

Roadmap

• advanced SQLite features
  • custom functions
  • nested transactions
  • incremental BLOB I/O
  • online backup
  • session extension
• custom VFSes
  • custom VFS API
  • in-memory VFS
  • read-only VFS, wrapping an io.ReaderAt
  • cloud-based VFS, based on Cloud Backed SQLite
  • MVCC VFS, using BadgerDB

Alternatives

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