1# Go bindings to SQLite using wazero
2
3[](https://pkg.go.dev/github.com/ncruces/go-sqlite3)
4[](https://goreportcard.com/report/github.com/ncruces/go-sqlite3)
5[](https://github.com/ncruces/go-sqlite3/wiki/Test-coverage-report)
6
7Go module `github.com/ncruces/go-sqlite3` is a `cgo`-free [SQLite](https://sqlite.org/) wrapper.\
8It provides a [`database/sql`](https://pkg.go.dev/database/sql) compatible driver,
9as well as direct access to most of the [C SQLite API](https://sqlite.org/cintro.html).
10
11It wraps a [Wasm](https://webassembly.org/) [build](embed/) of SQLite,
12and uses [wazero](https://wazero.io/) as the runtime.\
13Go, wazero and [`x/sys`](https://pkg.go.dev/golang.org/x/sys) are the _only_ direct dependencies.
14
15### Getting started
16
17Using the [`database/sql`](https://pkg.go.dev/database/sql) driver:
18```go
19
20import "database/sql"
21import _ "github.com/ncruces/go-sqlite3/driver"
22import _ "github.com/ncruces/go-sqlite3/embed"
23
24var version string
25db, _ := sql.Open("sqlite3", "file:demo.db")
26db.QueryRow(`SELECT sqlite_version()`).Scan(&version)
27```
28
29### Packages
30
31- [`github.com/ncruces/go-sqlite3`](https://pkg.go.dev/github.com/ncruces/go-sqlite3)
32 wraps the [C SQLite API](https://sqlite.org/cintro.html)
33 ([example usage](https://pkg.go.dev/github.com/ncruces/go-sqlite3#example-package)).
34- [`github.com/ncruces/go-sqlite3/driver`](https://pkg.go.dev/github.com/ncruces/go-sqlite3/driver)
35 provides a [`database/sql`](https://pkg.go.dev/database/sql) driver
36 ([example usage](https://pkg.go.dev/github.com/ncruces/go-sqlite3/driver#example-package)).
37- [`github.com/ncruces/go-sqlite3/embed`](https://pkg.go.dev/github.com/ncruces/go-sqlite3/embed)
38 embeds a build of SQLite into your application.
39- [`github.com/ncruces/go-sqlite3/vfs`](https://pkg.go.dev/github.com/ncruces/go-sqlite3/vfs)
40 wraps the [C SQLite VFS API](https://sqlite.org/vfs.html) and provides a pure Go implementation.
41- [`github.com/ncruces/go-sqlite3/gormlite`](https://pkg.go.dev/github.com/ncruces/go-sqlite3/gormlite)
42 provides a [GORM](https://gorm.io) driver.
43
44### Advanced features
45
46- [incremental BLOB I/O](https://sqlite.org/c3ref/blob_open.html)
47- [nested transactions](https://sqlite.org/lang_savepoint.html)
48- [custom functions](https://sqlite.org/c3ref/create_function.html)
49- [virtual tables](https://sqlite.org/vtab.html)
50- [custom VFSes](https://sqlite.org/vfs.html)
51- [online backup](https://sqlite.org/backup.html)
52- [JSON support](https://sqlite.org/json1.html)
53- [math functions](https://sqlite.org/lang_mathfunc.html)
54- [full-text search](https://sqlite.org/fts5.html)
55- [geospatial search](https://sqlite.org/geopoly.html)
56- [Unicode support](https://pkg.go.dev/github.com/ncruces/go-sqlite3/ext/unicode)
57- [statistics functions](https://pkg.go.dev/github.com/ncruces/go-sqlite3/ext/stats)
58- [encryption at rest](vfs/adiantum/README.md)
59- [many extensions](ext/README.md)
60- [custom VFSes](vfs/README.md#custom-vfses)
61- [and more…](embed/README.md)
62
63### Caveats
64
65This module replaces the SQLite [OS Interface](https://sqlite.org/vfs.html)
66(aka VFS) with a [pure Go](vfs/) implementation,
67which has advantages and disadvantages.
68Read more about the Go VFS design [here](vfs/README.md).
69
70Because each database connection executes within a Wasm sandboxed environment,
71memory usage will be higher than alternatives.
72
73### Testing
74
75This project aims for [high test coverage](https://github.com/ncruces/go-sqlite3/wiki/Test-coverage-report).
76It also benefits greatly from [SQLite's](https://sqlite.org/testing.html) and
77[wazero's](https://tetrate.io/blog/introducing-wazero-from-tetrate/#:~:text=Rock%2Dsolid%20test%20approach)
78thorough testing.
79
80Every commit is [tested](https://github.com/ncruces/go-sqlite3/wiki/Support-matrix) on
81Linux (amd64/arm64/386/riscv64/ppc64le/s390x), macOS (arm64/amd64),
82Windows (amd64), FreeBSD (amd64/arm64), OpenBSD (amd64), NetBSD (amd64/arm64),
83DragonFly BSD (amd64), illumos (amd64), and Solaris (amd64).
84
85The Go VFS is tested by running SQLite's
86[mptest](https://github.com/sqlite/sqlite/blob/master/mptest/mptest.c).
87
88### Performance
89
90Performance of the [`database/sql`](https://pkg.go.dev/database/sql) driver is
91[competitive](https://github.com/cvilsmeier/go-sqlite-bench) with alternatives.
92
93The Wasm and VFS layers are also benchmarked by running SQLite's
94[speedtest1](https://github.com/sqlite/sqlite/blob/master/test/speedtest1.c).
95
96### Concurrency
97
98This module behaves similarly to SQLite in [multi-thread](https://sqlite.org/threadsafe.html) mode:
99it is goroutine-safe, provided that no single database connection, or object derived from it,
100is used concurrently by multiple goroutines.
101
102The [`database/sql`](https://pkg.go.dev/database/sql) API is safe to use concurrently,
103according to its documentation.
104
105### FAQ, issues, new features
106
107For questions, please see [Discussions](https://github.com/ncruces/go-sqlite3/discussions/categories/q-a).
108
109Also, post there if you used this driver for something interesting
110([_"Show and tell"_](https://github.com/ncruces/go-sqlite3/discussions/categories/show-and-tell)),
111have an [idea](https://github.com/ncruces/go-sqlite3/discussions/categories/ideas)…
112
113The [Issue](https://github.com/ncruces/go-sqlite3/issues) tracker is for bugs,
114and features we're working on, planning to work on, or asking for help with.
115
116### Alternatives
117
118- [`modernc.org/sqlite`](https://pkg.go.dev/modernc.org/sqlite)
119- [`crawshaw.io/sqlite`](https://pkg.go.dev/crawshaw.io/sqlite)
120- [`github.com/mattn/go-sqlite3`](https://pkg.go.dev/github.com/mattn/go-sqlite3)
121- [`github.com/zombiezen/go-sqlite`](https://pkg.go.dev/github.com/zombiezen/go-sqlite)