sqlite3/README.md

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.

Caveats

Write-Ahead Logging

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

To work around this limitation, SQLite is compiled with SQLITE_DEFAULT_LOCKING_MODE=1, making EXCLUSIVE the default locking mode. For non-WAL databases, NORMAL locking mode can be activated with PRAGMA locking_mode=NORMAL.

Because connection pooling is incompatible with EXCLUSIVE locking mode, the database/sql driver defaults to NORMAL locking mode, and WAL databases are not supported.

Open File Description Locks

On Unix, this module uses OFD locks to synchronize access to database files.

POSIX advisory locks, which SQLite uses, are broken by design. OFD locks are fully compatible with process-associated POSIX advisory locks, and are supported on Linux, macOS and illumos. As a work around for other Unixes, you can use nolock=1.

Roadmap

• build SQLite using zig cc --target=wasm32-wasi
• :memory: databases
• port test_demovfs.c to Go
  • branch wasi uses test_demovfs.c directly
• design a nice API, enough for simple use cases
• provide a simple database/sql driver
• file locking, compatible with SQLite on macOS/Linux/Windows
• advanced SQLite features
  • nested transactions
  • incremental BLOB I/O
  • online backup
  • snapshots
  • session extension
  • resumable bulk update
  • shared cache mode
  • unlock-notify
• custom SQL functions
• custom VFSes
  • read-only VFS, wrapping an io.ReaderAt
  • in-memory VFS, wrapping a bytes.Buffer
  • cloud-based VFS, based on Cloud Backed SQLite
  • custom VFS API

Alternatives

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