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 adatabase/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 thearray
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/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/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
- Unicode support
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 LockFile
, LockFileEx
, and UnlockFile
,
like SQLite.
On all other platforms, file locking is not supported, and you must use
nolock=1
to open database files.
To use the database/sql
driver
with nolock=1
you must disable connection pooling by calling
db.SetMaxOpenConns(1)
.
Testing
The pure Go VFS is tested by running SQLite's mptest on Linux, macOS, Windows and FreeBSD. Performance is tested by running speedtest1.