-
Notifications
You must be signed in to change notification settings - Fork 0
/
doc.go
359 lines (358 loc) · 11.6 KB
/
doc.go
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
// 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.46.0
// darwin arm64 3.46.0
// freebsd amd64 3.46.0
// freebsd arm64 3.46.0
// linux 386 3.46.0
// linux amd64 3.46.0
// linux arm 3.46.0
// linux arm64 3.46.0
// linux loong64 3.46.0
// linux ppc64le 3.46.0
// linux riscv64 3.46.0
// linux s390x 3.46.0
// windows 386 3.46.0
// windows amd64 3.46.0
// windows arm64 3.46.0
//
// # Builders
//
// Builder results available at:
//
// https://modern-c.appspot.com/-/builder/?importpath=modernc.org%2fsqlite
//
// # Fragile modernc.org/libc dependency
//
// When you import this package you should use in your go.mod file the exact
// same version of modernc.org/libc as seen in the go.mod file of this
// repository.
//
// See the discussion at https://gitlab.com/cznic/sqlite/-/issues/177 for more details.
//
// # Changelog
//
// 2024-07-22: v1.31.0
//
// Support windows/386.
//
// 2024-06-04: v1.30.0
//
// Upgrade to SQLite 3.46.0, release notes at https://sqlite.org/releaselog/3_46_0.html.
//
// 2024-02-13: v1.29.0
//
// Upgrade to SQLite 3.45.1, release notes at https://sqlite.org/releaselog/3_45_1.html.
//
// 2023-12-14 v1.28.0:
//
// (*Driver).RegisterConnectionHook: added
// ConnectionHookFn: added
// ExecQuerierContext: added
// RegisterConnectionHook: added
//
// 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 <[email protected]>
// 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 <[email protected]>
// 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"