sqlite3 1.4.4 → 1.5.0.rc1

Sign up to get free protection for your applications and to get access to all the features.
data/faq/faq.md ADDED
@@ -0,0 +1,431 @@
1
+
2
+ ## How do I do a database query?
3
+ ### I just want an array of the rows...
4
+
5
+ Use the `Database#execute` method. If you don't give it a block, it will
6
+ return an array of all the rows:
7
+
8
+ ```ruby
9
+ require 'sqlite3'
10
+
11
+ db = SQLite3::Database.new( "test.db" )
12
+ rows = db.execute( "select * from test" )
13
+ ```
14
+
15
+ ### I'd like to use a block to iterate through the rows...
16
+
17
+ Use the `Database#execute` method. If you give it a block, each row of the
18
+ result will be yielded to the block:
19
+
20
+
21
+ ```ruby
22
+ require 'sqlite3'
23
+
24
+ db = SQLite3::Database.new( "test.db" )
25
+ db.execute( "select * from test" ) do |row|
26
+ ...
27
+ end
28
+ ```
29
+
30
+ ### I need to get the column names as well as the rows...
31
+
32
+ Use the `Database#execute2` method. This works just like `Database#execute`;
33
+ if you don't give it a block, it returns an array of rows; otherwise, it
34
+ will yield each row to the block. _However_, the first row returned is
35
+ always an array of the column names from the query:
36
+
37
+
38
+ ```ruby
39
+ require 'sqlite3'
40
+
41
+ db = SQLite3::Database.new( "test.db" )
42
+ columns, *rows = db.execute2( "select * from test" )
43
+
44
+ # or use a block:
45
+
46
+ columns = nil
47
+ db.execute2( "select * from test" ) do |row|
48
+ if columns.nil?
49
+ columns = row
50
+ else
51
+ # process row
52
+ end
53
+ end
54
+ ```
55
+
56
+ ### I just want the first row of the result set...
57
+
58
+ Easy. Just call `Database#get_first_row`:
59
+
60
+
61
+ ```ruby
62
+ row = db.get_first_row( "select * from table" )
63
+ ```
64
+
65
+
66
+ This also supports bind variables, just like `Database#execute`
67
+ and friends.
68
+
69
+ ### I just want the first value of the first row of the result set...
70
+
71
+ Also easy. Just call `Database#get_first_value`:
72
+
73
+
74
+ ```ruby
75
+ count = db.get_first_value( "select count(*) from table" )
76
+ ```
77
+
78
+
79
+ This also supports bind variables, just like `Database#execute`
80
+ and friends.
81
+
82
+ ## How do I prepare a statement for repeated execution?
83
+
84
+ If the same statement is going to be executed repeatedly, you can speed
85
+ things up a bit by _preparing_ the statement. You do this via the
86
+ `Database#prepare` method. It returns a `Statement` object, and you can
87
+ then invoke `#execute` on that to get the `ResultSet`:
88
+
89
+
90
+ ```ruby
91
+ stmt = db.prepare( "select * from person" )
92
+
93
+ 1000.times do
94
+ stmt.execute do |result|
95
+ ...
96
+ end
97
+ end
98
+
99
+ stmt.close
100
+
101
+ # or, use a block
102
+
103
+ db.prepare( "select * from person" ) do |stmt|
104
+ 1000.times do
105
+ stmt.execute do |result|
106
+ ...
107
+ end
108
+ end
109
+ end
110
+ ```
111
+
112
+
113
+ This is made more useful by the ability to bind variables to placeholders
114
+ via the `Statement#bind_param` and `Statement#bind_params` methods. (See the
115
+ next FAQ for details.)
116
+
117
+ ## How do I use placeholders in an SQL statement?
118
+
119
+ Placeholders in an SQL statement take any of the following formats:
120
+
121
+
122
+ * `?`
123
+ * `?_nnn_`
124
+ * `:_word_`
125
+
126
+
127
+ Where _n_ is an integer, and _word_ is an alpha-numeric identifier (or
128
+ number). When the placeholder is associated with a number, that number
129
+ identifies the index of the bind variable to replace it with. When it
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
+ mark--the placeholder is assigned a number one greater than the last
133
+ index used, or 1 if it is the first.)
134
+
135
+
136
+ For example, here is a query using these placeholder formats:
137
+
138
+
139
+ ```sql
140
+ select *
141
+ from table
142
+ where ( c = ?2 or c = ? )
143
+ and d = :name
144
+ and e = :1
145
+ ```
146
+
147
+
148
+ This defines 5 different placeholders: 1, 2, 3, and "name".
149
+
150
+
151
+ You replace these placeholders by _binding_ them to values. This can be
152
+ accomplished in a variety of ways.
153
+
154
+
155
+ The `Database#execute`, and `Database#execute2` methods all accept additional
156
+ arguments following the SQL statement. These arguments are assumed to be
157
+ bind parameters, and they are bound (positionally) to their corresponding
158
+ placeholders:
159
+
160
+
161
+ ```ruby
162
+ db.execute( "select * from table where a = ? and b = ?",
163
+ "hello",
164
+ "world" )
165
+ ```
166
+
167
+
168
+ The above would replace the first question mark with 'hello' and the
169
+ second with 'world'. If the placeholders have an explicit index given, they
170
+ will be replaced with the bind parameter at that index (1-based).
171
+
172
+
173
+ If a Hash is given as a bind parameter, then its key/value pairs are bound
174
+ to the placeholders. This is how you bind by name:
175
+
176
+
177
+ ```ruby
178
+ db.execute( "select * from table where a = :name and b = :value",
179
+ "name" => "bob",
180
+ "value" => "priceless" )
181
+ ```
182
+
183
+
184
+ You can also bind explicitly using the `Statement` object itself. Just pass
185
+ additional parameters to the `Statement#execute` statement:
186
+
187
+
188
+ ```ruby
189
+ db.prepare( "select * from table where a = :name and b = ?" ) do |stmt|
190
+ stmt.execute "value", "name" => "bob"
191
+ end
192
+ ```
193
+
194
+
195
+ Or do a `Database#prepare` to get the `Statement`, and then use either
196
+ `Statement#bind_param` or `Statement#bind_params`:
197
+
198
+
199
+ ```ruby
200
+ stmt = db.prepare( "select * from table where a = :name and b = ?" )
201
+
202
+ stmt.bind_param( "name", "bob" )
203
+ stmt.bind_param( 1, "value" )
204
+
205
+ # or
206
+
207
+ stmt.bind_params( "value", "name" => "bob" )
208
+ ```
209
+
210
+ ## How do I discover metadata about a query?
211
+
212
+ If you ever want to know the names or types of the columns in a result
213
+ set, you can do it in several ways.
214
+
215
+
216
+ The first way is to ask the row object itself. Each row will have a
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:
220
+
221
+
222
+ ```ruby
223
+ rows = db.execute( "select * from table" )
224
+ p rows[0].fields
225
+ p rows[0].types
226
+ ```
227
+
228
+
229
+ Obviously, this approach requires you to execute a statement that actually
230
+ returns data. If you don't know if the statement will return any rows, but
231
+ you still need the metadata, you can use `Database#query` and ask the
232
+ `ResultSet` object itself:
233
+
234
+
235
+ ```ruby
236
+ db.query( "select * from table" ) do |result|
237
+ p result.columns
238
+ p result.types
239
+ ...
240
+ end
241
+ ```
242
+
243
+
244
+ Lastly, you can use `Database#prepare` and ask the `Statement` object what
245
+ the metadata are:
246
+
247
+
248
+ ```ruby
249
+ stmt = db.prepare( "select * from table" )
250
+ p stmt.columns
251
+ p stmt.types
252
+ ```
253
+
254
+ ## I'd like the rows to be indexible by column name.
255
+
256
+ By default, each row from a query is returned as an `Array` of values. This
257
+ means that you can only obtain values by their index. Sometimes, however,
258
+ you would like to obtain values by their column name.
259
+
260
+
261
+ The first way to do this is to set the Database property `results_as_hash`
262
+ to true. If you do this, then all rows will be returned as Hash objects,
263
+ with the column names as the keys. (In this case, the `fields` property
264
+ is unavailable on the row, although the "types" property remains.)
265
+
266
+
267
+ ```ruby
268
+ db.results_as_hash = true
269
+ db.execute( "select * from table" ) do |row|
270
+ p row['column1']
271
+ p row['column2']
272
+ end
273
+ ```
274
+
275
+
276
+ The other way is to use Ara Howard's
277
+ [`ArrayFields`](http://rubyforge.org/projects/arrayfields)
278
+ module. Just `require "arrayfields"`, and all of your rows will be indexable
279
+ by column name, even though they are still arrays!
280
+
281
+
282
+ ```ruby
283
+ require 'arrayfields'
284
+
285
+ ...
286
+ db.execute( "select * from table" ) do |row|
287
+ p row[0] == row['column1']
288
+ p row[1] == row['column2']
289
+ end
290
+ ```
291
+
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
+ ## How do I insert binary data into the database?
336
+
337
+ Use blobs. Blobs are new features of SQLite3. You have to use bind
338
+ variables to make it work:
339
+
340
+
341
+ ```ruby
342
+ db.execute( "insert into foo ( ?, ? )",
343
+ SQLite3::Blob.new( "\0\1\2\3\4\5" ),
344
+ SQLite3::Blob.new( "a\0b\0c\0d ) )
345
+ ```
346
+
347
+
348
+ The blob values must be indicated explicitly by binding each parameter to
349
+ a value of type `SQLite3::Blob`.
350
+
351
+ ## How do I do a DDL (insert, update, delete) statement?
352
+
353
+ You can actually do inserts, updates, and deletes in exactly the same way
354
+ as selects, but in general the `Database#execute` method will be most
355
+ convenient:
356
+
357
+
358
+ ```ruby
359
+ db.execute( "insert into table values ( ?, ? )", *bind_vars )
360
+ ```
361
+
362
+ ## How do I execute multiple statements in a single string?
363
+
364
+ The standard query methods (`Database#execute`, `Database#execute2`,
365
+ `Database#query`, and `Statement#execute`) will only execute the first
366
+ statement in the string that is given to them. Thus, if you have a
367
+ string with multiple SQL statements, each separated by a string,
368
+ you can't use those methods to execute them all at once.
369
+
370
+
371
+ Instead, use `Database#execute_batch`:
372
+
373
+
374
+ ```ruby
375
+ sql = <<SQL
376
+ create table the_table (
377
+ a varchar2(30),
378
+ b varchar2(30)
379
+ );
380
+
381
+ insert into the_table values ( 'one', 'two' );
382
+ insert into the_table values ( 'three', 'four' );
383
+ insert into the_table values ( 'five', 'six' );
384
+ SQL
385
+
386
+ db.execute_batch( sql )
387
+ ```
388
+
389
+
390
+ Unlike the other query methods, `Database#execute_batch` accepts no
391
+ block. It will also only ever return `nil`. Thus, it is really only
392
+ suitable for batch processing of DDL statements.
393
+
394
+ ## How do I begin/end a transaction
395
+
396
+ Use `Database#transaction` to start a transaction. If you give it a block,
397
+ the block will be automatically committed at the end of the block,
398
+ unless an exception was raised, in which case the transaction will be
399
+ rolled back. (Never explicitly call `Database#commit` or `Database#rollback`
400
+ inside of a transaction block--you'll get errors when the block
401
+ terminates!)
402
+
403
+
404
+ ```ruby
405
+ database.transaction do |db|
406
+ db.execute( "insert into table values ( 'a', 'b', 'c' )" )
407
+ ...
408
+ end
409
+ ```
410
+
411
+
412
+ Alternatively, if you don't give a block to `Database#transaction`, the
413
+ transaction remains open until you explicitly call `Database#commit` or
414
+ `Database#rollback`.
415
+
416
+
417
+ ```ruby
418
+ db.transaction
419
+ db.execute( "insert into table values ( 'a', 'b', 'c' )" )
420
+ db.commit
421
+ ```
422
+
423
+
424
+ Note that SQLite does not allow nested transactions, so you'll get errors
425
+ if you try to open a new transaction while one is already active. Use
426
+ `Database#transaction_active?` to determine whether a transaction is
427
+ active or not.
428
+
429
+ ## How do I discover metadata about a table/index?
430
+
431
+ ## How do I do tweak database settings?
@@ -1,13 +1,13 @@
1
1
  module SQLite3
2
2
 
3
- VERSION = '1.4.4'
3
+ VERSION = "1.5.0.rc1"
4
4
 
5
5
  module VersionProxy
6
6
 
7
7
  MAJOR = 1
8
- MINOR = 4
9
- TINY = 4
10
- BUILD = nil
8
+ MINOR = 5
9
+ TINY = 0
10
+ BUILD = "rc1"
11
11
 
12
12
  STRING = [ MAJOR, MINOR, TINY, BUILD ].compact.join( "." )
13
13
  #:beta-tag:
data/test/helper.rb CHANGED
@@ -3,11 +3,13 @@ require 'minitest/autorun'
3
3
 
4
4
  if ENV['GITHUB_ACTIONS'] == 'true' || ENV['CI']
5
5
  $VERBOSE = nil
6
- puts "\nSQLite3 Version: #{SQLite3::SQLITE_VERSION} $VERBOSE = nil", ""
7
- else
8
- puts "\nSQLite3 Version: #{SQLite3::SQLITE_VERSION}", ""
9
6
  end
10
7
 
8
+ puts "info: sqlite3-ruby version: #{SQLite3::VERSION}/#{SQLite3::VersionProxy::STRING}"
9
+ puts "info: sqlite3 version: #{SQLite3::SQLITE_VERSION}/#{SQLite3::SQLITE_LOADED_VERSION}"
10
+ puts "info: sqlcipher?: #{SQLite3.sqlcipher?}"
11
+ puts "info: threadsafe?: #{SQLite3.threadsafe?}"
12
+
11
13
  unless RUBY_VERSION >= "1.9"
12
14
  require 'iconv'
13
15
  end
@@ -20,7 +20,7 @@ module SQLite3
20
20
  assert_equal '', @db.filename('main')
21
21
  tf = Tempfile.new 'thing'
22
22
  @db = SQLite3::Database.new tf.path
23
- assert_equal File.expand_path(tf.path), File.expand_path(@db.filename('main'))
23
+ assert_equal File.realdirpath(tf.path), File.realdirpath(@db.filename('main'))
24
24
  ensure
25
25
  tf.unlink if tf
26
26
  end
@@ -30,7 +30,7 @@ module SQLite3
30
30
  assert_equal '', @db.filename
31
31
  tf = Tempfile.new 'thing'
32
32
  @db = SQLite3::Database.new tf.path
33
- assert_equal File.expand_path(tf.path), File.expand_path(@db.filename)
33
+ assert_equal File.realdirpath(tf.path), File.realdirpath(@db.filename)
34
34
  ensure
35
35
  tf.unlink if tf
36
36
  end
@@ -40,7 +40,8 @@ module SQLite3
40
40
  assert_equal '', @db.filename
41
41
  tf = Tempfile.new 'thing'
42
42
  @db.execute "ATTACH DATABASE '#{tf.path}' AS 'testing'"
43
- assert_equal File.expand_path(tf.path), File.expand_path(@db.filename('testing'))
43
+
44
+ assert_equal File.realdirpath(tf.path), File.realdirpath(@db.filename('testing'))
44
45
  ensure
45
46
  tf.unlink if tf
46
47
  end
@@ -50,7 +51,7 @@ module SQLite3
50
51
  tf = Tempfile.new 'thing'
51
52
  pn = Pathname tf.path
52
53
  db = SQLite3::Database.new pn
53
- assert_equal pn.expand_path.to_s, File.expand_path(db.filename)
54
+ assert_equal pn.realdirpath.to_s, File.realdirpath(db.filename)
54
55
  ensure
55
56
  tf.close! if tf
56
57
  end
@@ -360,7 +361,10 @@ module SQLite3
360
361
  nil
361
362
  end
362
363
  @db.execute("select hello(2.2, 'foo', NULL)")
363
- assert_equal [2.2, 'foo', nil], called_with
364
+
365
+ assert_in_delta(2.2, called_with[0], 0.0001)
366
+ assert_equal("foo", called_with[1])
367
+ assert_nil(called_with[2])
364
368
  end
365
369
 
366
370
  def test_define_varargs
@@ -370,7 +374,10 @@ module SQLite3
370
374
  nil
371
375
  end
372
376
  @db.execute("select hello(2.2, 'foo', NULL)")
373
- assert_equal [2.2, 'foo', nil], called_with
377
+
378
+ assert_in_delta(2.2, called_with[0], 0.0001)
379
+ assert_equal("foo", called_with[1])
380
+ assert_nil(called_with[2])
374
381
  end
375
382
 
376
383
  def test_call_func_blob
data/test/test_sqlite3.rb CHANGED
@@ -17,5 +17,9 @@ module SQLite3
17
17
  refute SQLite3.threadsafe?
18
18
  end
19
19
  end
20
+
21
+ def test_version_strings
22
+ assert_equal(SQLite3::VERSION, SQLite3::VersionProxy::STRING)
23
+ end
20
24
  end
21
25
  end