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/lib/sqlite3/database.rb
CHANGED
|
@@ -1,14 +1,17 @@
|
|
|
1
|
-
|
|
2
|
-
require 'sqlite3/errors'
|
|
3
|
-
require 'sqlite3/pragmas'
|
|
4
|
-
require 'sqlite3/statement'
|
|
5
|
-
require 'sqlite3/translator'
|
|
6
|
-
require 'sqlite3/value'
|
|
1
|
+
# frozen_string_literal: true
|
|
7
2
|
|
|
8
|
-
|
|
3
|
+
require "sqlite3/constants"
|
|
4
|
+
require "sqlite3/errors"
|
|
5
|
+
require "sqlite3/pragmas"
|
|
6
|
+
require "sqlite3/statement"
|
|
7
|
+
require "sqlite3/value"
|
|
8
|
+
require "sqlite3/fork_safety"
|
|
9
9
|
|
|
10
|
-
|
|
11
|
-
#
|
|
10
|
+
module SQLite3
|
|
11
|
+
# == Overview
|
|
12
|
+
#
|
|
13
|
+
# The Database class encapsulates a single connection to a SQLite3 database. Here's a
|
|
14
|
+
# straightforward example of usage:
|
|
12
15
|
#
|
|
13
16
|
# require 'sqlite3'
|
|
14
17
|
#
|
|
@@ -18,50 +21,124 @@ module SQLite3
|
|
|
18
21
|
# end
|
|
19
22
|
# end
|
|
20
23
|
#
|
|
21
|
-
# It wraps the lower-level methods
|
|
22
|
-
#
|
|
23
|
-
# methods.
|
|
24
|
+
# It wraps the lower-level methods provided by the selected driver, and includes the Pragmas
|
|
25
|
+
# module for access to various pragma convenience methods.
|
|
24
26
|
#
|
|
25
|
-
# The Database class provides type translation services as well, by which
|
|
26
|
-
#
|
|
27
|
-
#
|
|
28
|
-
# for their tables). This translation only occurs when querying data from
|
|
27
|
+
# The Database class provides type translation services as well, by which the SQLite3 data types
|
|
28
|
+
# (which are all represented as strings) may be converted into their corresponding types (as
|
|
29
|
+
# defined in the schemas for their tables). This translation only occurs when querying data from
|
|
29
30
|
# the database--insertions and updates are all still typeless.
|
|
30
31
|
#
|
|
31
|
-
# Furthermore, the Database class has been designed to work well with the
|
|
32
|
-
#
|
|
33
|
-
#
|
|
34
|
-
#
|
|
32
|
+
# Furthermore, the Database class has been designed to work well with the ArrayFields module from
|
|
33
|
+
# Ara Howard. If you require the ArrayFields module before performing a query, and if you have not
|
|
34
|
+
# enabled results as hashes, then the results will all be indexible by field name.
|
|
35
|
+
#
|
|
36
|
+
# == Thread safety
|
|
37
|
+
#
|
|
38
|
+
# When SQLite3.threadsafe? returns true, it is safe to share instances of the database class
|
|
39
|
+
# among threads without adding specific locking. Other object instances may require applications
|
|
40
|
+
# to provide their own locks if they are to be shared among threads. Please see the README.md for
|
|
41
|
+
# more information.
|
|
42
|
+
#
|
|
43
|
+
# == SQLite Extensions
|
|
44
|
+
#
|
|
45
|
+
# SQLite3::Database supports the universe of {sqlite
|
|
46
|
+
# extensions}[https://www.sqlite.org/loadext.html]. It's possible to load an extension into an
|
|
47
|
+
# existing Database object using the #load_extension method and passing a filesystem path:
|
|
48
|
+
#
|
|
49
|
+
# db = SQLite3::Database.new(":memory:")
|
|
50
|
+
# db.enable_load_extension(true)
|
|
51
|
+
# db.load_extension("/path/to/extension")
|
|
52
|
+
#
|
|
53
|
+
# As of v2.4.0, it's also possible to pass an object that responds to +#to_path+. This
|
|
54
|
+
# documentation will refer to the supported interface as +_ExtensionSpecifier+, which can be
|
|
55
|
+
# expressed in RBS syntax as:
|
|
56
|
+
#
|
|
57
|
+
# interface _ExtensionSpecifier
|
|
58
|
+
# def to_path: () → String
|
|
59
|
+
# end
|
|
60
|
+
#
|
|
61
|
+
# So, for example, if you are using the {sqlean gem}[https://github.com/flavorjones/sqlean-ruby]
|
|
62
|
+
# which provides modules that implement this interface, you can pass the module directly:
|
|
63
|
+
#
|
|
64
|
+
# db = SQLite3::Database.new(":memory:")
|
|
65
|
+
# db.enable_load_extension(true)
|
|
66
|
+
# db.load_extension(SQLean::Crypto)
|
|
67
|
+
#
|
|
68
|
+
# It's also possible in v2.4.0+ to load extensions via the SQLite3::Database constructor by using
|
|
69
|
+
# the +extensions:+ keyword argument to pass an array of String paths or extension specifiers:
|
|
70
|
+
#
|
|
71
|
+
# db = SQLite3::Database.new(":memory:", extensions: ["/path/to/extension", SQLean::Crypto])
|
|
72
|
+
#
|
|
73
|
+
# Note that when loading extensions via the constructor, there is no need to call
|
|
74
|
+
# #enable_load_extension; however it is still necessary to call #enable_load_extensions before any
|
|
75
|
+
# subsequently invocations of #load_extension on the initialized Database object.
|
|
76
|
+
#
|
|
77
|
+
# You can load extensions in a Rails application by using the +extensions:+ configuration option:
|
|
78
|
+
#
|
|
79
|
+
# # config/database.yml
|
|
80
|
+
# development:
|
|
81
|
+
# adapter: sqlite3
|
|
82
|
+
# extensions:
|
|
83
|
+
# - .sqlpkg/nalgeon/crypto/crypto.so # a filesystem path
|
|
84
|
+
# - <%= SQLean::UUID.to_path %> # or ruby code returning a path
|
|
85
|
+
# - SQLean::Crypto # Rails 8.1+ accepts the name of a constant that responds to `to_path`
|
|
86
|
+
#
|
|
35
87
|
class Database
|
|
36
88
|
attr_reader :collations
|
|
37
89
|
|
|
38
90
|
include Pragmas
|
|
39
91
|
|
|
40
92
|
class << self
|
|
93
|
+
# Without block works exactly as new.
|
|
94
|
+
# With block, like new closes the database at the end, but unlike new
|
|
95
|
+
# returns the result of the block instead of the database instance.
|
|
96
|
+
def open(*args)
|
|
97
|
+
database = new(*args)
|
|
41
98
|
|
|
42
|
-
|
|
99
|
+
if block_given?
|
|
100
|
+
begin
|
|
101
|
+
yield database
|
|
102
|
+
ensure
|
|
103
|
+
database.close
|
|
104
|
+
end
|
|
105
|
+
else
|
|
106
|
+
database
|
|
107
|
+
end
|
|
108
|
+
end
|
|
43
109
|
|
|
44
110
|
# Quotes the given string, making it safe to use in an SQL statement.
|
|
45
111
|
# It replaces all instances of the single-quote character with two
|
|
46
112
|
# single-quote characters. The modified string is returned.
|
|
47
|
-
def quote(
|
|
48
|
-
string.gsub(
|
|
113
|
+
def quote(string)
|
|
114
|
+
string.gsub("'", "''")
|
|
49
115
|
end
|
|
50
|
-
|
|
51
116
|
end
|
|
52
117
|
|
|
53
118
|
# A boolean that indicates whether rows in result sets should be returned
|
|
54
119
|
# as hashes or not. By default, rows are returned as arrays.
|
|
55
120
|
attr_accessor :results_as_hash
|
|
56
121
|
|
|
57
|
-
# call-seq:
|
|
122
|
+
# call-seq:
|
|
123
|
+
# SQLite3::Database.new(file, options = {})
|
|
58
124
|
#
|
|
59
|
-
# Create a new Database object that opens the given file.
|
|
60
|
-
#
|
|
125
|
+
# Create a new Database object that opens the given file.
|
|
126
|
+
#
|
|
127
|
+
# Supported permissions +options+:
|
|
128
|
+
# - the default mode is <tt>READWRITE | CREATE</tt>
|
|
129
|
+
# - +readonly:+ boolean (default false), true to set the mode to +READONLY+
|
|
130
|
+
# - +readwrite:+ boolean (default false), true to set the mode to +READWRITE+
|
|
131
|
+
# - +flags:+ set the mode to a combination of SQLite3::Constants::Open flags.
|
|
132
|
+
#
|
|
133
|
+
# Supported encoding +options+:
|
|
134
|
+
# - +utf16:+ +boolish+ (default false), is the filename's encoding UTF-16 (only needed if the filename encoding is not UTF_16LE or BE)
|
|
135
|
+
#
|
|
136
|
+
# Other supported +options+:
|
|
137
|
+
# - +strict:+ +boolish+ (default false), disallow the use of double-quoted string literals (see https://www.sqlite.org/quirks.html#double_quoted_string_literals_are_accepted)
|
|
138
|
+
# - +results_as_hash:+ +boolish+ (default false), return rows as hashes instead of arrays
|
|
139
|
+
# - +default_transaction_mode:+ one of +:deferred+ (default), +:immediate+, or +:exclusive+. If a mode is not specified in a call to #transaction, this will be the default transaction mode.
|
|
140
|
+
# - +extensions:+ <tt>Array[String | _ExtensionSpecifier]</tt> SQLite extensions to load into the database. See Database@SQLite+Extensions for more information.
|
|
61
141
|
#
|
|
62
|
-
# By default, the new database will return result rows as arrays
|
|
63
|
-
# (#results_as_hash) and has type translation disabled (#type_translation=).
|
|
64
|
-
|
|
65
142
|
def initialize file, options = {}, zvfs = nil
|
|
66
143
|
mode = Constants::Open::READWRITE | Constants::Open::CREATE
|
|
67
144
|
|
|
@@ -94,16 +171,16 @@ module SQLite3
|
|
|
94
171
|
end
|
|
95
172
|
end
|
|
96
173
|
|
|
97
|
-
@
|
|
98
|
-
@
|
|
99
|
-
@
|
|
100
|
-
@
|
|
101
|
-
@
|
|
102
|
-
@
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
174
|
+
@progress_handler = nil
|
|
175
|
+
@collations = {}
|
|
176
|
+
@functions = []
|
|
177
|
+
@results_as_hash = options[:results_as_hash]
|
|
178
|
+
@readonly = mode & Constants::Open::READONLY != 0
|
|
179
|
+
@default_transaction_mode = options[:default_transaction_mode] || :deferred
|
|
180
|
+
|
|
181
|
+
initialize_extensions(options[:extensions])
|
|
182
|
+
|
|
183
|
+
ForkSafety.track(self)
|
|
107
184
|
|
|
108
185
|
if block_given?
|
|
109
186
|
begin
|
|
@@ -114,32 +191,18 @@ module SQLite3
|
|
|
114
191
|
end
|
|
115
192
|
end
|
|
116
193
|
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
#
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
eowarn
|
|
123
|
-
@type_translator = make_type_translator value
|
|
124
|
-
@type_translation = value
|
|
125
|
-
end
|
|
126
|
-
attr_reader :type_translation # :nodoc:
|
|
127
|
-
|
|
128
|
-
# Return the type translator employed by this database instance. Each
|
|
129
|
-
# database instance has its own type translator; this allows for different
|
|
130
|
-
# type handlers to be installed in each instance without affecting other
|
|
131
|
-
# instances. Furthermore, the translators are instantiated lazily, so that
|
|
132
|
-
# if a database does not use type translation, it will not be burdened by
|
|
133
|
-
# the overhead of a useless type translator. (See the Translator class.)
|
|
134
|
-
def translator
|
|
135
|
-
@translator ||= Translator.new
|
|
194
|
+
# call-seq: db.encoding
|
|
195
|
+
#
|
|
196
|
+
# Fetch the encoding set on this database
|
|
197
|
+
def encoding
|
|
198
|
+
Encoding.find super
|
|
136
199
|
end
|
|
137
200
|
|
|
138
201
|
# Installs (or removes) a block that will be invoked for every access
|
|
139
202
|
# to the database. If the block returns 0 (or +nil+), the statement
|
|
140
203
|
# is allowed to proceed. Returning 1 causes an authorization error to
|
|
141
204
|
# occur, and returning 2 causes the access to be silently denied.
|
|
142
|
-
def authorizer(
|
|
205
|
+
def authorizer(&block)
|
|
143
206
|
self.authorizer = block
|
|
144
207
|
end
|
|
145
208
|
|
|
@@ -149,7 +212,7 @@ in version 2.0.0.
|
|
|
149
212
|
# The Statement can then be executed using Statement#execute.
|
|
150
213
|
#
|
|
151
214
|
def prepare sql
|
|
152
|
-
stmt = SQLite3::Statement.new(
|
|
215
|
+
stmt = SQLite3::Statement.new(self, sql)
|
|
153
216
|
return stmt unless block_given?
|
|
154
217
|
|
|
155
218
|
begin
|
|
@@ -162,7 +225,7 @@ in version 2.0.0.
|
|
|
162
225
|
# Returns the filename for the database named +db_name+. +db_name+ defaults
|
|
163
226
|
# to "main". Main return `nil` or an empty string if the database is
|
|
164
227
|
# temporary or in-memory.
|
|
165
|
-
def filename db_name =
|
|
228
|
+
def filename db_name = "main"
|
|
166
229
|
db_filename db_name
|
|
167
230
|
end
|
|
168
231
|
|
|
@@ -180,31 +243,17 @@ in version 2.0.0.
|
|
|
180
243
|
#
|
|
181
244
|
# See also #execute2, #query, and #execute_batch for additional ways of
|
|
182
245
|
# executing statements.
|
|
183
|
-
def execute sql, bind_vars = [],
|
|
184
|
-
|
|
185
|
-
if args.empty?
|
|
186
|
-
bind_vars = []
|
|
187
|
-
else
|
|
188
|
-
bind_vars = [bind_vars] + args
|
|
189
|
-
end
|
|
190
|
-
|
|
191
|
-
warn(<<-eowarn) if $VERBOSE
|
|
192
|
-
#{caller[0]} is calling SQLite3::Database#execute with nil or multiple bind params
|
|
193
|
-
without using an array. Please switch to passing bind parameters as an array.
|
|
194
|
-
Support for bind parameters as *args will be removed in 2.0.0.
|
|
195
|
-
eowarn
|
|
196
|
-
end
|
|
197
|
-
|
|
198
|
-
prepare( sql ) do |stmt|
|
|
246
|
+
def execute sql, bind_vars = [], &block
|
|
247
|
+
prepare(sql) do |stmt|
|
|
199
248
|
stmt.bind_params(bind_vars)
|
|
200
|
-
stmt
|
|
249
|
+
stmt = build_result_set stmt
|
|
201
250
|
|
|
202
|
-
if
|
|
251
|
+
if block
|
|
203
252
|
stmt.each do |row|
|
|
204
253
|
yield row
|
|
205
254
|
end
|
|
206
255
|
else
|
|
207
|
-
stmt.to_a
|
|
256
|
+
stmt.to_a.freeze
|
|
208
257
|
end
|
|
209
258
|
end
|
|
210
259
|
end
|
|
@@ -219,15 +268,16 @@ Support for bind parameters as *args will be removed in 2.0.0.
|
|
|
219
268
|
#
|
|
220
269
|
# See also #execute, #query, and #execute_batch for additional ways of
|
|
221
270
|
# executing statements.
|
|
222
|
-
def execute2(
|
|
223
|
-
prepare(
|
|
224
|
-
result = stmt.execute(
|
|
271
|
+
def execute2(sql, *bind_vars)
|
|
272
|
+
prepare(sql) do |stmt|
|
|
273
|
+
result = stmt.execute(*bind_vars)
|
|
225
274
|
if block_given?
|
|
226
275
|
yield stmt.columns
|
|
227
276
|
result.each { |row| yield row }
|
|
228
277
|
else
|
|
229
|
-
return result.
|
|
230
|
-
|
|
278
|
+
return result.each_with_object([stmt.columns]) { |row, arr|
|
|
279
|
+
arr << row
|
|
280
|
+
}
|
|
231
281
|
end
|
|
232
282
|
end
|
|
233
283
|
end
|
|
@@ -238,53 +288,28 @@ Support for bind parameters as *args will be removed in 2.0.0.
|
|
|
238
288
|
# in turn. The same bind parameters, if given, will be applied to each
|
|
239
289
|
# statement.
|
|
240
290
|
#
|
|
241
|
-
# This always returns
|
|
242
|
-
# rows.
|
|
291
|
+
# This always returns the result of the last statement.
|
|
243
292
|
#
|
|
244
293
|
# See also #execute_batch2 for additional ways of
|
|
245
294
|
# executing statements.
|
|
246
|
-
def execute_batch(
|
|
247
|
-
# FIXME: remove this stuff later
|
|
248
|
-
unless [Array, Hash].include?(bind_vars.class)
|
|
249
|
-
bind_vars = [bind_vars]
|
|
250
|
-
warn(<<-eowarn) if $VERBOSE
|
|
251
|
-
#{caller[0]} is calling SQLite3::Database#execute_batch with bind parameters
|
|
252
|
-
that are not a list of a hash. Please switch to passing bind parameters as an
|
|
253
|
-
array or hash. Support for this behavior will be removed in version 2.0.0.
|
|
254
|
-
eowarn
|
|
255
|
-
end
|
|
256
|
-
|
|
257
|
-
# FIXME: remove this stuff later
|
|
258
|
-
if bind_vars.nil? || !args.empty?
|
|
259
|
-
if args.empty?
|
|
260
|
-
bind_vars = []
|
|
261
|
-
else
|
|
262
|
-
bind_vars = [nil] + args
|
|
263
|
-
end
|
|
264
|
-
|
|
265
|
-
warn(<<-eowarn) if $VERBOSE
|
|
266
|
-
#{caller[0]} is calling SQLite3::Database#execute_batch with nil or multiple bind params
|
|
267
|
-
without using an array. Please switch to passing bind parameters as an array.
|
|
268
|
-
Support for this behavior will be removed in version 2.0.0.
|
|
269
|
-
eowarn
|
|
270
|
-
end
|
|
271
|
-
|
|
295
|
+
def execute_batch(sql, bind_vars = [])
|
|
272
296
|
sql = sql.strip
|
|
273
|
-
|
|
274
|
-
|
|
297
|
+
result = nil
|
|
298
|
+
until sql.empty?
|
|
299
|
+
prepare(sql) do |stmt|
|
|
275
300
|
unless stmt.closed?
|
|
276
301
|
# FIXME: this should probably use sqlite3's api for batch execution
|
|
277
302
|
# This implementation requires stepping over the results.
|
|
278
303
|
if bind_vars.length == stmt.bind_parameter_count
|
|
279
304
|
stmt.bind_params(bind_vars)
|
|
280
305
|
end
|
|
281
|
-
stmt.step
|
|
306
|
+
result = stmt.step
|
|
282
307
|
end
|
|
283
308
|
sql = stmt.remainder.strip
|
|
284
309
|
end
|
|
285
310
|
end
|
|
286
|
-
|
|
287
|
-
|
|
311
|
+
|
|
312
|
+
result
|
|
288
313
|
end
|
|
289
314
|
|
|
290
315
|
# Executes all SQL statements in the given string. By contrast, the other
|
|
@@ -301,7 +326,7 @@ Support for this behavior will be removed in version 2.0.0.
|
|
|
301
326
|
# See also #execute_batch for additional ways of
|
|
302
327
|
# executing statements.
|
|
303
328
|
def execute_batch2(sql, &block)
|
|
304
|
-
if
|
|
329
|
+
if block
|
|
305
330
|
result = exec_batch(sql, @results_as_hash)
|
|
306
331
|
result.map do |val|
|
|
307
332
|
yield val
|
|
@@ -322,23 +347,8 @@ Support for this behavior will be removed in version 2.0.0.
|
|
|
322
347
|
# returned, or you could have problems with locks on the table. If called
|
|
323
348
|
# with a block, +close+ will be invoked implicitly when the block
|
|
324
349
|
# terminates.
|
|
325
|
-
def query(
|
|
326
|
-
|
|
327
|
-
if bind_vars.nil? || !args.empty?
|
|
328
|
-
if args.empty?
|
|
329
|
-
bind_vars = []
|
|
330
|
-
else
|
|
331
|
-
bind_vars = [bind_vars] + args
|
|
332
|
-
end
|
|
333
|
-
|
|
334
|
-
warn(<<-eowarn) if $VERBOSE
|
|
335
|
-
#{caller[0]} is calling SQLite3::Database#query with nil or multiple bind params
|
|
336
|
-
without using an array. Please switch to passing bind parameters as an array.
|
|
337
|
-
Support for this will be removed in version 2.0.0.
|
|
338
|
-
eowarn
|
|
339
|
-
end
|
|
340
|
-
|
|
341
|
-
result = prepare( sql ).execute( bind_vars )
|
|
350
|
+
def query(sql, bind_vars = [])
|
|
351
|
+
result = prepare(sql).execute(bind_vars)
|
|
342
352
|
if block_given?
|
|
343
353
|
begin
|
|
344
354
|
yield result
|
|
@@ -346,7 +356,7 @@ Support for this will be removed in version 2.0.0.
|
|
|
346
356
|
result.close
|
|
347
357
|
end
|
|
348
358
|
else
|
|
349
|
-
|
|
359
|
+
result
|
|
350
360
|
end
|
|
351
361
|
end
|
|
352
362
|
|
|
@@ -354,8 +364,8 @@ Support for this will be removed in version 2.0.0.
|
|
|
354
364
|
# discarding all others. It is otherwise identical to #execute.
|
|
355
365
|
#
|
|
356
366
|
# See also #get_first_value.
|
|
357
|
-
def get_first_row(
|
|
358
|
-
execute(
|
|
367
|
+
def get_first_row(sql, *bind_vars)
|
|
368
|
+
execute(sql, *bind_vars).first
|
|
359
369
|
end
|
|
360
370
|
|
|
361
371
|
# A convenience method for obtaining the first value of the first row of a
|
|
@@ -363,8 +373,8 @@ Support for this will be removed in version 2.0.0.
|
|
|
363
373
|
# identical to #execute.
|
|
364
374
|
#
|
|
365
375
|
# See also #get_first_row.
|
|
366
|
-
def get_first_value(
|
|
367
|
-
query(
|
|
376
|
+
def get_first_value(sql, *bind_vars)
|
|
377
|
+
query(sql, bind_vars) do |rs|
|
|
368
378
|
if (row = rs.next)
|
|
369
379
|
return @results_as_hash ? row[rs.columns[0]] : row[0]
|
|
370
380
|
end
|
|
@@ -372,7 +382,7 @@ Support for this will be removed in version 2.0.0.
|
|
|
372
382
|
nil
|
|
373
383
|
end
|
|
374
384
|
|
|
375
|
-
|
|
385
|
+
alias_method :busy_timeout, :busy_timeout=
|
|
376
386
|
|
|
377
387
|
# Creates a new function for use in SQL statements. It will be added as
|
|
378
388
|
# +name+, with the given +arity+. (For variable arity functions, use
|
|
@@ -386,6 +396,8 @@ Support for this will be removed in version 2.0.0.
|
|
|
386
396
|
# the FunctionProxy#result= method on the +func+ parameter and
|
|
387
397
|
# indicate the return value that way.
|
|
388
398
|
#
|
|
399
|
+
# A reference to the block will be kept for the lifetime of the database object.
|
|
400
|
+
#
|
|
389
401
|
# Example:
|
|
390
402
|
#
|
|
391
403
|
# db.create_function( "maim", 1 ) do |func, value|
|
|
@@ -397,7 +409,7 @@ Support for this will be removed in version 2.0.0.
|
|
|
397
409
|
# end
|
|
398
410
|
#
|
|
399
411
|
# puts db.get_first_value( "select maim(name) from table" )
|
|
400
|
-
def create_function name, arity, text_rep=Constants::TextRep::UTF8, &block
|
|
412
|
+
def create_function name, arity, text_rep = Constants::TextRep::UTF8, &block
|
|
401
413
|
define_function_with_flags(name, text_rep) do |*args|
|
|
402
414
|
fp = FunctionProxy.new
|
|
403
415
|
block.call(fp, *args)
|
|
@@ -425,6 +437,8 @@ Support for this will be removed in version 2.0.0.
|
|
|
425
437
|
# function invocation. It should invoke FunctionProxy#result= to
|
|
426
438
|
# store the result of the function.
|
|
427
439
|
#
|
|
440
|
+
# A reference to the block will be kept for the lifetime of the database object.
|
|
441
|
+
#
|
|
428
442
|
# Example:
|
|
429
443
|
#
|
|
430
444
|
# db.create_aggregate( "lengths", 1 ) do
|
|
@@ -442,20 +456,18 @@ Support for this will be removed in version 2.0.0.
|
|
|
442
456
|
#
|
|
443
457
|
# See also #create_aggregate_handler for a more object-oriented approach to
|
|
444
458
|
# aggregate functions.
|
|
445
|
-
def create_aggregate(
|
|
446
|
-
text_rep=Constants::TextRep::ANY, &block )
|
|
447
|
-
|
|
459
|
+
def create_aggregate(name, arity, step = nil, finalize = nil, text_rep = Constants::TextRep::ANY, &block)
|
|
448
460
|
proxy = Class.new do
|
|
449
|
-
def self.step(
|
|
461
|
+
def self.step(&block)
|
|
450
462
|
define_method(:step_with_ctx, &block)
|
|
451
463
|
end
|
|
452
464
|
|
|
453
|
-
def self.finalize(
|
|
465
|
+
def self.finalize(&block)
|
|
454
466
|
define_method(:finalize_with_ctx, &block)
|
|
455
467
|
end
|
|
456
468
|
end
|
|
457
469
|
|
|
458
|
-
if
|
|
470
|
+
if block
|
|
459
471
|
proxy.instance_eval(&block)
|
|
460
472
|
else
|
|
461
473
|
proxy.class_eval do
|
|
@@ -481,7 +493,7 @@ Support for this will be removed in version 2.0.0.
|
|
|
481
493
|
@ctx = FunctionProxy.new
|
|
482
494
|
end
|
|
483
495
|
|
|
484
|
-
def step(
|
|
496
|
+
def step(*args)
|
|
485
497
|
step_with_ctx(@ctx, *args)
|
|
486
498
|
end
|
|
487
499
|
|
|
@@ -540,7 +552,7 @@ Support for this will be removed in version 2.0.0.
|
|
|
540
552
|
#
|
|
541
553
|
# db.create_aggregate_handler( LengthsAggregateHandler )
|
|
542
554
|
# puts db.get_first_value( "select lengths(name) from A" )
|
|
543
|
-
def create_aggregate_handler(
|
|
555
|
+
def create_aggregate_handler(handler)
|
|
544
556
|
# This is a compatibility shim so the (basically pointless) FunctionProxy
|
|
545
557
|
# "ctx" object is passed as first argument to both step() and finalize().
|
|
546
558
|
# Now its up to the library user whether he prefers to store his
|
|
@@ -554,7 +566,7 @@ Support for this will be removed in version 2.0.0.
|
|
|
554
566
|
@fp = FunctionProxy.new
|
|
555
567
|
end
|
|
556
568
|
|
|
557
|
-
def step(
|
|
569
|
+
def step(*args)
|
|
558
570
|
super(@fp, *args)
|
|
559
571
|
end
|
|
560
572
|
|
|
@@ -577,7 +589,7 @@ Support for this will be removed in version 2.0.0.
|
|
|
577
589
|
# individual instances of the aggregate function. Regular ruby objects
|
|
578
590
|
# already provide a suitable +clone+.
|
|
579
591
|
# The functions arity is the arity of the +step+ method.
|
|
580
|
-
def define_aggregator(
|
|
592
|
+
def define_aggregator(name, aggregator)
|
|
581
593
|
# Previously, this has been implemented in C. Now this is just yet
|
|
582
594
|
# another compatibility shim
|
|
583
595
|
proxy = Class.new do
|
|
@@ -617,8 +629,10 @@ Support for this will be removed in version 2.0.0.
|
|
|
617
629
|
# by SQLite, so attempting to nest a transaction will result in a runtime
|
|
618
630
|
# exception.
|
|
619
631
|
#
|
|
620
|
-
# The +mode+ parameter may be either <tt>:deferred</tt
|
|
632
|
+
# The +mode+ parameter may be either <tt>:deferred</tt>,
|
|
621
633
|
# <tt>:immediate</tt>, or <tt>:exclusive</tt>.
|
|
634
|
+
# If `nil` is specified, the default transaction mode, which was
|
|
635
|
+
# passed to #initialize, is used.
|
|
622
636
|
#
|
|
623
637
|
# If a block is given, the database instance is yielded to it, and the
|
|
624
638
|
# transaction is committed when the block terminates. If the block
|
|
@@ -629,8 +643,9 @@ Support for this will be removed in version 2.0.0.
|
|
|
629
643
|
# If a block is not given, it is the caller's responsibility to end the
|
|
630
644
|
# transaction explicitly, either by calling #commit, or by calling
|
|
631
645
|
# #rollback.
|
|
632
|
-
def transaction(
|
|
633
|
-
|
|
646
|
+
def transaction(mode = nil)
|
|
647
|
+
mode = @default_transaction_mode if mode.nil?
|
|
648
|
+
execute "begin #{mode} transaction"
|
|
634
649
|
|
|
635
650
|
if block_given?
|
|
636
651
|
abort = false
|
|
@@ -642,9 +657,9 @@ Support for this will be removed in version 2.0.0.
|
|
|
642
657
|
ensure
|
|
643
658
|
abort and rollback or commit
|
|
644
659
|
end
|
|
660
|
+
else
|
|
661
|
+
true
|
|
645
662
|
end
|
|
646
|
-
|
|
647
|
-
true
|
|
648
663
|
end
|
|
649
664
|
|
|
650
665
|
# Commits the current transaction. If there is no current transaction,
|
|
@@ -671,6 +686,71 @@ Support for this will be removed in version 2.0.0.
|
|
|
671
686
|
@readonly
|
|
672
687
|
end
|
|
673
688
|
|
|
689
|
+
# Sets a #busy_handler that releases the GVL between retries,
|
|
690
|
+
# but only retries up to the indicated number of +milliseconds+.
|
|
691
|
+
# This is an alternative to #busy_timeout, which holds the GVL
|
|
692
|
+
# while SQLite sleeps and retries.
|
|
693
|
+
def busy_handler_timeout=(milliseconds)
|
|
694
|
+
timeout_seconds = milliseconds.fdiv(1000)
|
|
695
|
+
|
|
696
|
+
busy_handler do |count|
|
|
697
|
+
now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
|
|
698
|
+
if count.zero?
|
|
699
|
+
@timeout_deadline = now + timeout_seconds
|
|
700
|
+
elsif now > @timeout_deadline
|
|
701
|
+
next false
|
|
702
|
+
else
|
|
703
|
+
sleep(0.001)
|
|
704
|
+
end
|
|
705
|
+
end
|
|
706
|
+
end
|
|
707
|
+
|
|
708
|
+
# call-seq:
|
|
709
|
+
# load_extension(extension_specifier) -> self
|
|
710
|
+
#
|
|
711
|
+
# Loads an SQLite extension library from the named file. Extension loading must be enabled using
|
|
712
|
+
# #enable_load_extension prior to using this method.
|
|
713
|
+
#
|
|
714
|
+
# See also: Database@SQLite+Extensions
|
|
715
|
+
#
|
|
716
|
+
# [Parameters]
|
|
717
|
+
# - +extension_specifier+: (String | +_ExtensionSpecifier+) If a String, it is the filesystem path
|
|
718
|
+
# to the sqlite extension file. If an object that responds to #to_path, the
|
|
719
|
+
# return value of that method is used as the filesystem path to the sqlite extension file.
|
|
720
|
+
#
|
|
721
|
+
# [Example] Using a filesystem path:
|
|
722
|
+
#
|
|
723
|
+
# db.load_extension("/path/to/my_extension.so")
|
|
724
|
+
#
|
|
725
|
+
# [Example] Using the {sqlean gem}[https://github.com/flavorjones/sqlean-ruby]:
|
|
726
|
+
#
|
|
727
|
+
# db.load_extension(SQLean::VSV)
|
|
728
|
+
#
|
|
729
|
+
def load_extension(extension_specifier)
|
|
730
|
+
if extension_specifier.respond_to?(:to_path)
|
|
731
|
+
extension_specifier = extension_specifier.to_path
|
|
732
|
+
elsif !extension_specifier.is_a?(String)
|
|
733
|
+
raise TypeError, "extension_specifier #{extension_specifier.inspect} is not a String or a valid extension specifier object"
|
|
734
|
+
end
|
|
735
|
+
load_extension_internal(extension_specifier)
|
|
736
|
+
end
|
|
737
|
+
|
|
738
|
+
def initialize_extensions(extensions) # :nodoc:
|
|
739
|
+
return if extensions.nil?
|
|
740
|
+
raise TypeError, "extensions must be an Array" unless extensions.is_a?(Array)
|
|
741
|
+
return if extensions.empty?
|
|
742
|
+
|
|
743
|
+
begin
|
|
744
|
+
enable_load_extension(true)
|
|
745
|
+
|
|
746
|
+
extensions.each do |extension|
|
|
747
|
+
load_extension(extension)
|
|
748
|
+
end
|
|
749
|
+
ensure
|
|
750
|
+
enable_load_extension(false)
|
|
751
|
+
end
|
|
752
|
+
end
|
|
753
|
+
|
|
674
754
|
# A helper class for dealing with custom functions (see #create_function,
|
|
675
755
|
# #create_aggregate, and #create_aggregate_handler). It encapsulates the
|
|
676
756
|
# opaque function object that represents the current invocation. It also
|
|
@@ -687,54 +767,31 @@ Support for this will be removed in version 2.0.0.
|
|
|
687
767
|
# it is non-nil, it must quack like a Hash. If it is nil, then none of
|
|
688
768
|
# the context functions will be available.
|
|
689
769
|
def initialize
|
|
690
|
-
@result
|
|
691
|
-
@context
|
|
692
|
-
end
|
|
693
|
-
|
|
694
|
-
# Set the result of the function to the given error message.
|
|
695
|
-
# The function will then return that error.
|
|
696
|
-
def set_error( error )
|
|
697
|
-
@driver.result_error( @func, error.to_s, -1 )
|
|
698
|
-
end
|
|
699
|
-
|
|
700
|
-
# (Only available to aggregate functions.) Returns the number of rows
|
|
701
|
-
# that the aggregate has processed so far. This will include the current
|
|
702
|
-
# row, and so will always return at least 1.
|
|
703
|
-
def count
|
|
704
|
-
@driver.aggregate_count( @func )
|
|
770
|
+
@result = nil
|
|
771
|
+
@context = {}
|
|
705
772
|
end
|
|
706
773
|
|
|
707
774
|
# Returns the value with the given key from the context. This is only
|
|
708
775
|
# available to aggregate functions.
|
|
709
|
-
def [](
|
|
710
|
-
@context[
|
|
776
|
+
def [](key)
|
|
777
|
+
@context[key]
|
|
711
778
|
end
|
|
712
779
|
|
|
713
780
|
# Sets the value with the given key in the context. This is only
|
|
714
781
|
# available to aggregate functions.
|
|
715
|
-
def []=(
|
|
716
|
-
@context[
|
|
782
|
+
def []=(key, value)
|
|
783
|
+
@context[key] = value
|
|
717
784
|
end
|
|
718
785
|
end
|
|
719
786
|
|
|
720
|
-
#
|
|
721
|
-
|
|
722
|
-
|
|
723
|
-
|
|
724
|
-
|
|
725
|
-
|
|
726
|
-
|
|
727
|
-
NULL_TRANSLATOR = lambda { |_, row| row }
|
|
728
|
-
|
|
729
|
-
def make_type_translator should_translate
|
|
730
|
-
if should_translate
|
|
731
|
-
lambda { |types, row|
|
|
732
|
-
types.zip(row).map do |type, value|
|
|
733
|
-
translator.translate( type, value )
|
|
734
|
-
end
|
|
735
|
-
}
|
|
787
|
+
# Given a statement, return a result set.
|
|
788
|
+
# This is not intended for general consumption
|
|
789
|
+
# :nodoc:
|
|
790
|
+
def build_result_set stmt
|
|
791
|
+
if results_as_hash
|
|
792
|
+
HashResultSet.new(self, stmt)
|
|
736
793
|
else
|
|
737
|
-
|
|
794
|
+
ResultSet.new(self, stmt)
|
|
738
795
|
end
|
|
739
796
|
end
|
|
740
797
|
end
|