sqlite3 1.5.4 → 2.9.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/CHANGELOG.md +594 -1
- data/CONTRIBUTING.md +112 -6
- data/{faq/faq.md → FAQ.md} +52 -84
- data/INSTALLATION.md +267 -0
- data/LICENSE +18 -22
- data/README.md +87 -124
- data/dependencies.yml +10 -11
- data/ext/sqlite3/aggregator.c +153 -147
- data/ext/sqlite3/aggregator.h +6 -4
- data/ext/sqlite3/backup.c +86 -64
- data/ext/sqlite3/backup.h +2 -2
- data/ext/sqlite3/database.c +744 -484
- data/ext/sqlite3/database.h +23 -4
- data/ext/sqlite3/exception.c +116 -92
- data/ext/sqlite3/exception.h +5 -1
- data/ext/sqlite3/extconf.rb +68 -33
- data/ext/sqlite3/sqlite3.c +177 -115
- data/ext/sqlite3/sqlite3_ruby.h +2 -2
- data/ext/sqlite3/statement.c +590 -293
- data/ext/sqlite3/statement.h +4 -3
- data/ext/sqlite3/timespec.h +20 -0
- data/lib/sqlite3/constants.rb +195 -47
- data/lib/sqlite3/database.rb +252 -195
- data/lib/sqlite3/errors.rb +54 -1
- data/lib/sqlite3/fork_safety.rb +66 -0
- data/lib/sqlite3/pragmas.rb +196 -143
- data/lib/sqlite3/resultset.rb +14 -105
- data/lib/sqlite3/statement.rb +58 -13
- data/lib/sqlite3/value.rb +17 -20
- data/lib/sqlite3/version.rb +2 -21
- data/lib/sqlite3/version_info.rb +17 -0
- data/lib/sqlite3.rb +8 -4
- data/ports/archives/sqlite-autoconf-3530200.tar.gz +0 -0
- metadata +16 -108
- data/API_CHANGES.md +0 -49
- data/ChangeLog.cvs +0 -88
- data/Gemfile +0 -3
- data/LICENSE-DEPENDENCIES +0 -20
- data/faq/faq.rb +0 -145
- data/faq/faq.yml +0 -426
- data/lib/sqlite3/translator.rb +0 -118
- data/ports/archives/sqlite-autoconf-3400000.tar.gz +0 -0
- data/test/helper.rb +0 -27
- data/test/test_backup.rb +0 -33
- data/test/test_collation.rb +0 -82
- data/test/test_database.rb +0 -545
- data/test/test_database_flags.rb +0 -95
- data/test/test_database_readonly.rb +0 -36
- data/test/test_database_readwrite.rb +0 -41
- data/test/test_deprecated.rb +0 -44
- data/test/test_encoding.rb +0 -155
- data/test/test_integration.rb +0 -507
- data/test/test_integration_aggregate.rb +0 -336
- data/test/test_integration_open_close.rb +0 -30
- data/test/test_integration_pending.rb +0 -115
- data/test/test_integration_resultset.rb +0 -142
- data/test/test_integration_statement.rb +0 -194
- data/test/test_result_set.rb +0 -37
- data/test/test_sqlite3.rb +0 -30
- data/test/test_statement.rb +0 -263
- data/test/test_statement_execute.rb +0 -35
data/README.md
CHANGED
|
@@ -1,22 +1,31 @@
|
|
|
1
1
|
# Ruby Interface for SQLite3
|
|
2
2
|
|
|
3
|
+
## Overview
|
|
4
|
+
|
|
5
|
+
This library allows Ruby programs to use the SQLite3 database engine (http://www.sqlite.org).
|
|
6
|
+
|
|
7
|
+
Note that this module is only compatible with SQLite 3.6.16 or newer.
|
|
8
|
+
|
|
3
9
|
* Source code: https://github.com/sparklemotion/sqlite3-ruby
|
|
4
10
|
* Mailing list: http://groups.google.com/group/sqlite3-ruby
|
|
5
11
|
* Download: http://rubygems.org/gems/sqlite3
|
|
6
|
-
* Documentation:
|
|
12
|
+
* Documentation: https://sparklemotion.github.io/sqlite3-ruby/
|
|
7
13
|
|
|
8
|
-
[](https://github.com/sparklemotion/sqlite3-ruby/actions/workflows/gem-install.yml)
|
|
14
|
+
[](https://github.com/sparklemotion/sqlite3-ruby/actions/workflows/ci.yml)
|
|
10
15
|
|
|
11
16
|
|
|
12
|
-
##
|
|
17
|
+
## Quick start
|
|
13
18
|
|
|
14
|
-
|
|
19
|
+
For help understanding the SQLite3 Ruby API, please read the [FAQ](./FAQ.md) and the [full API documentation](https://sparklemotion.github.io/sqlite3-ruby/).
|
|
15
20
|
|
|
16
|
-
|
|
21
|
+
A few key classes whose APIs are often-used are:
|
|
22
|
+
|
|
23
|
+
- SQLite3::Database ([rdoc](https://sparklemotion.github.io/sqlite3-ruby/SQLite3/Database.html))
|
|
24
|
+
- SQLite3::Statement ([rdoc](https://sparklemotion.github.io/sqlite3-ruby/SQLite3/Statement.html))
|
|
25
|
+
- SQLite3::ResultSet ([rdoc](https://sparklemotion.github.io/sqlite3-ruby/SQLite3/ResultSet.html))
|
|
17
26
|
|
|
27
|
+
If you have any questions that you feel should be addressed in the FAQ, please send them to [the mailing list](http://groups.google.com/group/sqlite3-ruby) or open a [discussion thread](https://github.com/sparklemotion/sqlite3-ruby/discussions/categories/q-a).
|
|
18
28
|
|
|
19
|
-
## Synopsis
|
|
20
29
|
|
|
21
30
|
``` ruby
|
|
22
31
|
require "sqlite3"
|
|
@@ -67,157 +76,111 @@ end
|
|
|
67
76
|
# => ["Jane", "me@janedoe.com", "A", "http://blog.janedoe.com"]
|
|
68
77
|
```
|
|
69
78
|
|
|
70
|
-
##
|
|
71
|
-
|
|
72
|
-
### Native Gems (recommended)
|
|
73
|
-
|
|
74
|
-
As of v1.5.0 of this library, native (precompiled) gems are available for Ruby 2.6, 2.7, 3.0, and 3.1 on all these platforms:
|
|
75
|
-
|
|
76
|
-
- `aarch64-linux`
|
|
77
|
-
- `arm-linux`
|
|
78
|
-
- `arm64-darwin`
|
|
79
|
-
- `x64-mingw32` / `x64-mingw-ucrt`
|
|
80
|
-
- `x86-linux`
|
|
81
|
-
- `x86_64-darwin`
|
|
82
|
-
- `x86_64-linux`
|
|
83
|
-
|
|
84
|
-
If you are using one of these Ruby versions on one of these platforms, the native gem is the recommended way to install sqlite3-ruby.
|
|
85
|
-
|
|
86
|
-
For example, on a linux system running Ruby 3.1:
|
|
87
|
-
|
|
88
|
-
``` text
|
|
89
|
-
$ ruby -v
|
|
90
|
-
ruby 3.1.2p20 (2022-04-12 revision 4491bb740a) [x86_64-linux]
|
|
91
|
-
|
|
92
|
-
$ time gem install sqlite3
|
|
93
|
-
Fetching sqlite3-1.5.0-x86_64-linux.gem
|
|
94
|
-
Successfully installed sqlite3-1.5.0-x86_64-linux
|
|
95
|
-
1 gem installed
|
|
96
|
-
|
|
97
|
-
real 0m4.274s
|
|
98
|
-
user 0m0.734s
|
|
99
|
-
sys 0m0.165s
|
|
100
|
-
```
|
|
101
|
-
|
|
102
|
-
#### Avoiding the precompiled native gem
|
|
103
|
-
|
|
104
|
-
The maintainers strongly urge you to use a native gem if at all possible. It will be a better experience for you and allow us to focus our efforts on improving functionality rather than diagnosing installation issues.
|
|
105
|
-
|
|
106
|
-
If you're on a platform that supports a native gem but you want to avoid using it in your project, do one of the following:
|
|
107
|
-
|
|
108
|
-
- If you're not using Bundler, then run `gem install sqlite3 --platform=ruby`
|
|
109
|
-
- If you are using Bundler
|
|
110
|
-
- version 2.3.18 or later, you can specify [`gem "sqlite3", force_ruby_platform: true`](https://bundler.io/v2.3/man/gemfile.5.html#FORCE_RUBY_PLATFORM)
|
|
111
|
-
- version 2.1 or later, then you'll need to run `bundle config set force_ruby_platform true`
|
|
112
|
-
- version 2.0 or earlier, then you'll need to run `bundle config force_ruby_platform true`
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
### Compiling the source gem
|
|
116
|
-
|
|
117
|
-
If you are on a platform or version of Ruby that is not covered by the Native Gems, then the vanilla "ruby platform" (non-native) gem will be installed by the `gem install` or `bundle` commands.
|
|
79
|
+
## Thread Safety
|
|
118
80
|
|
|
81
|
+
When `SQLite3.threadsafe?` returns `true`, then SQLite3 has been compiled to
|
|
82
|
+
support running in a multithreaded environment. However, this doesn't mean
|
|
83
|
+
that all classes in the SQLite3 gem can be considered "thread safe".
|
|
119
84
|
|
|
120
|
-
|
|
85
|
+
When `SQLite3.threadsafe?` returns `true`, it is safe to share only
|
|
86
|
+
`SQLite3::Database` instances among threads without providing your own locking
|
|
87
|
+
mechanism. For example, the following code is fine because only the database
|
|
88
|
+
instance is shared among threads:
|
|
121
89
|
|
|
122
|
-
|
|
90
|
+
```ruby
|
|
91
|
+
require 'sqlite3'
|
|
123
92
|
|
|
124
|
-
|
|
93
|
+
db = SQLite3::Database.new ":memory:"
|
|
125
94
|
|
|
126
|
-
|
|
127
|
-
$ ruby -v
|
|
128
|
-
ruby 2.5.9p229 (2021-04-05 revision 67939) [x86_64-linux]
|
|
95
|
+
latch = Queue.new
|
|
129
96
|
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
97
|
+
ts = 10.times.map {
|
|
98
|
+
Thread.new {
|
|
99
|
+
latch.pop
|
|
100
|
+
db.execute "SELECT '#{Thread.current.inspect}'"
|
|
101
|
+
}
|
|
102
|
+
}
|
|
103
|
+
10.times { latch << nil }
|
|
134
104
|
|
|
135
|
-
|
|
136
|
-
user 0m23.361s
|
|
137
|
-
sys 0m5.839s
|
|
105
|
+
p ts.map(&:value)
|
|
138
106
|
```
|
|
139
107
|
|
|
108
|
+
Other instances can be shared among threads, but they require that you provide
|
|
109
|
+
your own locking for thread safety. For example, `SQLite3::Statement` objects
|
|
110
|
+
(prepared statements) are mutable, so applications must take care to add
|
|
111
|
+
appropriate locks to avoid data race conditions when sharing these objects
|
|
112
|
+
among threads.
|
|
140
113
|
|
|
141
|
-
|
|
114
|
+
Lets rewrite the above example but use a prepared statement and safely share
|
|
115
|
+
the prepared statement among threads:
|
|
142
116
|
|
|
143
|
-
|
|
117
|
+
```ruby
|
|
118
|
+
db = SQLite3::Database.new ":memory:"
|
|
144
119
|
|
|
145
|
-
|
|
120
|
+
# Prepare a statement
|
|
121
|
+
stmt = db.prepare "SELECT :inspect"
|
|
122
|
+
stmt_lock = Mutex.new
|
|
146
123
|
|
|
147
|
-
|
|
148
|
-
- only versions of libsqlite3 `>= 3.5.0` are supported,
|
|
149
|
-
- and some library features may depend on how your libsqlite3 was compiled.
|
|
124
|
+
latch = Queue.new
|
|
150
125
|
|
|
151
|
-
|
|
126
|
+
ts = 10.times.map {
|
|
127
|
+
Thread.new {
|
|
128
|
+
latch.pop
|
|
152
129
|
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
130
|
+
# Add a lock when using the prepared statement.
|
|
131
|
+
# Binding values, and walking over results will mutate the statement, so
|
|
132
|
+
# in order to prevent other threads from "seeing" this thread's data, we
|
|
133
|
+
# must lock when using the statement object
|
|
134
|
+
stmt_lock.synchronize do
|
|
135
|
+
stmt.execute(Thread.current.inspect).to_a
|
|
136
|
+
end
|
|
137
|
+
}
|
|
138
|
+
}
|
|
159
139
|
|
|
160
|
-
|
|
161
|
-
user 0m3.809s
|
|
162
|
-
sys 0m0.912s
|
|
163
|
-
```
|
|
140
|
+
10.times { latch << nil }
|
|
164
141
|
|
|
165
|
-
|
|
142
|
+
p ts.map(&:value)
|
|
166
143
|
|
|
167
|
-
|
|
168
|
-
bundle config build.sqlite3 --enable-system-libraries
|
|
144
|
+
stmt.close
|
|
169
145
|
```
|
|
170
146
|
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
gem install sqlite3 -- \
|
|
175
|
-
--enable-system-libraries \
|
|
176
|
-
--with-sqlite3-include=/opt/local/include \
|
|
177
|
-
--with-sqlite3-lib=/opt/local/lib
|
|
178
|
-
```
|
|
147
|
+
It is generally recommended that if applications want to share a database among
|
|
148
|
+
threads, they _only_ share the database instance object. Other objects are
|
|
149
|
+
fine to share, but may require manual locking for thread safety.
|
|
179
150
|
|
|
180
151
|
|
|
181
|
-
|
|
152
|
+
## Fork Safety
|
|
182
153
|
|
|
183
|
-
|
|
154
|
+
[Sqlite is not fork
|
|
155
|
+
safe](https://www.sqlite.org/howtocorrupt.html#_carrying_an_open_database_connection_across_a_fork_)
|
|
156
|
+
and instructs users to not carry an open writable database connection across a `fork()`. Using an inherited
|
|
157
|
+
connection in the child may corrupt your database, leak memory, or cause other undefined behavior.
|
|
184
158
|
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
This could take a while...
|
|
189
|
-
Successfully installed sqlite3-1.5.0
|
|
190
|
-
1 gem installed
|
|
159
|
+
To help protect users of this gem from accidental corruption due to this lack of fork safety, the gem will immediately close any open writable databases in the child after a fork. Discarding writable
|
|
160
|
+
connections in the child will incur a small one-time memory leak per connection, but that's
|
|
161
|
+
preferable to potentially corrupting your database.
|
|
191
162
|
|
|
192
|
-
|
|
193
|
-
user 0m3.906s
|
|
194
|
-
sys 0m0.896s
|
|
195
|
-
```
|
|
163
|
+
Whenever possible, close writable connections in the parent before forking. If absolutely necessary (and you know what you're doing), you may suppress the fork safety warnings by calling `SQLite3::ForkSafety.suppress_warnings!`.
|
|
196
164
|
|
|
197
|
-
|
|
165
|
+
See [./adr/2024-09-fork-safety.md](./adr/2024-09-fork-safety.md) for more information and context.
|
|
198
166
|
|
|
199
167
|
|
|
200
168
|
## Support
|
|
201
169
|
|
|
202
|
-
###
|
|
170
|
+
### Installation or database extensions
|
|
203
171
|
|
|
204
|
-
|
|
205
|
-
[sqlite3-ruby mailing list](http://groups.google.com/group/sqlite3-ruby) which
|
|
206
|
-
can be found here:
|
|
172
|
+
If you're having trouble with installation, please first read [`INSTALLATION.md`](./INSTALLATION.md).
|
|
207
173
|
|
|
208
|
-
|
|
174
|
+
### General help requests
|
|
209
175
|
|
|
176
|
+
You can ask for help or support:
|
|
210
177
|
|
|
211
|
-
|
|
178
|
+
* by emailing the [sqlite3-ruby mailing list](http://groups.google.com/group/sqlite3-ruby)
|
|
179
|
+
* by opening a [discussion thread](https://github.com/sparklemotion/sqlite3-ruby/discussions/categories/q-a) on Github
|
|
212
180
|
|
|
213
|
-
|
|
181
|
+
### Bug reports
|
|
214
182
|
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
## Usage
|
|
219
|
-
|
|
220
|
-
For help figuring out the SQLite3/Ruby interface, check out the SYNOPSIS as well as the RDoc. It includes examples of usage. If you have any questions that you feel should be addressed in the FAQ, please send them to [the mailing list](http://groups.google.com/group/sqlite3-ruby).
|
|
183
|
+
You can file the bug at the [github issues page](https://github.com/sparklemotion/sqlite3-ruby/issues).
|
|
221
184
|
|
|
222
185
|
|
|
223
186
|
## Contributing
|
|
@@ -229,7 +192,7 @@ See [`CONTRIBUTING.md`](./CONTRIBUTING.md).
|
|
|
229
192
|
|
|
230
193
|
This library is licensed under `BSD-3-Clause`, see [`LICENSE`](./LICENSE).
|
|
231
194
|
|
|
232
|
-
|
|
233
195
|
### Dependencies
|
|
234
196
|
|
|
235
|
-
The source code of `sqlite` is distributed in the "ruby platform" gem. This code is public domain,
|
|
197
|
+
The source code of `sqlite` is distributed in the "ruby platform" gem. This code is public domain,
|
|
198
|
+
see https://www.sqlite.org/copyright.html for details.
|
data/dependencies.yml
CHANGED
|
@@ -1,14 +1,13 @@
|
|
|
1
|
-
|
|
2
|
-
:sqlite3:
|
|
1
|
+
sqlite3:
|
|
3
2
|
# checksum verified by first checking the published sha3(256) checksum against https://sqlite.org/download.html:
|
|
3
|
+
# 025328da165109f48abccc6e7478508060804412bed2bd81d47e98ba1b72983b
|
|
4
4
|
#
|
|
5
|
-
# $ sha3sum -a 256 ports/archives/sqlite-autoconf-
|
|
6
|
-
#
|
|
5
|
+
# $ sha3sum -a 256 ports/archives/sqlite-autoconf-3530200.tar.gz
|
|
6
|
+
# 025328da165109f48abccc6e7478508060804412bed2bd81d47e98ba1b72983b ports/archives/sqlite-autoconf-3530200.tar.gz
|
|
7
7
|
#
|
|
8
|
-
# $ sha256sum ports/archives/sqlite-autoconf-
|
|
9
|
-
#
|
|
10
|
-
|
|
11
|
-
:
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
:sha256: "0333552076d2700c75352256e91c78bf5cd62491589ba0c69aed0a81868980e7"
|
|
8
|
+
# $ sha256sum ports/archives/sqlite-autoconf-3530200.tar.gz
|
|
9
|
+
# 588ad51949419a56ebe81fe56193d510c559eb94c9a57748387860b5d3069316 ports/archives/sqlite-autoconf-3530200.tar.gz
|
|
10
|
+
version: "3.53.2"
|
|
11
|
+
files:
|
|
12
|
+
- url: "https://sqlite.org/2026/sqlite-autoconf-3530200.tar.gz"
|
|
13
|
+
sha256: "588ad51949419a56ebe81fe56193d510c559eb94c9a57748387860b5d3069316"
|