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
@@ -1,14 +1,17 @@
1
- require 'sqlite3/constants'
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
- module SQLite3
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
- # The Database class encapsulates a single connection to a SQLite3 database.
11
- # Its usage is very straightforward:
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 provides by the selected driver, and
22
- # includes the Pragmas module for access to various pragma convenience
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
- # the SQLite3 data types (which are all represented as strings) may be
27
- # converted into their corresponding types (as defined in the schemas
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
- # ArrayFields module from Ara Howard. If you require the ArrayFields
33
- # module before performing a query, and if you have not enabled results as
34
- # hashes, then the results will all be indexible by field name.
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
- alias :open :new
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( string )
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: SQLite3::Database.new(file, options = {})
122
+ # call-seq:
123
+ # SQLite3::Database.new(file, options = {})
58
124
  #
59
- # Create a new Database object that opens the given file. If utf16
60
- # is +true+, the filename is interpreted as a UTF-16 encoded string.
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
- @tracefunc = nil
98
- @authorizer = nil
99
- @encoding = nil
100
- @busy_handler = nil
101
- @collations = {}
102
- @functions = {}
103
- @results_as_hash = options[:results_as_hash]
104
- @type_translation = options[:type_translation]
105
- @type_translator = make_type_translator @type_translation
106
- @readonly = mode & Constants::Open::READONLY != 0
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
- def type_translation= value # :nodoc:
118
- warn(<<-eowarn) if $VERBOSE
119
- #{caller[0]} is calling SQLite3::Database#type_translation=
120
- SQLite3::Database#type_translation= is deprecated and will be removed
121
- in version 2.0.0.
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( &block )
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( self, sql )
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 = 'main'
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 = [], *args, &block
184
- if bind_vars.nil? || !args.empty?
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 = ResultSet.new self, stmt
249
+ stmt = build_result_set stmt
201
250
 
202
- if block_given?
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( sql, *bind_vars )
223
- prepare( sql ) do |stmt|
224
- result = stmt.execute( *bind_vars )
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.inject( [ stmt.columns ] ) { |arr,row|
230
- arr << row; arr }
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 +nil+, making it unsuitable for queries that return
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( sql, bind_vars = [], *args )
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
- until sql.empty? do
274
- prepare( sql ) do |stmt|
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
- # FIXME: we should not return `nil` as a success return value
287
- nil
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 block_given?
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( sql, bind_vars = [], *args )
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
- return result
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( sql, *bind_vars )
358
- execute( sql, *bind_vars ).first
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( sql, *bind_vars )
367
- query( sql, bind_vars ) do |rs|
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
- alias :busy_timeout :busy_timeout=
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( name, arity, step=nil, finalize=nil,
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( &block )
461
+ def self.step(&block)
450
462
  define_method(:step_with_ctx, &block)
451
463
  end
452
464
 
453
- def self.finalize( &block )
465
+ def self.finalize(&block)
454
466
  define_method(:finalize_with_ctx, &block)
455
467
  end
456
468
  end
457
469
 
458
- if block_given?
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( *args )
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( 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( *args )
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( name, 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> (the default),
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( mode = :deferred )
633
- execute "begin #{mode.to_s} transaction"
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 = nil
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 []( key )
710
- @context[ key ]
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 []=( key, value )
716
- @context[ key ] = value
782
+ def []=(key, value)
783
+ @context[key] = value
717
784
  end
718
785
  end
719
786
 
720
- # Translates a +row+ of data from the database with the given +types+
721
- def translate_from_db types, row
722
- @type_translator.call types, row
723
- end
724
-
725
- private
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
- NULL_TRANSLATOR
794
+ ResultSet.new(self, stmt)
738
795
  end
739
796
  end
740
797
  end