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/CONTRIBUTING.md
CHANGED
|
@@ -5,6 +5,93 @@
|
|
|
5
5
|
This doc is a short introduction on how to modify and maintain the sqlite3-ruby gem.
|
|
6
6
|
|
|
7
7
|
|
|
8
|
+
## Architecture notes
|
|
9
|
+
|
|
10
|
+
### Decision record
|
|
11
|
+
|
|
12
|
+
As of 2024-09, we're starting to keep some architecture decisions in the subdirectory `/adr`, so
|
|
13
|
+
please look there for additional information.
|
|
14
|
+
|
|
15
|
+
### Garbage collection
|
|
16
|
+
|
|
17
|
+
All statements keep pointers back to their respective database connections.
|
|
18
|
+
The `@connection` instance variable on the `Statement` handle keeps the database
|
|
19
|
+
connection alive.
|
|
20
|
+
|
|
21
|
+
We use `sqlite3_close_v2` in `Database#close` since v2.1.0 which defers _actually_ closing the
|
|
22
|
+
connection and freeing the underlying memory until all open statements are closed; though the
|
|
23
|
+
`Database` object will immediately behave as though it's been fully closed. If a Database is not
|
|
24
|
+
explicitly closed, it will be closed when it is GCed.
|
|
25
|
+
|
|
26
|
+
`Statement#close` finalizes the underlying statement. If a Statement is not explicitly closed, it
|
|
27
|
+
will be closed/finalized when it is GCed.
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
## Debugging memory issues
|
|
31
|
+
|
|
32
|
+
Please install `valgrind` and `gdb` before you use the tools in this section.
|
|
33
|
+
|
|
34
|
+
Run the test suite under valgrind and [`ruby_memcheck`](https://github.com/Shopify/ruby_memcheck) to
|
|
35
|
+
look for memory leaks and other memory errors:
|
|
36
|
+
|
|
37
|
+
``` sh
|
|
38
|
+
bundle exec rake compile test:valgrind
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
If you can't install valgrind on your system, use the `sqlite3-dev` docker image, which contains
|
|
42
|
+
valgrind:
|
|
43
|
+
|
|
44
|
+
``` sh
|
|
45
|
+
# build the image
|
|
46
|
+
bundle exec rake docker:dev:build
|
|
47
|
+
|
|
48
|
+
# run the test suite in a container
|
|
49
|
+
bundle exec rake docker:dev:test
|
|
50
|
+
|
|
51
|
+
# run the test suite under valgrind in a container
|
|
52
|
+
bundle exec rake docker:dev:test:valgrind
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
Each `docker:dev:test` task builds the image first, then mounts your working copy at `/sqlite3` in
|
|
56
|
+
the container. Note that the container compiles into the mounted working copy, so please re-run
|
|
57
|
+
`rake compile` on your machine afterwards.
|
|
58
|
+
|
|
59
|
+
Run the test suite in the debugger:
|
|
60
|
+
|
|
61
|
+
``` sh
|
|
62
|
+
bundle exec rake compile test:gdb
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
You can also run the test suite with a variety of GC behaviors, which is useful to localize some
|
|
66
|
+
classes of memory bugs. Set the `SQLITE3_TEST_GC_LEVEL` environment variable (see `test/helper.rb`
|
|
67
|
+
for more info). A more stressful level finds more bugs, but makes the suite slower:
|
|
68
|
+
|
|
69
|
+
``` sh
|
|
70
|
+
# ordinary GC behavior (the default)
|
|
71
|
+
SQLITE3_TEST_GC_LEVEL=normal bundle exec rake compile test
|
|
72
|
+
|
|
73
|
+
# minor GC after each test
|
|
74
|
+
SQLITE3_TEST_GC_LEVEL=minor bundle exec rake compile test
|
|
75
|
+
|
|
76
|
+
# major GC after each test
|
|
77
|
+
SQLITE3_TEST_GC_LEVEL=major bundle exec rake compile test
|
|
78
|
+
|
|
79
|
+
# major GC after each test, and GC compaction after every 20 tests
|
|
80
|
+
SQLITE3_TEST_GC_LEVEL=compact bundle exec rake compile test
|
|
81
|
+
|
|
82
|
+
# verify references after compaction, after every 20 tests
|
|
83
|
+
# (see https://alanwu.space/post/check-compaction/)
|
|
84
|
+
SQLITE3_TEST_GC_LEVEL=verify bundle exec rake compile test
|
|
85
|
+
|
|
86
|
+
# run each test with GC "stress mode" on
|
|
87
|
+
SQLITE3_TEST_GC_LEVEL=stress bundle exec rake compile test
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
The `compact` and `verify` levels fall back to `normal` on a platform that does not support GC
|
|
91
|
+
compaction. The `stress` level makes the suite about 150 times slower, and it makes
|
|
92
|
+
timing-sensitive tests unreliable.
|
|
93
|
+
|
|
94
|
+
|
|
8
95
|
## Building gems
|
|
9
96
|
|
|
10
97
|
As a prerequisite please make sure you have `docker` correctly installed, so that you're able to cross-compile the native gems.
|
|
@@ -12,13 +99,32 @@ As a prerequisite please make sure you have `docker` correctly installed, so tha
|
|
|
12
99
|
Run `bin/build-gems` which will package gems for all supported platforms, and run some basic sanity tests on those packages using `bin/test-gem-set` and `bin/test-gem-file-contents`.
|
|
13
100
|
|
|
14
101
|
|
|
102
|
+
## Updating the version of libsqlite3
|
|
103
|
+
|
|
104
|
+
Update `/dependencies.yml` to reflect:
|
|
105
|
+
|
|
106
|
+
- the version of libsqlite3
|
|
107
|
+
- the URL from which to download
|
|
108
|
+
- the checksum of the file, which will need to be verified manually (see comments in that file)
|
|
109
|
+
|
|
110
|
+
|
|
15
111
|
## Making a release
|
|
16
112
|
|
|
17
|
-
A quick checklist:
|
|
113
|
+
A quick checklist to cutting a release of the sqlite3 gem:
|
|
114
|
+
|
|
115
|
+
Prep
|
|
116
|
+
- [ ] Make sure CI is green!
|
|
117
|
+
- [ ] Update `CHANGELOG.md` and `lib/sqlite3/version.rb`
|
|
118
|
+
- [ ] Create a git tag using a format that matches the pattern `v\d+\.\d+\.\d+`, e.g. `v1.3.13`
|
|
119
|
+
- [ ] `git push && git push --tags`
|
|
18
120
|
|
|
19
|
-
|
|
20
|
-
- [
|
|
21
|
-
- [
|
|
22
|
-
|
|
121
|
+
Automated build and release
|
|
122
|
+
- [ ] Run workflow https://github.com/sparklemotion/sqlite3-ruby/actions/workflows/release.yml
|
|
123
|
+
- [ ] Copy checksums from the push job
|
|
124
|
+
|
|
125
|
+
Manual build and release
|
|
126
|
+
- [ ] Run `bin/build-gems` and make sure it completes and all the tests pass
|
|
23
127
|
- [ ] `for g in gems/*.gem ; do gem push $g ; done`
|
|
24
|
-
|
|
128
|
+
|
|
129
|
+
Post-release
|
|
130
|
+
- [ ] Create a release at https://github.com/sparklemotion/sqlite3-ruby/releases and include sha2 checksums
|
data/{faq/faq.md → FAQ.md}
RENAMED
|
@@ -122,15 +122,17 @@ Placeholders in an SQL statement take any of the following formats:
|
|
|
122
122
|
* `?`
|
|
123
123
|
* `?_nnn_`
|
|
124
124
|
* `:_word_`
|
|
125
|
+
* `$_word_`
|
|
126
|
+
* `@_word_`
|
|
125
127
|
|
|
126
128
|
|
|
127
|
-
Where _n_ is an integer, and _word_ is an alpha-numeric identifier
|
|
128
|
-
|
|
129
|
-
identifies the index of the bind variable to replace it with.
|
|
130
|
-
is an identifier, it identifies the name of the corresponding bind
|
|
131
|
-
variable. (In the instance of the first format--a single question
|
|
132
|
-
|
|
133
|
-
|
|
129
|
+
Where _n_ is an integer, and _word_ is an alpha-numeric identifier(or number).
|
|
130
|
+
When the placeholder is associated with a number (only in case of `?_nnn_`),
|
|
131
|
+
that number identifies the index of the bind variable to replace it with.
|
|
132
|
+
When it is an identifier, it identifies the name of the corresponding bind
|
|
133
|
+
variable. (In the instance of the first format--a single question mark--the
|
|
134
|
+
placeholder is assigned a number one greater than the last index used, or 1
|
|
135
|
+
if it is the first.)
|
|
134
136
|
|
|
135
137
|
|
|
136
138
|
For example, here is a query using these placeholder formats:
|
|
@@ -207,48 +209,46 @@ Or do a `Database#prepare` to get the `Statement`, and then use either
|
|
|
207
209
|
stmt.bind_params( "value", "name" => "bob" )
|
|
208
210
|
```
|
|
209
211
|
|
|
210
|
-
## How do I discover metadata about a query?
|
|
212
|
+
## How do I discover metadata about a query result?
|
|
211
213
|
|
|
212
|
-
|
|
213
|
-
|
|
214
|
+
IMPORTANT: `Database#execute` returns an Array of Array of Strings
|
|
215
|
+
which will have no metadata about the query or the result, such
|
|
216
|
+
as column names.
|
|
214
217
|
|
|
215
218
|
|
|
216
|
-
|
|
217
|
-
property "fields" that returns an array of the column names. The row
|
|
218
|
-
will also have a property "types" that returns an array of the column
|
|
219
|
-
types:
|
|
219
|
+
There are 2 main sources of query metadata:
|
|
220
220
|
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
rows = db.execute( "select * from table" )
|
|
224
|
-
p rows[0].fields
|
|
225
|
-
p rows[0].types
|
|
226
|
-
```
|
|
221
|
+
* `Statement`
|
|
222
|
+
* `ResultSet`
|
|
227
223
|
|
|
228
224
|
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
you still need the metadata, you can use `Database#query` and ask the
|
|
232
|
-
`ResultSet` object itself:
|
|
225
|
+
You can get a `Statement` via `Database#prepare`, and you can get
|
|
226
|
+
a `ResultSet` via `Statement#execute` or `Database#query`.
|
|
233
227
|
|
|
234
228
|
|
|
235
229
|
```ruby
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
230
|
+
sql = 'select * from table'
|
|
231
|
+
|
|
232
|
+
# No metadata
|
|
233
|
+
rows = db.execute(sql)
|
|
234
|
+
rows.class # => Array, no metadata
|
|
235
|
+
rows.first.class # => Array, no metadata
|
|
236
|
+
rows.first.first.class #=> String, no metadata
|
|
237
|
+
|
|
238
|
+
# Statement has metadata
|
|
239
|
+
stmt = db.prepare(sql)
|
|
240
|
+
stmt.columns # => [ ... ]
|
|
241
|
+
stmt.types # => [ ... ]
|
|
242
|
+
|
|
243
|
+
# ResultSet has metadata
|
|
244
|
+
results = stmt.execute
|
|
245
|
+
results.columns # => [ ... ]
|
|
246
|
+
results.types # => [ ... ]
|
|
247
|
+
|
|
248
|
+
# ResultSet has metadata
|
|
249
|
+
results = db.query(sql)
|
|
250
|
+
results.columns # => [ ... ]
|
|
251
|
+
results.types # => [ ... ]
|
|
252
252
|
```
|
|
253
253
|
|
|
254
254
|
## I'd like the rows to be indexible by column name.
|
|
@@ -273,7 +273,18 @@ is unavailable on the row, although the "types" property remains.)
|
|
|
273
273
|
```
|
|
274
274
|
|
|
275
275
|
|
|
276
|
-
|
|
276
|
+
A more granular way to do this is via `ResultSet#next_hash` or
|
|
277
|
+
`ResultSet#each_hash`.
|
|
278
|
+
|
|
279
|
+
|
|
280
|
+
```ruby
|
|
281
|
+
results = db.query( "select * from table" )
|
|
282
|
+
row = results.next_hash
|
|
283
|
+
p row['column1']
|
|
284
|
+
```
|
|
285
|
+
|
|
286
|
+
|
|
287
|
+
Another way is to use Ara Howard's
|
|
277
288
|
[`ArrayFields`](http://rubyforge.org/projects/arrayfields)
|
|
278
289
|
module. Just `require "arrayfields"`, and all of your rows will be indexable
|
|
279
290
|
by column name, even though they are still arrays!
|
|
@@ -289,49 +300,6 @@ by column name, even though they are still arrays!
|
|
|
289
300
|
end
|
|
290
301
|
```
|
|
291
302
|
|
|
292
|
-
## I'd like the values from a query to be the correct types, instead of String.
|
|
293
|
-
|
|
294
|
-
You can turn on "type translation" by setting `Database#type_translation` to
|
|
295
|
-
true:
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
```ruby
|
|
299
|
-
db.type_translation = true
|
|
300
|
-
db.execute( "select * from table" ) do |row|
|
|
301
|
-
p row
|
|
302
|
-
end
|
|
303
|
-
```
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
By doing this, each return value for each row will be translated to its
|
|
307
|
-
correct type, based on its declared column type.
|
|
308
|
-
|
|
309
|
-
|
|
310
|
-
You can even declare your own translation routines, if (for example) you are
|
|
311
|
-
using an SQL type that is not handled by default:
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
```ruby
|
|
315
|
-
# assume "objects" table has the following schema:
|
|
316
|
-
# create table objects (
|
|
317
|
-
# name varchar2(20),
|
|
318
|
-
# thing object
|
|
319
|
-
# )
|
|
320
|
-
|
|
321
|
-
db.type_translation = true
|
|
322
|
-
db.translator.add_translator( "object" ) do |type, value|
|
|
323
|
-
db.decode( value )
|
|
324
|
-
end
|
|
325
|
-
|
|
326
|
-
h = { :one=>:two, "three"=>"four", 5=>6 }
|
|
327
|
-
dump = db.encode( h )
|
|
328
|
-
|
|
329
|
-
db.execute( "insert into objects values ( ?, ? )", "bob", dump )
|
|
330
|
-
|
|
331
|
-
obj = db.get_first_value( "select thing from objects where name='bob'" )
|
|
332
|
-
p obj == h
|
|
333
|
-
```
|
|
334
|
-
|
|
335
303
|
## How do I insert binary data into the database?
|
|
336
304
|
|
|
337
305
|
Use blobs. Blobs are new features of SQLite3. You have to use bind
|
data/INSTALLATION.md
ADDED
|
@@ -0,0 +1,267 @@
|
|
|
1
|
+
|
|
2
|
+
# Installation and Using SQLite3 extensions
|
|
3
|
+
|
|
4
|
+
This document will help you install the `sqlite3` ruby gem. It also contains instructions on loading database extensions and building against drop-in replacements for sqlite3.
|
|
5
|
+
|
|
6
|
+
## Installation
|
|
7
|
+
|
|
8
|
+
### Native Gems (recommended)
|
|
9
|
+
|
|
10
|
+
In v2.5.0 and later, native (precompiled) gems are available for recent Ruby versions on these platforms:
|
|
11
|
+
|
|
12
|
+
- `aarch64-linux-gnu` (requires: glibc >= 2.29)
|
|
13
|
+
- `aarch64-linux-musl`
|
|
14
|
+
- `arm-linux-gnu` (requires: glibc >= 2.29)
|
|
15
|
+
- `arm-linux-musl`
|
|
16
|
+
- `arm64-darwin`
|
|
17
|
+
- `x64-mingw-ucrt`
|
|
18
|
+
- `x86-linux-gnu` (requires: glibc >= 2.29)
|
|
19
|
+
- `x86-linux-musl`
|
|
20
|
+
- `x86_64-darwin`
|
|
21
|
+
- `x86_64-linux-gnu` (requires: glibc >= 2.29)
|
|
22
|
+
- `x86_64-linux-musl`
|
|
23
|
+
|
|
24
|
+
⚠ Musl linux users should update to Bundler >= 2.5.6 to avoid https://github.com/rubygems/rubygems/issues/7432
|
|
25
|
+
|
|
26
|
+
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.
|
|
27
|
+
|
|
28
|
+
For example, on a linux system running Ruby 3.4:
|
|
29
|
+
|
|
30
|
+
``` text
|
|
31
|
+
$ ruby -v
|
|
32
|
+
ruby 3.4.7 (2025-10-08 revision 7a5688e2a2) +PRISM [x86_64-linux]
|
|
33
|
+
|
|
34
|
+
$ time gem install sqlite3
|
|
35
|
+
Fetching sqlite3-2.8.1-x86_64-linux-gnu.gem
|
|
36
|
+
Successfully installed sqlite3-2.8.1-x86_64-linux-gnu
|
|
37
|
+
1 gem installed
|
|
38
|
+
|
|
39
|
+
real 0m1.273s
|
|
40
|
+
user 0m0.496s
|
|
41
|
+
sys 0m0.078s
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
#### Avoiding the precompiled native gem
|
|
45
|
+
|
|
46
|
+
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.
|
|
47
|
+
|
|
48
|
+
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:
|
|
49
|
+
|
|
50
|
+
- If you're not using Bundler, then run `gem install sqlite3 --platform=ruby`
|
|
51
|
+
- If you are using Bundler
|
|
52
|
+
- 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)
|
|
53
|
+
- version 2.1 or later, then you'll need to run `bundle config set force_ruby_platform true`
|
|
54
|
+
- version 2.0 or earlier, then you'll need to run `bundle config force_ruby_platform true`
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
### Compiling the source gem
|
|
58
|
+
|
|
59
|
+
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.
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
#### Packaged libsqlite3
|
|
63
|
+
|
|
64
|
+
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.
|
|
65
|
+
|
|
66
|
+
⚠ A prerequisite to build the gem with the packaged sqlite3 is that you must have `pkgconf` installed.
|
|
67
|
+
|
|
68
|
+
For example, on a linux system running Ruby 2.5:
|
|
69
|
+
|
|
70
|
+
``` text
|
|
71
|
+
$ ruby -v
|
|
72
|
+
ruby 2.5.9p229 (2021-04-05 revision 67939) [x86_64-linux]
|
|
73
|
+
|
|
74
|
+
$ time gem install sqlite3
|
|
75
|
+
Building native extensions. This could take a while...
|
|
76
|
+
Successfully installed sqlite3-1.5.0
|
|
77
|
+
1 gem installed
|
|
78
|
+
|
|
79
|
+
real 0m20.620s
|
|
80
|
+
user 0m23.361s
|
|
81
|
+
sys 0m5.839s
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
##### Controlling compilation flags for sqlite
|
|
85
|
+
|
|
86
|
+
Upstream sqlite allows for the setting of some parameters at compile time. If you're an expert and would like to set these, you may do so at gem install time in two different ways ...
|
|
87
|
+
|
|
88
|
+
**If you're installing the gem using `gem install`** then you can pass in these compile-time flags like this:
|
|
89
|
+
|
|
90
|
+
``` sh
|
|
91
|
+
gem install sqlite3 --platform=ruby -- \
|
|
92
|
+
--with-sqlite-cflags="-DSQLITE_DEFAULT_CACHE_SIZE=9999 -DSQLITE_DEFAULT_PAGE_SIZE=4444"
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
or the equivalent:
|
|
96
|
+
|
|
97
|
+
``` sh
|
|
98
|
+
CFLAGS="-DSQLITE_DEFAULT_CACHE_SIZE=9999 -DSQLITE_DEFAULT_PAGE_SIZE=4444" \
|
|
99
|
+
gem install sqlite3 --platform=ruby
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
**If you're installing the gem using `bundler`** then you should first pin the gem to the "ruby" platform gem, so that you are compiling from source:
|
|
103
|
+
|
|
104
|
+
``` ruby
|
|
105
|
+
# Gemfile
|
|
106
|
+
gem "sqlite3", force_ruby_platform: true # requires bundler >= 2.3.18
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
and then set up a bundler config parameter for `build.sqlite3`:
|
|
110
|
+
|
|
111
|
+
``` sh
|
|
112
|
+
bundle config set build.sqlite3 \
|
|
113
|
+
"--with-sqlite-cflags='-DSQLITE_DEFAULT_CACHE_SIZE=9999 -DSQLITE_DEFAULT_PAGE_SIZE=4444'"
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
NOTE the use of single quotes within the double-quoted string to ensure the space between compiler flags is interpreted correctly. The contents of your `.bundle/config` file should look like:
|
|
117
|
+
|
|
118
|
+
``` yaml
|
|
119
|
+
---
|
|
120
|
+
BUNDLE_BUILD__SQLITE3: "--with-sqlite-cflags='-DSQLITE_DEFAULT_CACHE_SIZE=9999 -DSQLITE_DEFAULT_PAGE_SIZE=4444'"
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
|
|
124
|
+
#### System libsqlite3
|
|
125
|
+
|
|
126
|
+
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.
|
|
127
|
+
|
|
128
|
+
PLEASE NOTE:
|
|
129
|
+
|
|
130
|
+
- you must avoid installing a precompiled native gem (see [previous section](#avoiding-the-precompiled-native-gem))
|
|
131
|
+
- only versions of libsqlite3 `>= 3.5.0` are supported,
|
|
132
|
+
- and some library features may depend on how your libsqlite3 was compiled.
|
|
133
|
+
|
|
134
|
+
For example, on a linux system running Ruby 2.5:
|
|
135
|
+
|
|
136
|
+
``` text
|
|
137
|
+
$ time gem install sqlite3 -- --enable-system-libraries
|
|
138
|
+
Building native extensions with: '--enable-system-libraries'
|
|
139
|
+
This could take a while...
|
|
140
|
+
Successfully installed sqlite3-1.5.0
|
|
141
|
+
1 gem installed
|
|
142
|
+
|
|
143
|
+
real 0m4.234s
|
|
144
|
+
user 0m3.809s
|
|
145
|
+
sys 0m0.912s
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
If you're using bundler, you can opt into system libraries like this:
|
|
149
|
+
|
|
150
|
+
``` sh
|
|
151
|
+
bundle config build.sqlite3 --enable-system-libraries
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
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.
|
|
155
|
+
|
|
156
|
+
``` sh
|
|
157
|
+
gem install sqlite3 -- \
|
|
158
|
+
--enable-system-libraries \
|
|
159
|
+
--with-sqlite3-include=/opt/local/include \
|
|
160
|
+
--with-sqlite3-lib=/opt/local/lib
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
|
|
164
|
+
#### System libsqlcipher
|
|
165
|
+
|
|
166
|
+
If you'd like to link against a system-installed libsqlcipher, you may do so by using the `--with-sqlcipher` flag:
|
|
167
|
+
|
|
168
|
+
``` text
|
|
169
|
+
$ time gem install sqlite3 -- --with-sqlcipher
|
|
170
|
+
Building native extensions with: '--with-sqlcipher'
|
|
171
|
+
This could take a while...
|
|
172
|
+
Successfully installed sqlite3-1.5.0
|
|
173
|
+
1 gem installed
|
|
174
|
+
|
|
175
|
+
real 0m4.772s
|
|
176
|
+
user 0m3.906s
|
|
177
|
+
sys 0m0.896s
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
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.
|
|
181
|
+
|
|
182
|
+
|
|
183
|
+
## Using SQLite3 extensions
|
|
184
|
+
|
|
185
|
+
### How do I load a sqlite extension?
|
|
186
|
+
|
|
187
|
+
Some add-ons are available to sqlite as "extensions". The instructions that upstream sqlite provides at https://www.sqlite.org/loadext.html are the canonical source of advice, but here's a brief example showing how you can do this with the `sqlite3` ruby gem.
|
|
188
|
+
|
|
189
|
+
In this example, I'll be loading the ["spellfix" extension](https://www.sqlite.org/spellfix1.html):
|
|
190
|
+
|
|
191
|
+
``` text
|
|
192
|
+
# download spellfix.c from somewherehttp://www.sqlite.org/src/finfo?name=ext/misc/spellfix.c
|
|
193
|
+
$ wget https://raw.githubusercontent.com/sqlite/sqlite/master/ext/misc/spellfix.c
|
|
194
|
+
spellfix.c 100%[=================================================>] 100.89K --.-KB/s in 0.09s
|
|
195
|
+
|
|
196
|
+
# follow instructions at https://www.sqlite.org/loadext.html
|
|
197
|
+
# (you will need sqlite3 development packages for this)
|
|
198
|
+
$ gcc -g -fPIC -shared spellfix.c -o spellfix.o
|
|
199
|
+
|
|
200
|
+
$ ls -lt
|
|
201
|
+
total 192
|
|
202
|
+
-rwxrwxr-x 1 flavorjones flavorjones 87984 2023-05-24 10:44 spellfix.o
|
|
203
|
+
-rw-rw-r-- 1 flavorjones flavorjones 103310 2023-05-24 10:43 spellfix.c
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
Then, in your application, use that `spellfix.o` file like this:
|
|
207
|
+
|
|
208
|
+
``` ruby
|
|
209
|
+
require "sqlite3"
|
|
210
|
+
|
|
211
|
+
db = SQLite3::Database.new(':memory:')
|
|
212
|
+
db.enable_load_extension(true)
|
|
213
|
+
db.load_extension("/path/to/sqlite/spellfix.o")
|
|
214
|
+
db.execute("CREATE VIRTUAL TABLE demo USING spellfix1;")
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
### How do I use my own sqlite3 shared library?
|
|
218
|
+
|
|
219
|
+
Some folks have strong opinions about what features they want compiled into sqlite3; or may be using a package like SQLite Encryption Extension ("SEE"). This section will explain how to get your Ruby application to load that specific shared library.
|
|
220
|
+
|
|
221
|
+
If you've installed your alternative as an autotools-style installation, the directory structure will look like this:
|
|
222
|
+
|
|
223
|
+
```
|
|
224
|
+
/opt/sqlite3
|
|
225
|
+
├── bin
|
|
226
|
+
│ └── sqlite3
|
|
227
|
+
├── include
|
|
228
|
+
│ ├── sqlite3.h
|
|
229
|
+
│ └── sqlite3ext.h
|
|
230
|
+
├── lib
|
|
231
|
+
│ ├── libsqlite3.a
|
|
232
|
+
│ ├── libsqlite3.la
|
|
233
|
+
│ ├── libsqlite3.so -> libsqlite3.so.0.8.6
|
|
234
|
+
│ ├── libsqlite3.so.0 -> libsqlite3.so.0.8.6
|
|
235
|
+
│ ├── libsqlite3.so.0.8.6
|
|
236
|
+
│ └── pkgconfig
|
|
237
|
+
│ └── sqlite3.pc
|
|
238
|
+
└── share
|
|
239
|
+
└── man
|
|
240
|
+
└── man1
|
|
241
|
+
└── sqlite3.1
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
You can build this gem against that library like this:
|
|
245
|
+
|
|
246
|
+
```
|
|
247
|
+
gem install sqlite3 --platform=ruby -- \
|
|
248
|
+
--enable-system-libraries \
|
|
249
|
+
--with-opt-dir=/opt/sqlite
|
|
250
|
+
```
|
|
251
|
+
|
|
252
|
+
Explanation:
|
|
253
|
+
|
|
254
|
+
- use `--platform=ruby` to avoid the precompiled native gems (see the README)
|
|
255
|
+
- the `--` separates arguments passed to "gem install" from arguments passed to the C extension builder
|
|
256
|
+
- use `--enable-system-libraries` to avoid the vendored sqlite3 source
|
|
257
|
+
- use `--with-opt-dir=/path/to/installation` to point the build process at the desired header files and shared object files
|
|
258
|
+
|
|
259
|
+
Alternatively, if you've simply downloaded an "amalgamation" and so your compiled library and header files are in arbitrary locations, try this more detailed command:
|
|
260
|
+
|
|
261
|
+
```
|
|
262
|
+
gem install sqlite3 --platform=ruby -- \
|
|
263
|
+
--enable-system-libraries \
|
|
264
|
+
--with-opt-include=/path/to/include \
|
|
265
|
+
--with-opt-lib=/path/to/lib
|
|
266
|
+
```
|
|
267
|
+
|
data/LICENSE
CHANGED
|
@@ -1,27 +1,23 @@
|
|
|
1
|
-
Copyright (c) 2004, Jamis Buck
|
|
2
|
-
All rights reserved.
|
|
1
|
+
Copyright (c) 2004-2024, Jamis Buck, Luis Lavena, Aaron Patterson, Mike Dalessio, et al.
|
|
3
2
|
|
|
4
|
-
Redistribution and use in source and binary forms, with or without
|
|
5
|
-
|
|
3
|
+
Redistribution and use in source and binary forms, with or without modification, are permitted
|
|
4
|
+
provided that the following conditions are met:
|
|
6
5
|
|
|
7
|
-
|
|
8
|
-
|
|
6
|
+
1. Redistributions of source code must retain the above copyright notice, this list of conditions
|
|
7
|
+
and the following disclaimer.
|
|
9
8
|
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
9
|
+
2. Redistributions in binary form must reproduce the above copyright notice, this list of
|
|
10
|
+
conditions and the following disclaimer in the documentation and/or other materials provided with
|
|
11
|
+
the distribution.
|
|
13
12
|
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
permission.
|
|
13
|
+
3. Neither the name of the copyright holder nor the names of its contributors may be used to
|
|
14
|
+
endorse or promote products derived from this software without specific prior written permission.
|
|
17
15
|
|
|
18
|
-
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
|
|
27
|
-
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
16
|
+
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR
|
|
17
|
+
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
|
|
18
|
+
FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
|
|
19
|
+
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
20
|
+
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
|
|
21
|
+
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
|
|
22
|
+
IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
|
|
23
|
+
THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|