GoToSocial/vendor/modernc.org/sqlite/doc.go

384 lines
17 KiB
Go
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

// Copyright 2017 The Sqlite Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.
// Package sqlite is a sql/database driver using a CGo-free port of the C
// SQLite3 library.
//
// SQLite is an in-process implementation of a self-contained, serverless,
// zero-configuration, transactional SQL database engine.
//
// # Thanks
//
// This project is sponsored by Schleibinger Geräte Teubert u. Greim GmbH by
// allowing one of the maintainers to work on it also in office hours.
//
// # Supported platforms and architectures
//
// These combinations of GOOS and GOARCH are currently supported
//
// OS Arch SQLite version
// ------------------------------
// darwin amd64 3.41.2
// darwin arm64 3.41.2
// freebsd amd64 3.41.2
// freebsd arm64 3.41.2
// linux 386 3.41.2
// linux amd64 3.41.2
// linux arm 3.41.2
// linux arm64 3.41.2
// linux ppc64le 3.41.2
// linux riscv64 3.41.2
// linux s390x 3.41.2
// windows amd64 3.41.2
// windows arm64 3.41.2
//
// # Builders
//
// Builder results available at:
//
// https://modern-c.appspot.com/-/builder/?importpath=modernc.org%2fsqlite
//
// # Speedtest1
//
// Numbers for the pure Go version were produced by
//
// ~/src/modernc.org/sqlite/speedtest1$ go build && ./speedtest1
//
// Numbers for the pure C version were produced by
//
// ~/src/modernc.org/sqlite/testdata/sqlite-src-3410200/test$ gcc speedtest1.c ../../sqlite-amalgamation-3410200/sqlite3.c -lpthread -ldl && ./a.out
//
// The results are from Go version 1.20.4 and GCC version 10.2.1 on a
// Linux/amd64 machine, CPU: AMD Ryzen 9 3900X 12-Core Processor × 24, 128GB
// RAM. Shown are the best of 3 runs.
//
// Go C
//
// -- Speedtest1 for SQLite 3.41.2 2023-03-22 11:56:21 0d1fc92f94cb6b76bffe3ec34d69 -- Speedtest1 for SQLite 3.41.2 2023-03-22 11:56:21 0d1fc92f94cb6b76bffe3ec34d69
// 100 - 50000 INSERTs into table with no index...................... 0.071s 100 - 50000 INSERTs into table with no index...................... 0.077s
// 110 - 50000 ordered INSERTS with one index/PK..................... 0.114s 110 - 50000 ordered INSERTS with one index/PK..................... 0.082s
// 120 - 50000 unordered INSERTS with one index/PK................... 0.137s 120 - 50000 unordered INSERTS with one index/PK................... 0.099s
// 130 - 25 SELECTS, numeric BETWEEN, unindexed...................... 0.083s 130 - 25 SELECTS, numeric BETWEEN, unindexed...................... 0.091s
// 140 - 10 SELECTS, LIKE, unindexed................................. 0.210s 140 - 10 SELECTS, LIKE, unindexed................................. 0.120s
// 142 - 10 SELECTS w/ORDER BY, unindexed............................ 0.276s 142 - 10 SELECTS w/ORDER BY, unindexed............................ 0.182s
// 145 - 10 SELECTS w/ORDER BY and LIMIT, unindexed.................. 0.183s 145 - 10 SELECTS w/ORDER BY and LIMIT, unindexed.................. 0.099s
// 150 - CREATE INDEX five times..................................... 0.172s 150 - CREATE INDEX five times..................................... 0.127s
// 160 - 10000 SELECTS, numeric BETWEEN, indexed..................... 0.080s 160 - 10000 SELECTS, numeric BETWEEN, indexed..................... 0.078s
// 161 - 10000 SELECTS, numeric BETWEEN, PK.......................... 0.080s 161 - 10000 SELECTS, numeric BETWEEN, PK.......................... 0.078s
// 170 - 10000 SELECTS, text BETWEEN, indexed........................ 0.187s 170 - 10000 SELECTS, text BETWEEN, indexed........................ 0.169s
// 180 - 50000 INSERTS with three indexes............................ 0.196s 180 - 50000 INSERTS with three indexes............................ 0.154s
// 190 - DELETE and REFILL one table................................. 0.200s 190 - DELETE and REFILL one table................................. 0.155s
// 200 - VACUUM...................................................... 0.180s 200 - VACUUM...................................................... 0.142s
// 210 - ALTER TABLE ADD COLUMN, and query........................... 0.004s 210 - ALTER TABLE ADD COLUMN, and query........................... 0.005s
// 230 - 10000 UPDATES, numeric BETWEEN, indexed..................... 0.093s 230 - 10000 UPDATES, numeric BETWEEN, indexed..................... 0.080s
// 240 - 50000 UPDATES of individual rows............................ 0.153s 240 - 50000 UPDATES of individual rows............................ 0.137s
// 250 - One big UPDATE of the whole 50000-row table................. 0.024s 250 - One big UPDATE of the whole 50000-row table................. 0.019s
// 260 - Query added column after filling............................ 0.004s 260 - Query added column after filling............................ 0.005s
// 270 - 10000 DELETEs, numeric BETWEEN, indexed..................... 0.278s 270 - 10000 DELETEs, numeric BETWEEN, indexed..................... 0.263s
// 280 - 50000 DELETEs of individual rows............................ 0.188s 280 - 50000 DELETEs of individual rows............................ 0.180s
// 290 - Refill two 50000-row tables using REPLACE................... 0.411s 290 - Refill two 50000-row tables using REPLACE................... 0.359s
// 300 - Refill a 50000-row table using (b&1)==(a&1)................. 0.175s 300 - Refill a 50000-row table using (b&1)==(a&1)................. 0.151s
// 310 - 10000 four-ways joins....................................... 0.427s 310 - 10000 four-ways joins....................................... 0.365s
// 320 - subquery in result set...................................... 0.440s 320 - subquery in result set...................................... 0.521s
// 400 - 70000 REPLACE ops on an IPK................................. 0.125s 400 - 70000 REPLACE ops on an IPK................................. 0.106s
// 410 - 70000 SELECTS on an IPK..................................... 0.081s 410 - 70000 SELECTS on an IPK..................................... 0.078s
// 500 - 70000 REPLACE on TEXT PK.................................... 0.174s 500 - 70000 REPLACE on TEXT PK.................................... 0.116s
// 510 - 70000 SELECTS on a TEXT PK.................................. 0.153s 510 - 70000 SELECTS on a TEXT PK.................................. 0.117s
// 520 - 70000 SELECT DISTINCT....................................... 0.083s 520 - 70000 SELECT DISTINCT....................................... 0.067s
// 980 - PRAGMA integrity_check...................................... 0.436s 980 - PRAGMA integrity_check...................................... 0.377s
// 990 - ANALYZE..................................................... 0.107s 990 - ANALYZE..................................................... 0.038s
// TOTAL....................................................... 5.525s TOTAL....................................................... 4.637s
//
// This particular test executes 16.1% faster in the C version.
//
// # Changelog
//
// 2023-08-03 v1.25.0: enable SQLITE_ENABLE_DBSTAT_VTAB.
//
// 2023-07-11 v1.24.0:
//
// Add (*conn).{Serialize,Deserialize,NewBackup,NewRestore} methods, add Backup type.
//
// 2023-06-01 v1.23.0:
//
// Allow registering aggregate functions.
//
// 2023-04-22 v1.22.0:
//
// Support linux/s390x.
//
// 2023-02-23 v1.21.0:
//
// Upgrade to SQLite 3.41.0, release notes at https://sqlite.org/releaselog/3_41_0.html.
//
// 2022-11-28 v1.20.0
//
// Support linux/ppc64le.
//
// 2022-09-16 v1.19.0:
//
// Support frebsd/arm64.
//
// 2022-07-26 v1.18.0:
//
// Adds support for Go fs.FS based SQLite virtual filesystems, see function New
// in modernc.org/sqlite/vfs and/or TestVFS in all_test.go
//
// 2022-04-24 v1.17.0:
//
// Support windows/arm64.
//
// 2022-04-04 v1.16.0:
//
// Support scalar application defined functions written in Go.
//
// https://www.sqlite.org/appfunc.html
//
// 2022-03-13 v1.15.0:
//
// Support linux/riscv64.
//
// 2021-11-13 v1.14.0:
//
// Support windows/amd64. This target had previously only experimental status
// because of a now resolved memory leak.
//
// 2021-09-07 v1.13.0:
//
// Support freebsd/amd64.
//
// 2021-06-23 v1.11.0:
//
// Upgrade to use sqlite 3.36.0, release notes at https://www.sqlite.org/releaselog/3_36_0.html.
//
// 2021-05-06 v1.10.6:
//
// Fixes a memory corruption issue
// (https://gitlab.com/cznic/sqlite/-/issues/53). Versions since v1.8.6 were
// affected and should be updated to v1.10.6.
//
// 2021-03-14 v1.10.0:
//
// Update to use sqlite 3.35.0, release notes at https://www.sqlite.org/releaselog/3_35_0.html.
//
// 2021-03-11 v1.9.0:
//
// Support darwin/arm64.
//
// 2021-01-08 v1.8.0:
//
// Support darwin/amd64.
//
// 2020-09-13 v1.7.0:
//
// Support linux/arm and linux/arm64.
//
// 2020-09-08 v1.6.0:
//
// Support linux/386.
//
// 2020-09-03 v1.5.0:
//
// This project is now completely CGo-free, including the Tcl tests.
//
// 2020-08-26 v1.4.0:
//
// First stable release for linux/amd64. The database/sql driver and its tests
// are CGo free. Tests of the translated sqlite3.c library still require CGo.
//
// $ make full
//
// ...
//
// SQLite 2020-08-14 13:23:32 fca8dc8b578f215a969cd899336378966156154710873e68b3d9ac5881b0ff3f
// 0 errors out of 928271 tests on 3900x Linux 64-bit little-endian
// WARNING: Multi-threaded tests skipped: Linked against a non-threadsafe Tcl build
// All memory allocations freed - no leaks
// Maximum memory usage: 9156360 bytes
// Current memory usage: 0 bytes
// Number of malloc() : -1 calls
// --- PASS: TestTclTest (1785.04s)
// PASS
// ok modernc.org/sqlite 1785.041s
// $
//
// 2020-07-26 v1.4.0-beta1:
//
// The project has reached beta status while supporting linux/amd64 only at the
// moment. The 'extraquick' Tcl testsuite reports
//
// 630 errors out of 200177 tests on Linux 64-bit little-endian
//
// and some memory leaks
//
// Unfreed memory: 698816 bytes in 322 allocations
//
// 2019-12-28 v1.2.0-alpha.3: Third alpha fixes issue #19.
//
// It also bumps the minor version as the repository was wrongly already tagged
// with v1.1.0 before. Even though the tag was deleted there are proxies that
// cached that tag. Thanks /u/garaktailor for detecting the problem and
// suggesting this solution.
//
// 2019-12-26 v1.1.0-alpha.2: Second alpha release adds support for accessing a
// database concurrently by multiple goroutines and/or processes. v1.1.0 is now
// considered feature-complete. Next planed release should be a beta with a
// proper test suite.
//
// 2019-12-18 v1.1.0-alpha.1: First alpha release using the new cc/v3, gocc,
// qbe toolchain. Some primitive tests pass on linux_{amd64,386}. Not yet safe
// for concurrent access by multiple goroutines. Next alpha release is planed
// to arrive before the end of this year.
//
// 2017-06-10 Windows/Intel no more uses the VM (thanks Steffen Butzer).
//
// 2017-06-05 Linux/Intel no more uses the VM (cznic/virtual).
//
// # Connecting to a database
//
// To access a Sqlite database do something like
//
// import (
// "database/sql"
//
// _ "modernc.org/sqlite"
// )
//
// ...
//
//
// db, err := sql.Open("sqlite", dsnURI)
//
// ...
//
// # Debug and development versions
//
// A comma separated list of options can be passed to `go generate` via the
// environment variable GO_GENERATE. Some useful options include for example:
//
// -DSQLITE_DEBUG
// -DSQLITE_MEM_DEBUG
// -ccgo-verify-structs
//
// To create a debug/development version, issue for example:
//
// $ GO_GENERATE=-DSQLITE_DEBUG,-DSQLITE_MEM_DEBUG go generate
//
// Note: To run `go generate` you need to have modernc.org/ccgo/v3 installed.
//
// # Hacking
//
// This is an example of how to use the debug logs in modernc.org/libc when hunting a bug.
//
// 0:jnml@e5-1650:~/src/modernc.org/sqlite$ git status
// On branch master
// Your branch is up to date with 'origin/master'.
//
// nothing to commit, working tree clean
// 0:jnml@e5-1650:~/src/modernc.org/sqlite$ git log -1
// commit df33b8d15107f3cc777799c0fe105f74ef499e62 (HEAD -> master, tag: v1.21.1, origin/master, origin/HEAD, wips, ok)
// Author: Jan Mercl <0xjnml@gmail.com>
// Date: Mon Mar 27 16:18:28 2023 +0200
//
// upgrade to SQLite 3.41.2
// 0:jnml@e5-1650:~/src/modernc.org/sqlite$ rm -f /tmp/libc.log ; go test -v -tags=libc.dmesg -run TestScalar ; ls -l /tmp/libc.log
// test binary compiled for linux/amd64
// === RUN TestScalar
// --- PASS: TestScalar (0.09s)
// PASS
// ok modernc.org/sqlite 0.128s
// -rw-r--r-- 1 jnml jnml 76 Apr 6 11:22 /tmp/libc.log
// 0:jnml@e5-1650:~/src/modernc.org/sqlite$ cat /tmp/libc.log
// [10723 sqlite.test] 2023-04-06 11:22:48.288066057 +0200 CEST m=+0.000707150
// 0:jnml@e5-1650:~/src/modernc.org/sqlite$
//
// The /tmp/libc.log file is created as requested. No useful messages there because none are enabled in libc. Let's try to enable Xwrite as an example.
//
// 0:jnml@e5-1650:~/src/modernc.org/libc$ git status
// On branch master
// Your branch is up to date with 'origin/master'.
//
// Changes not staged for commit:
// (use "git add <file>..." to update what will be committed)
// (use "git restore <file>..." to discard changes in working directory)
// modified: libc_linux.go
//
// no changes added to commit (use "git add" and/or "git commit -a")
// 0:jnml@e5-1650:~/src/modernc.org/libc$ git log -1
// commit 1e22c18cf2de8aa86d5b19b165f354f99c70479c (HEAD -> master, tag: v1.22.3, origin/master, origin/HEAD)
// Author: Jan Mercl <0xjnml@gmail.com>
// Date: Wed Feb 22 20:27:45 2023 +0100
//
// support sqlite 3.41 on linux targets
// 0:jnml@e5-1650:~/src/modernc.org/libc$ git diff
// diff --git a/libc_linux.go b/libc_linux.go
// index 1c2f482..ac1f08d 100644
// --- a/libc_linux.go
// +++ b/libc_linux.go
// @@ -332,19 +332,19 @@ func Xwrite(t *TLS, fd int32, buf uintptr, count types.Size_t) types.Ssize_t {
// var n uintptr
// switch n, _, err = unix.Syscall(unix.SYS_WRITE, uintptr(fd), buf, uintptr(count)); err {
// case 0:
// - // if dmesgs {
// - // // dmesg("%v: %d %#x: %#x\n%s", origin(1), fd, count, n, hex.Dump(GoBytes(buf, int(n))))
// - // dmesg("%v: %d %#x: %#x", origin(1), fd, count, n)
// - // }
// + if dmesgs {
// + // dmesg("%v: %d %#x: %#x\n%s", origin(1), fd, count, n, hex.Dump(GoBytes(buf, int(n))))
// + dmesg("%v: %d %#x: %#x", origin(1), fd, count, n)
// + }
// return types.Ssize_t(n)
// case errno.EAGAIN:
// // nop
// }
// }
//
// - // if dmesgs {
// - // dmesg("%v: fd %v, count %#x: %v", origin(1), fd, count, err)
// - // }
// + if dmesgs {
// + dmesg("%v: fd %v, count %#x: %v", origin(1), fd, count, err)
// + }
// t.setErrno(err)
// return -1
// }
// 0:jnml@e5-1650:~/src/modernc.org/libc$
//
// We need to tell the Go build system to use our local, patched/debug libc:
//
// 0:jnml@e5-1650:~/src/modernc.org/sqlite$ go work use $(go env GOPATH)/src/modernc.org/libc
// 0:jnml@e5-1650:~/src/modernc.org/sqlite$ go work use .
//
// And run the test again:
//
// 0:jnml@e5-1650:~/src/modernc.org/sqlite$ rm -f /tmp/libc.log ; go test -v -tags=libc.dmesg -run TestScalar ; ls -l /tmp/libc.log
// test binary compiled for linux/amd64
// === RUN TestScalar
// --- PASS: TestScalar (0.26s)
// PASS
// ok modernc.org/sqlite 0.285s
// -rw-r--r-- 1 jnml jnml 918 Apr 6 11:29 /tmp/libc.log
// 0:jnml@e5-1650:~/src/modernc.org/sqlite$ cat /tmp/libc.log
// [11910 sqlite.test] 2023-04-06 11:29:13.143589542 +0200 CEST m=+0.000689270
// [11910 sqlite.test] libc_linux.go:337:Xwrite: 8 0x200: 0x200
// [11910 sqlite.test] libc_linux.go:337:Xwrite: 8 0xc: 0xc
// [11910 sqlite.test] libc_linux.go:337:Xwrite: 7 0x1000: 0x1000
// [11910 sqlite.test] libc_linux.go:337:Xwrite: 7 0x1000: 0x1000
// [11910 sqlite.test] libc_linux.go:337:Xwrite: 8 0x200: 0x200
// [11910 sqlite.test] libc_linux.go:337:Xwrite: 8 0x4: 0x4
// [11910 sqlite.test] libc_linux.go:337:Xwrite: 8 0x1000: 0x1000
// [11910 sqlite.test] libc_linux.go:337:Xwrite: 8 0x4: 0x4
// [11910 sqlite.test] libc_linux.go:337:Xwrite: 8 0x4: 0x4
// [11910 sqlite.test] libc_linux.go:337:Xwrite: 8 0x1000: 0x1000
// [11910 sqlite.test] libc_linux.go:337:Xwrite: 8 0x4: 0x4
// [11910 sqlite.test] libc_linux.go:337:Xwrite: 8 0xc: 0xc
// [11910 sqlite.test] libc_linux.go:337:Xwrite: 7 0x1000: 0x1000
// [11910 sqlite.test] libc_linux.go:337:Xwrite: 7 0x1000: 0x1000
// 0:jnml@e5-1650:~/src/modernc.org/sqlite$
//
// # Sqlite documentation
//
// See https://sqlite.org/docs.html
package sqlite // import "modernc.org/sqlite"