mirror of
https://github.com/superseriousbusiness/gotosocial.git
synced 2025-10-31 05:32:25 -05:00
3b46eb6a9e
# Description Upgrades ncruces/go-sqlite3 to 0.26 which includes SQLite 3.50. ## Checklist Please put an x inside each checkbox to indicate that you've read and followed it: `[ ]` -> `[x]` If this is a documentation change, only the first checkbox must be filled (you can delete the others if you want). - [x] I/we have read the [GoToSocial contribution guidelines](https://codeberg.org/superseriousbusiness/gotosocial/src/branch/main/CONTRIBUTING.md). - [ ] I/we have discussed the proposed changes already, either in an issue on the repository, or in the Matrix chat. - [x] I/we have not leveraged AI to create the proposed changes. - [ ] I/we have performed a self-review of added code. - [ ] I/we have written code that is legible and maintainable by others. - [ ] I/we have commented the added code, particularly in hard-to-understand areas. - [ ] I/we have made any necessary changes to documentation. - [ ] I/we have added tests that cover new code. - [ ] I/we have run tests and they pass locally with the changes. - [ ] I/we have run `go fmt ./...` and `golangci-lint run`. Reviewed-on: https://codeberg.org/superseriousbusiness/gotosocial/pulls/4218 Co-authored-by: Daenney <daenney@noreply.codeberg.org> Co-committed-by: Daenney <daenney@noreply.codeberg.org>
136 lines
6.3 KiB
Markdown
136 lines
6.3 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_ direct dependencies.
|
|
|
|
### Getting started
|
|
|
|
Using the [`database/sql`](https://pkg.go.dev/database/sql) driver:
|
|
```go
|
|
|
|
import "database/sql"
|
|
import _ "github.com/ncruces/go-sqlite3/driver"
|
|
import _ "github.com/ncruces/go-sqlite3/embed"
|
|
|
|
var version string
|
|
db, _ := sql.Open("sqlite3", "file:demo.db")
|
|
db.QueryRow(`SELECT sqlite_version()`).Scan(&version)
|
|
```
|
|
|
|
### 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](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](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.
|
|
|
|
### Advanced features
|
|
|
|
- [incremental BLOB I/O](https://sqlite.org/c3ref/blob_open.html)
|
|
([example](https://pkg.go.dev/github.com/ncruces/go-sqlite3/ext/blobio#example-package))
|
|
- [nested transactions](https://sqlite.org/lang_savepoint.html)
|
|
([example](https://pkg.go.dev/github.com/ncruces/go-sqlite3/driver#example-Savepoint))
|
|
- [custom functions](https://sqlite.org/c3ref/create_function.html)
|
|
([example](https://pkg.go.dev/github.com/ncruces/go-sqlite3#example-Conn.CreateFunction))
|
|
- [virtual tables](https://sqlite.org/vtab.html)
|
|
([example](https://pkg.go.dev/github.com/ncruces/go-sqlite3#example-CreateModule))
|
|
- [custom VFSes](https://sqlite.org/vfs.html)
|
|
([examples](vfs/README.md#custom-vfses))
|
|
- [online backup](https://sqlite.org/backup.html)
|
|
([example](https://pkg.go.dev/github.com/ncruces/go-sqlite3/driver#Conn))
|
|
- [JSON support](https://sqlite.org/json1.html)
|
|
([example](https://pkg.go.dev/github.com/ncruces/go-sqlite3/driver#example-package-Json))
|
|
- [math functions](https://sqlite.org/lang_mathfunc.html)
|
|
- [full-text search](https://sqlite.org/fts5.html)
|
|
- [geospatial search](https://sqlite.org/geopoly.html)
|
|
- [Unicode support](https://pkg.go.dev/github.com/ncruces/go-sqlite3/ext/unicode)
|
|
- [statistics functions](https://pkg.go.dev/github.com/ncruces/go-sqlite3/ext/stats)
|
|
- [encryption at rest](vfs/adiantum/README.md)
|
|
- [many extensions](ext/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).
|
|
|
|
Because each database connection executes within a Wasm sandboxed environment,
|
|
memory usage will be higher than alternatives.
|
|
|
|
### 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 on:
|
|
* Linux: amd64, arm64, 386, riscv64, ppc64le, s390x
|
|
* macOS: amd64, arm64
|
|
* Windows: amd64
|
|
* BSD:
|
|
* FreeBSD: amd64, arm64
|
|
* OpenBSD: amd64
|
|
* NetBSD: amd64, arm64
|
|
* DragonFly BSD: amd64
|
|
* illumos: amd64
|
|
* Solaris: amd64
|
|
|
|
Certain operating system and CPU combinations have some limitations. See the [support matrix](https://github.com/ncruces/go-sqlite3/wiki/Support-matrix) for a complete overview.
|
|
|
|
The Go VFS is tested by running SQLite's
|
|
[mptest](https://github.com/sqlite/sqlite/blob/master/mptest/mptest.c).
|
|
|
|
### Performance
|
|
|
|
Performance 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 benchmarked by running SQLite's
|
|
[speedtest1](https://github.com/sqlite/sqlite/blob/master/test/speedtest1.c).
|
|
|
|
### Concurrency
|
|
|
|
This module behaves similarly to SQLite in [multi-thread](https://sqlite.org/threadsafe.html) mode:
|
|
it is goroutine-safe, provided that no single database connection, or object derived from it,
|
|
is used concurrently by multiple goroutines.
|
|
|
|
The [`database/sql`](https://pkg.go.dev/database/sql) API is safe to use concurrently,
|
|
according to its documentation.
|
|
|
|
### FAQ, issues, new features
|
|
|
|
For questions, please see [Discussions](https://github.com/ncruces/go-sqlite3/discussions/categories/q-a).
|
|
|
|
Also, post there if you used this driver for something interesting
|
|
([_"Show and tell"_](https://github.com/ncruces/go-sqlite3/discussions/categories/show-and-tell)),
|
|
have an [idea](https://github.com/ncruces/go-sqlite3/discussions/categories/ideas)…
|
|
|
|
The [Issue](https://github.com/ncruces/go-sqlite3/issues) tracker is for bugs,
|
|
and features we're working on, planning to work on, or asking for help with.
|
|
|
|
### 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)
|