sqlite3 1.3.13-x64-mingw32 → 1.5.0.rc1-x64-mingw32

Sign up to get free protection for your applications and to get access to all the features.
Files changed (54) hide show
  1. checksums.yaml +5 -5
  2. data/.gemtest +0 -0
  3. data/{API_CHANGES.rdoc → API_CHANGES.md} +3 -4
  4. data/CHANGELOG.md +419 -0
  5. data/CONTRIBUTING.md +24 -0
  6. data/Gemfile +2 -14
  7. data/LICENSE-DEPENDENCIES +20 -0
  8. data/README.md +233 -0
  9. data/ext/sqlite3/aggregator.c +273 -0
  10. data/ext/sqlite3/aggregator.h +12 -0
  11. data/ext/sqlite3/database.c +169 -204
  12. data/ext/sqlite3/database.h +2 -0
  13. data/ext/sqlite3/exception.c +6 -2
  14. data/ext/sqlite3/extconf.rb +154 -66
  15. data/ext/sqlite3/sqlite3.c +12 -1
  16. data/ext/sqlite3/sqlite3_ruby.h +0 -7
  17. data/ext/sqlite3/statement.c +15 -20
  18. data/faq/faq.md +431 -0
  19. data/faq/faq.yml +1 -1
  20. data/lib/sqlite3/2.6/sqlite3_native.so +0 -0
  21. data/lib/sqlite3/2.7/sqlite3_native.so +0 -0
  22. data/lib/sqlite3/3.0/sqlite3_native.so +0 -0
  23. data/lib/sqlite3/constants.rb +2 -1
  24. data/lib/sqlite3/database.rb +202 -52
  25. data/lib/sqlite3/errors.rb +1 -10
  26. data/lib/sqlite3/pragmas.rb +17 -10
  27. data/lib/sqlite3/resultset.rb +2 -10
  28. data/lib/sqlite3/statement.rb +2 -1
  29. data/lib/sqlite3/translator.rb +1 -1
  30. data/lib/sqlite3/version.rb +4 -4
  31. data/test/helper.rb +9 -0
  32. data/test/test_database.rb +119 -11
  33. data/test/test_database_flags.rb +95 -0
  34. data/test/test_database_readwrite.rb +41 -0
  35. data/test/test_integration.rb +12 -81
  36. data/test/test_integration_aggregate.rb +336 -0
  37. data/test/test_integration_resultset.rb +0 -17
  38. data/test/test_sqlite3.rb +4 -0
  39. data/test/test_statement.rb +11 -8
  40. metadata +55 -86
  41. data/CHANGELOG.rdoc +0 -292
  42. data/Manifest.txt +0 -52
  43. data/README.rdoc +0 -118
  44. data/Rakefile +0 -10
  45. data/lib/sqlite3/2.0/sqlite3_native.so +0 -0
  46. data/lib/sqlite3/2.1/sqlite3_native.so +0 -0
  47. data/lib/sqlite3/2.2/sqlite3_native.so +0 -0
  48. data/lib/sqlite3/2.3/sqlite3_native.so +0 -0
  49. data/lib/sqlite3/2.4/sqlite3_native.so +0 -0
  50. data/setup.rb +0 -1333
  51. data/tasks/faq.rake +0 -9
  52. data/tasks/gem.rake +0 -38
  53. data/tasks/native.rake +0 -52
  54. data/tasks/vendor_sqlite3.rake +0 -97
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?
data/faq/faq.yml CHANGED
@@ -128,7 +128,7 @@
128
128
  Where _n_ is an integer, and _word_ is an alpha-numeric identifier (or
129
129
  number). When the placeholder is associated with a number, that number
130
130
  identifies the index of the bind variable to replace it with. When it
131
- is an identifier, it identifies the name of the correponding bind
131
+ is an identifier, it identifies the name of the corresponding bind
132
132
  variable. (In the instance of the first format--a single question
133
133
  mark--the placeholder is assigned a number one greater than the last
134
134
  index used, or 1 if it is the first.)
Binary file
Binary file
Binary file
@@ -6,6 +6,7 @@ module SQLite3 ; module Constants
6
6
  UTF16BE = 3
7
7
  UTF16 = 4
8
8
  ANY = 5
9
+ DETERMINISTIC = 0x800
9
10
  end
10
11
 
11
12
  module ColumnType
@@ -36,7 +37,7 @@ module SQLite3 ; module Constants
36
37
  EMPTY = 16 # (Internal Only) Database table is empty
37
38
  SCHEMA = 17 # The database schema changed
38
39
  TOOBIG = 18 # Too much data for one row of a table
39
- CONSTRAINT = 19 # Abort due to contraint violation
40
+ CONSTRAINT = 19 # Abort due to constraint violation
40
41
  MISMATCH = 20 # Data type mismatch
41
42
  MISUSE = 21 # Library used incorrectly
42
43
  NOLFS = 22 # Uses OS features not supported on host