mirror of
https://github.com/superseriousbusiness/gotosocial.git
synced 2024-12-13 02:20:47 +01:00
49009fbd8f
This fixes some linkname shenanigans previous versions of the library were using. It's now safe to upgrade to Go 1.23 and beyond once they become available.
121 lines
7.0 KiB
Markdown
121 lines
7.0 KiB
Markdown
# Go bindings to SQLite using Wazero
|
|
|
|
[](https://pkg.go.dev/github.com/ncruces/go-sqlite3)
|
|
[](https://goreportcard.com/report/github.com/ncruces/go-sqlite3)
|
|
[](https://github.com/ncruces/go-sqlite3/wiki/Test-coverage-report)
|
|
|
|
Go module `github.com/ncruces/go-sqlite3` is a `cgo`-free [SQLite](https://sqlite.org/) wrapper.\
|
|
It provides a [`database/sql`](https://pkg.go.dev/database/sql) compatible driver,
|
|
as well as direct access to most of the [C SQLite API](https://sqlite.org/cintro.html).
|
|
|
|
It wraps a [Wasm](https://webassembly.org/) [build](embed/) of SQLite,
|
|
and uses [wazero](https://wazero.io/) as the runtime.\
|
|
Go, wazero and [`x/sys`](https://pkg.go.dev/golang.org/x/sys) are the _only_ runtime dependencies [^1].
|
|
|
|
### Packages
|
|
|
|
- [`github.com/ncruces/go-sqlite3`](https://pkg.go.dev/github.com/ncruces/go-sqlite3)
|
|
wraps the [C SQLite API](https://sqlite.org/cintro.html)
|
|
([example usage](https://pkg.go.dev/github.com/ncruces/go-sqlite3#example-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)).
|
|
- [`github.com/ncruces/go-sqlite3/embed`](https://pkg.go.dev/github.com/ncruces/go-sqlite3/embed)
|
|
embeds a build of SQLite into your application.
|
|
- [`github.com/ncruces/go-sqlite3/vfs`](https://pkg.go.dev/github.com/ncruces/go-sqlite3/vfs)
|
|
wraps the [C SQLite VFS API](https://sqlite.org/vfs.html) and provides a pure Go implementation.
|
|
- [`github.com/ncruces/go-sqlite3/gormlite`](https://pkg.go.dev/github.com/ncruces/go-sqlite3/gormlite)
|
|
provides a [GORM](https://gorm.io) driver.
|
|
|
|
### Extensions
|
|
|
|
- [`github.com/ncruces/go-sqlite3/ext/array`](https://pkg.go.dev/github.com/ncruces/go-sqlite3/ext/array)
|
|
provides the [`array`](https://sqlite.org/carray.html) table-valued function.
|
|
- [`github.com/ncruces/go-sqlite3/ext/blobio`](https://pkg.go.dev/github.com/ncruces/go-sqlite3/ext/blobio)
|
|
simplifies [incremental BLOB I/O](https://sqlite.org/c3ref/blob_open.html).
|
|
- [`github.com/ncruces/go-sqlite3/ext/bloom`](https://pkg.go.dev/github.com/ncruces/go-sqlite3/ext/bloom)
|
|
provides a [Bloom filter](https://github.com/nalgeon/sqlean/issues/27#issuecomment-1002267134) virtual table.
|
|
- [`github.com/ncruces/go-sqlite3/ext/csv`](https://pkg.go.dev/github.com/ncruces/go-sqlite3/ext/csv)
|
|
reads [comma-separated values](https://sqlite.org/csv.html).
|
|
- [`github.com/ncruces/go-sqlite3/ext/fileio`](https://pkg.go.dev/github.com/ncruces/go-sqlite3/ext/fileio)
|
|
reads, writes and lists files.
|
|
- [`github.com/ncruces/go-sqlite3/ext/hash`](https://pkg.go.dev/github.com/ncruces/go-sqlite3/ext/hash)
|
|
provides cryptographic hash functions.
|
|
- [`github.com/ncruces/go-sqlite3/ext/lines`](https://pkg.go.dev/github.com/ncruces/go-sqlite3/ext/lines)
|
|
reads data [line-by-line](https://github.com/asg017/sqlite-lines).
|
|
- [`github.com/ncruces/go-sqlite3/ext/pivot`](https://pkg.go.dev/github.com/ncruces/go-sqlite3/ext/pivot)
|
|
creates [pivot tables](https://github.com/jakethaw/pivot_vtab).
|
|
- [`github.com/ncruces/go-sqlite3/ext/regexp`](https://pkg.go.dev/github.com/ncruces/go-sqlite3/ext/regexp)
|
|
provides regular expression functions.
|
|
- [`github.com/ncruces/go-sqlite3/ext/statement`](https://pkg.go.dev/github.com/ncruces/go-sqlite3/ext/statement)
|
|
creates [parameterized views](https://github.com/0x09/sqlite-statement-vtab).
|
|
- [`github.com/ncruces/go-sqlite3/ext/stats`](https://pkg.go.dev/github.com/ncruces/go-sqlite3/ext/stats)
|
|
provides [statistics](https://www.oreilly.com/library/view/sql-in-a/9780596155322/ch04s02.html) functions.
|
|
- [`github.com/ncruces/go-sqlite3/ext/unicode`](https://pkg.go.dev/github.com/ncruces/go-sqlite3/ext/unicode)
|
|
provides [Unicode aware](https://sqlite.org/src/dir/ext/icu) functions.
|
|
- [`github.com/ncruces/go-sqlite3/ext/uuid`](https://pkg.go.dev/github.com/ncruces/go-sqlite3/ext/uuid)
|
|
generates [UUIDs](https://en.wikipedia.org/wiki/Universally_unique_identifier).
|
|
- [`github.com/ncruces/go-sqlite3/ext/zorder`](https://pkg.go.dev/github.com/ncruces/go-sqlite3/ext/zorder)
|
|
maps multidimensional data to one dimension.
|
|
- [`github.com/ncruces/go-sqlite3/vfs/adiantum`](https://pkg.go.dev/github.com/ncruces/go-sqlite3/vfs/adiantum)
|
|
wraps a VFS to offer encryption at rest.
|
|
- [`github.com/ncruces/go-sqlite3/vfs/memdb`](https://pkg.go.dev/github.com/ncruces/go-sqlite3/vfs/memdb)
|
|
implements an in-memory VFS.
|
|
- [`github.com/ncruces/go-sqlite3/vfs/readervfs`](https://pkg.go.dev/github.com/ncruces/go-sqlite3/vfs/readervfs)
|
|
implements a VFS for immutable databases.
|
|
|
|
### Advanced features
|
|
|
|
- [incremental BLOB I/O](https://sqlite.org/c3ref/blob_open.html)
|
|
- [nested transactions](https://sqlite.org/lang_savepoint.html)
|
|
- [custom functions](https://sqlite.org/c3ref/create_function.html)
|
|
- [virtual tables](https://sqlite.org/vtab.html)
|
|
- [custom VFSes](https://sqlite.org/vfs.html)
|
|
- [online backup](https://sqlite.org/backup.html)
|
|
- [JSON support](https://sqlite.org/json1.html)
|
|
- [math functions](https://sqlite.org/lang_mathfunc.html)
|
|
- [full-text search](https://sqlite.org/fts5.html)
|
|
- [geospatial search](https://sqlite.org/geopoly.html)
|
|
- [encryption at rest](vfs/adiantum/README.md)
|
|
- [and more…](embed/README.md)
|
|
|
|
### Caveats
|
|
|
|
This module replaces the SQLite [OS Interface](https://sqlite.org/vfs.html)
|
|
(aka VFS) with a [pure Go](vfs/) implementation,
|
|
which has advantages and disadvantages.
|
|
|
|
Read more about the Go VFS design [here](vfs/README.md).
|
|
|
|
### Testing
|
|
|
|
This project aims for [high test coverage](https://github.com/ncruces/go-sqlite3/wiki/Test-coverage-report).
|
|
It also benefits greatly from [SQLite's](https://sqlite.org/testing.html) and
|
|
[wazero's](https://tetrate.io/blog/introducing-wazero-from-tetrate/#:~:text=Rock%2Dsolid%20test%20approach) thorough testing.
|
|
|
|
Every commit is [tested](.github/workflows/test.yml) on
|
|
Linux (amd64/arm64/386/riscv64/s390x), macOS (amd64/arm64),
|
|
Windows (amd64), FreeBSD (amd64), OpenBSD (amd64), NetBSD (amd64),
|
|
illumos (amd64), and Solaris (amd64).
|
|
|
|
The Go VFS is tested by running SQLite's
|
|
[mptest](https://github.com/sqlite/sqlite/blob/master/mptest/mptest.c).
|
|
|
|
### Performance
|
|
|
|
Perfomance of the [`database/sql`](https://pkg.go.dev/database/sql) driver is
|
|
[competitive](https://github.com/cvilsmeier/go-sqlite-bench) with alternatives.
|
|
|
|
The Wasm and VFS layers are also tested by running SQLite's
|
|
[speedtest1](https://github.com/sqlite/sqlite/blob/master/test/speedtest1.c).
|
|
|
|
### Alternatives
|
|
|
|
- [`modernc.org/sqlite`](https://pkg.go.dev/modernc.org/sqlite)
|
|
- [`crawshaw.io/sqlite`](https://pkg.go.dev/crawshaw.io/sqlite)
|
|
- [`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)
|
|
|
|
[^1]: anything else you find in `go.mod` is either a test dependency,
|
|
or needed by one of the extensions.
|