2023-01-12 16:29:57 +00:00
|
|
|
# Go bindings to SQLite using Wazero
|
|
|
|
|
|
2023-01-26 01:11:09 +00:00
|
|
|
[](https://pkg.go.dev/github.com/ncruces/go-sqlite3)
|
|
|
|
|
[](https://goreportcard.com/report/github.com/ncruces/go-sqlite3)
|
2023-01-27 15:50:21 +00:00
|
|
|
[](https://raw.githack.com/wiki/ncruces/go-sqlite3/coverage.html)
|
2023-01-12 16:29:57 +00:00
|
|
|
|
2023-02-24 14:31:41 +00:00
|
|
|
### ⚠️ Work in Progress ⚠️
|
2023-01-26 01:11:09 +00:00
|
|
|
|
2023-02-24 14:31:41 +00:00
|
|
|
Go module `github.com/ncruces/go-sqlite3` wraps a [WASM](https://webassembly.org/) build of [SQLite](https://sqlite.org/),
|
|
|
|
|
and uses [wazero](https://wazero.io/) to provide `cgo`-free SQLite bindings.
|
|
|
|
|
|
|
|
|
|
- Package [`github.com/ncruces/go-sqlite3`](https://pkg.go.dev/github.com/ncruces/go-sqlite3)
|
|
|
|
|
wraps the [C SQLite API](https://www.sqlite.org/cintro.html)
|
|
|
|
|
([example usage](https://pkg.go.dev/github.com/ncruces/go-sqlite3#example-package)).
|
|
|
|
|
- Package [`github.com/ncruces/go-sqlite3/driver`](https://pkg.go.dev/github.com/ncruces/go-sqlite3/driver)
|
|
|
|
|
provides a [`database/sql`](https://pkg.go.dev/database/sql) driver
|
|
|
|
|
([example usage](https://pkg.go.dev/github.com/ncruces/go-sqlite3/driver#example-package)).
|
|
|
|
|
- Package [`github.com/ncruces/go-sqlite3/embed`](https://pkg.go.dev/github.com/ncruces/go-sqlite3/embed)
|
|
|
|
|
embeds a build of SQLite into your application.
|
|
|
|
|
|
|
|
|
|
### Caveats
|
|
|
|
|
|
|
|
|
|
Because WASM does not support shared memory,
|
|
|
|
|
[WAL](https://www.sqlite.org/wal.html) support is [limited](https://www.sqlite.org/wal.html#noshm).
|
|
|
|
|
|
|
|
|
|
To work around this limitation, SQLite is compiled with
|
|
|
|
|
[`SQLITE_DEFAULT_LOCKING_MODE=1`](https://www.sqlite.org/compile.html#default_locking_mode),
|
|
|
|
|
making `EXCLUSIVE` the default locking mode.
|
|
|
|
|
For non-WAL databases, `NORMAL` locking mode can be activated with
|
|
|
|
|
[`PRAGMA locking_mode=NORMAL`](https://www.sqlite.org/pragma.html#pragma_locking_mode).
|
|
|
|
|
|
|
|
|
|
Because connection pooling is incompatible with `EXCLUSIVE` locking mode,
|
|
|
|
|
the `database/sql` driver defaults to `NORMAL` locking mode,
|
|
|
|
|
and WAL databases are not supported.
|
|
|
|
|
|
|
|
|
|
### Roadmap
|
2023-01-12 16:29:57 +00:00
|
|
|
|
|
|
|
|
- [x] build SQLite using `zig cc --target=wasm32-wasi`
|
|
|
|
|
- [x] `:memory:` databases
|
2023-01-19 15:28:36 +00:00
|
|
|
- [x] port [`test_demovfs.c`](https://www.sqlite.org/src/doc/trunk/src/test_demovfs.c) to Go
|
|
|
|
|
- branch [`wasi`](https://github.com/ncruces/go-sqlite3/tree/wasi) uses `test_demovfs.c` directly
|
2023-02-24 14:31:41 +00:00
|
|
|
- [x] design a nice API, enough for simple use cases
|
2023-02-18 03:43:17 +00:00
|
|
|
- [x] provide a simple `database/sql` driver
|
2023-02-23 14:13:32 +00:00
|
|
|
- [x] file locking, compatible with SQLite on macOS/Linux/Windows
|
2023-02-22 17:51:30 +00:00
|
|
|
- [ ] advanced SQLite features
|
2023-02-24 14:31:41 +00:00
|
|
|
- [x] nested transactions
|
2023-02-22 14:19:56 +00:00
|
|
|
- [ ] incremental BLOB I/O
|
|
|
|
|
- [ ] online backup
|
2023-02-22 17:51:30 +00:00
|
|
|
- [ ] snapshots
|
2023-02-26 04:49:10 +00:00
|
|
|
- [ ] session extension
|
|
|
|
|
- [ ] resumable bulk update
|
2023-02-24 14:31:41 +00:00
|
|
|
- [ ] SQL functions
|
|
|
|
|
- [ ] custom VFSes
|
|
|
|
|
- [ ] read-only VFS, wrapping an [`io.ReaderAt`](https://pkg.go.dev/io#ReaderAt)
|
|
|
|
|
- [ ] in-memory VFS, wrapping a [`bytes.Buffer`](https://pkg.go.dev/bytes#Buffer)
|
|
|
|
|
- [ ] expose a custom VFS API
|
|
|
|
|
|
|
|
|
|
### Alternatives
|
|
|
|
|
|
|
|
|
|
- [`modernc.org/sqlite`](https://pkg.go.dev/modernc.org/sqlite)
|
|
|
|
|
- [`crawshaw.io/sqlite`](https://pkg.go.dev/crawshaw.io/sqlite)
|
2023-02-26 03:22:08 +00:00
|
|
|
- [`github.com/mattn/go-sqlite3`](https://pkg.go.dev/github.com/mattn/go-sqlite3)
|
|
|
|
|
- [`github.com/zombiezen/go-sqlite`](https://pkg.go.dev/github.com/zombiezen/go-sqlite)
|
