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.
Files changed (62) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +594 -1
  3. data/CONTRIBUTING.md +112 -6
  4. data/{faq/faq.md → FAQ.md} +52 -84
  5. data/INSTALLATION.md +267 -0
  6. data/LICENSE +18 -22
  7. data/README.md +87 -124
  8. data/dependencies.yml +10 -11
  9. data/ext/sqlite3/aggregator.c +153 -147
  10. data/ext/sqlite3/aggregator.h +6 -4
  11. data/ext/sqlite3/backup.c +86 -64
  12. data/ext/sqlite3/backup.h +2 -2
  13. data/ext/sqlite3/database.c +744 -484
  14. data/ext/sqlite3/database.h +23 -4
  15. data/ext/sqlite3/exception.c +116 -92
  16. data/ext/sqlite3/exception.h +5 -1
  17. data/ext/sqlite3/extconf.rb +68 -33
  18. data/ext/sqlite3/sqlite3.c +177 -115
  19. data/ext/sqlite3/sqlite3_ruby.h +2 -2
  20. data/ext/sqlite3/statement.c +590 -293
  21. data/ext/sqlite3/statement.h +4 -3
  22. data/ext/sqlite3/timespec.h +20 -0
  23. data/lib/sqlite3/constants.rb +195 -47
  24. data/lib/sqlite3/database.rb +252 -195
  25. data/lib/sqlite3/errors.rb +54 -1
  26. data/lib/sqlite3/fork_safety.rb +66 -0
  27. data/lib/sqlite3/pragmas.rb +196 -143
  28. data/lib/sqlite3/resultset.rb +14 -105
  29. data/lib/sqlite3/statement.rb +58 -13
  30. data/lib/sqlite3/value.rb +17 -20
  31. data/lib/sqlite3/version.rb +2 -21
  32. data/lib/sqlite3/version_info.rb +17 -0
  33. data/lib/sqlite3.rb +8 -4
  34. data/ports/archives/sqlite-autoconf-3530200.tar.gz +0 -0
  35. metadata +16 -108
  36. data/API_CHANGES.md +0 -49
  37. data/ChangeLog.cvs +0 -88
  38. data/Gemfile +0 -3
  39. data/LICENSE-DEPENDENCIES +0 -20
  40. data/faq/faq.rb +0 -145
  41. data/faq/faq.yml +0 -426
  42. data/lib/sqlite3/translator.rb +0 -118
  43. data/ports/archives/sqlite-autoconf-3400000.tar.gz +0 -0
  44. data/test/helper.rb +0 -27
  45. data/test/test_backup.rb +0 -33
  46. data/test/test_collation.rb +0 -82
  47. data/test/test_database.rb +0 -545
  48. data/test/test_database_flags.rb +0 -95
  49. data/test/test_database_readonly.rb +0 -36
  50. data/test/test_database_readwrite.rb +0 -41
  51. data/test/test_deprecated.rb +0 -44
  52. data/test/test_encoding.rb +0 -155
  53. data/test/test_integration.rb +0 -507
  54. data/test/test_integration_aggregate.rb +0 -336
  55. data/test/test_integration_open_close.rb +0 -30
  56. data/test/test_integration_pending.rb +0 -115
  57. data/test/test_integration_resultset.rb +0 -142
  58. data/test/test_integration_statement.rb +0 -194
  59. data/test/test_result_set.rb +0 -37
  60. data/test/test_sqlite3.rb +0 -30
  61. data/test/test_statement.rb +0 -263
  62. 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: http://www.rubydoc.info/gems/sqlite3
12
+ * Documentation: https://sparklemotion.github.io/sqlite3-ruby/
7
13
 
8
- [![Unit tests](https://github.com/sparklemotion/sqlite3-ruby/actions/workflows/sqlite3-ruby.yml/badge.svg)](https://github.com/sparklemotion/sqlite3-ruby/actions/workflows/sqlite3-ruby.yml)
9
- [![Native packages](https://github.com/sparklemotion/sqlite3-ruby/actions/workflows/gem-install.yml/badge.svg)](https://github.com/sparklemotion/sqlite3-ruby/actions/workflows/gem-install.yml)
14
+ [![Test suite](https://github.com/sparklemotion/sqlite3-ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/sparklemotion/sqlite3-ruby/actions/workflows/ci.yml)
10
15
 
11
16
 
12
- ## Description
17
+ ## Quick start
13
18
 
14
- This library allows Ruby programs to use the SQLite3 database engine (http://www.sqlite.org).
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
- Note that this module is only compatible with SQLite 3.6.16 or newer.
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
- ## Installation
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
- #### Packaged libsqlite3
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
- By default, as of v1.5.0 of this library, the latest available version of libsqlite3 is packaged with the gem and will be compiled and used automatically. This takes a bit longer than the native gem, but will provide a modern, well-supported version of libsqlite3.
90
+ ```ruby
91
+ require 'sqlite3'
123
92
 
124
- For example, on a linux system running Ruby 2.5:
93
+ db = SQLite3::Database.new ":memory:"
125
94
 
126
- ``` text
127
- $ ruby -v
128
- ruby 2.5.9p229 (2021-04-05 revision 67939) [x86_64-linux]
95
+ latch = Queue.new
129
96
 
130
- $ time gem install sqlite3
131
- Building native extensions. This could take a while...
132
- Successfully installed sqlite3-1.5.0
133
- 1 gem installed
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
- real 0m20.620s
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
- #### System libsqlite3
114
+ Lets rewrite the above example but use a prepared statement and safely share
115
+ the prepared statement among threads:
142
116
 
143
- If you would prefer to build the sqlite3-ruby gem against your system libsqlite3, which requires that you install libsqlite3 and its development files yourself, you may do so by using the `--enable-system-libraries` flag at gem install time.
117
+ ```ruby
118
+ db = SQLite3::Database.new ":memory:"
144
119
 
145
- PLEASE NOTE:
120
+ # Prepare a statement
121
+ stmt = db.prepare "SELECT :inspect"
122
+ stmt_lock = Mutex.new
146
123
 
147
- - you must avoid installing a precompiled native gem (see [previous section](#avoiding-the-precompiled-native-gem))
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
- For example, on a linux system running Ruby 2.5:
126
+ ts = 10.times.map {
127
+ Thread.new {
128
+ latch.pop
152
129
 
153
- ``` text
154
- $ time gem install sqlite3 -- --enable-system-libraries
155
- Building native extensions with: '--enable-system-libraries'
156
- This could take a while...
157
- Successfully installed sqlite3-1.5.0
158
- 1 gem installed
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
- real 0m4.234s
161
- user 0m3.809s
162
- sys 0m0.912s
163
- ```
140
+ 10.times { latch << nil }
164
141
 
165
- If you're using bundler, you can opt into system libraries like this:
142
+ p ts.map(&:value)
166
143
 
167
- ``` sh
168
- bundle config build.sqlite3 --enable-system-libraries
144
+ stmt.close
169
145
  ```
170
146
 
171
- If you have sqlite3 installed in a non-standard location, you may need to specify the location of the include and lib files by using `--with-sqlite-include` and `--with-sqlite-lib` options (or a `--with-sqlite-dir` option, see [MakeMakefile#dir_config](https://ruby-doc.org/stdlib-3.1.1/libdoc/mkmf/rdoc/MakeMakefile.html#method-i-dir_config)). If you have pkg-config installed and configured properly, this may not be necessary.
172
-
173
- ``` sh
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
- #### System libsqlcipher
152
+ ## Fork Safety
182
153
 
183
- If you'd like to link against a system-installed libsqlcipher, you may do so by using the `--with-sqlcipher` flag:
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
- ``` text
186
- $ time gem install sqlite3 -- --with-sqlcipher
187
- Building native extensions with: '--with-sqlcipher'
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
- real 0m4.772s
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
- If you have sqlcipher installed in a non-standard location, you may need to specify the location of the include and lib files by using `--with-sqlite-include` and `--with-sqlite-lib` options (or a `--with-sqlite-dir` option, see [MakeMakefile#dir_config](https://ruby-doc.org/stdlib-3.1.1/libdoc/mkmf/rdoc/MakeMakefile.html#method-i-dir_config)). If you have pkg-config installed and configured properly, this may not be necessary.
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
- ### Something has gone wrong! Where do I get help?
170
+ ### Installation or database extensions
203
171
 
204
- You can ask for help or support from the
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
- > http://groups.google.com/group/sqlite3-ruby
174
+ ### General help requests
209
175
 
176
+ You can ask for help or support:
210
177
 
211
- ### I've found a bug! How do I report it?
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
- After contacting the mailing list, you've found that you've uncovered a bug. You can file the bug at the [github issues page](https://github.com/sparklemotion/sqlite3-ruby/issues) which can be found here:
181
+ ### Bug reports
214
182
 
215
- > https://github.com/sparklemotion/sqlite3-ruby/issues
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, see [`LICENSE-DEPENDENCIES`](./LICENSE-DEPENDENCIES) for details.
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
- # TODO: stop using symbols here once we no longer support Ruby 2.7 and can rely on symbolize_names
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-3400000.tar.gz
6
- # 7ee8f02b21edb4489df5082b5cf5b7ef47bcebcdb0e209bf14240db69633c878 ports/archives/sqlite-autoconf-3400000.tar.gz
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-3400000.tar.gz
9
- # 0333552076d2700c75352256e91c78bf5cd62491589ba0c69aed0a81868980e7 ports/archives/sqlite-autoconf-3400000.tar.gz
10
- #
11
- :version: "3.40.0"
12
- :files:
13
- - :url: "https://sqlite.org/2022/sqlite-autoconf-3400000.tar.gz"
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"