sqlite3 1.5.0.rc1-x86_64-darwin

Sign up to get free protection for your applications and to get access to all the features.
Files changed (60) hide show
  1. checksums.yaml +7 -0
  2. data/.gemtest +0 -0
  3. data/API_CHANGES.md +49 -0
  4. data/CHANGELOG.md +419 -0
  5. data/CONTRIBUTING.md +24 -0
  6. data/ChangeLog.cvs +88 -0
  7. data/Gemfile +3 -0
  8. data/LICENSE +27 -0
  9. data/LICENSE-DEPENDENCIES +20 -0
  10. data/README.md +233 -0
  11. data/ext/sqlite3/aggregator.c +273 -0
  12. data/ext/sqlite3/aggregator.h +12 -0
  13. data/ext/sqlite3/backup.c +168 -0
  14. data/ext/sqlite3/backup.h +15 -0
  15. data/ext/sqlite3/database.c +853 -0
  16. data/ext/sqlite3/database.h +17 -0
  17. data/ext/sqlite3/exception.c +98 -0
  18. data/ext/sqlite3/exception.h +8 -0
  19. data/ext/sqlite3/extconf.rb +159 -0
  20. data/ext/sqlite3/sqlite3.c +163 -0
  21. data/ext/sqlite3/sqlite3_ruby.h +45 -0
  22. data/ext/sqlite3/statement.c +442 -0
  23. data/ext/sqlite3/statement.h +16 -0
  24. data/faq/faq.md +431 -0
  25. data/faq/faq.rb +145 -0
  26. data/faq/faq.yml +426 -0
  27. data/lib/sqlite3/2.6/sqlite3_native.bundle +0 -0
  28. data/lib/sqlite3/2.7/sqlite3_native.bundle +0 -0
  29. data/lib/sqlite3/3.0/sqlite3_native.bundle +0 -0
  30. data/lib/sqlite3/3.1/sqlite3_native.bundle +0 -0
  31. data/lib/sqlite3/constants.rb +50 -0
  32. data/lib/sqlite3/database.rb +741 -0
  33. data/lib/sqlite3/errors.rb +35 -0
  34. data/lib/sqlite3/pragmas.rb +595 -0
  35. data/lib/sqlite3/resultset.rb +187 -0
  36. data/lib/sqlite3/statement.rb +145 -0
  37. data/lib/sqlite3/translator.rb +118 -0
  38. data/lib/sqlite3/value.rb +57 -0
  39. data/lib/sqlite3/version.rb +25 -0
  40. data/lib/sqlite3.rb +15 -0
  41. data/test/helper.rb +27 -0
  42. data/test/test_backup.rb +33 -0
  43. data/test/test_collation.rb +82 -0
  44. data/test/test_database.rb +538 -0
  45. data/test/test_database_flags.rb +95 -0
  46. data/test/test_database_readonly.rb +36 -0
  47. data/test/test_database_readwrite.rb +41 -0
  48. data/test/test_deprecated.rb +44 -0
  49. data/test/test_encoding.rb +155 -0
  50. data/test/test_integration.rb +507 -0
  51. data/test/test_integration_aggregate.rb +336 -0
  52. data/test/test_integration_open_close.rb +30 -0
  53. data/test/test_integration_pending.rb +115 -0
  54. data/test/test_integration_resultset.rb +142 -0
  55. data/test/test_integration_statement.rb +194 -0
  56. data/test/test_result_set.rb +37 -0
  57. data/test/test_sqlite3.rb +25 -0
  58. data/test/test_statement.rb +263 -0
  59. data/test/test_statement_execute.rb +35 -0
  60. metadata +190 -0
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.rb ADDED
@@ -0,0 +1,145 @@
1
+ require 'yaml'
2
+ require 'redcloth'
3
+
4
+ def process_faq_list( faqs )
5
+ puts "<ul>"
6
+ faqs.each do |faq|
7
+ process_faq_list_item faq
8
+ end
9
+ puts "</ul>"
10
+ end
11
+
12
+ def process_faq_list_item( faq )
13
+ question = faq.keys.first
14
+ answer = faq.values.first
15
+
16
+ print "<li>"
17
+
18
+ question_text = RedCloth.new(question).to_html.gsub( %r{</?p>},"" )
19
+ if answer.is_a?( Array )
20
+ puts question_text
21
+ process_faq_list answer
22
+ else
23
+ print "<a href='##{question.object_id}'>#{question_text}</a>"
24
+ end
25
+
26
+ puts "</li>"
27
+ end
28
+
29
+ def process_faq_descriptions( faqs, path=nil )
30
+ faqs.each do |faq|
31
+ process_faq_description faq, path
32
+ end
33
+ end
34
+
35
+ def process_faq_description( faq, path )
36
+ question = faq.keys.first
37
+ path = ( path ? path + " " : "" ) + question
38
+ answer = faq.values.first
39
+
40
+ if answer.is_a?( Array )
41
+ process_faq_descriptions( answer, path )
42
+ else
43
+ title = RedCloth.new( path ).to_html.gsub( %r{</?p>}, "" )
44
+ answer = RedCloth.new( answer || "" )
45
+
46
+ puts "<a name='#{question.object_id}'></a>"
47
+ puts "<div class='faq-title'>#{title}</div>"
48
+ puts "<div class='faq-answer'>#{add_api_links(answer.to_html)}</div>"
49
+ end
50
+ end
51
+
52
+ API_OBJECTS = [ "Database", "Statement", "ResultSet",
53
+ "ParsedStatement", "Pragmas", "Translator" ].inject( "(" ) { |acc,name|
54
+ acc << "|" if acc.length > 1
55
+ acc << name
56
+ acc
57
+ } + ")"
58
+
59
+ def add_api_links( text )
60
+ text.gsub( /#{API_OBJECTS}(#(\w+))?/ ) do
61
+ disp_obj = obj = $1
62
+
63
+ case obj
64
+ when "Pragmas"; disp_obj = "Database"
65
+ end
66
+
67
+ method = $3
68
+ s = "<a href='http://sqlite-ruby.rubyforge.org/classes/SQLite/#{obj}.html'>#{disp_obj}"
69
+ s << "##{method}" if method
70
+ s << "</a>"
71
+ s
72
+ end
73
+ end
74
+
75
+ faqs = YAML.load( File.read( "faq.yml" ) )
76
+
77
+ puts <<-EOF
78
+ <html>
79
+ <head>
80
+ <title>SQLite3/Ruby FAQ</title>
81
+ <style type="text/css">
82
+ a, a:visited, a:active {
83
+ color: #00F;
84
+ text-decoration: none;
85
+ }
86
+
87
+ a:hover {
88
+ text-decoration: underline;
89
+ }
90
+
91
+ .faq-list {
92
+ color: #000;
93
+ font-family: vera-sans, verdana, arial, sans-serif;
94
+ }
95
+
96
+ .faq-title {
97
+ background: #007;
98
+ color: #FFF;
99
+ font-family: vera-sans, verdana, arial, sans-serif;
100
+ padding-left: 1em;
101
+ padding-top: 0.5em;
102
+ padding-bottom: 0.5em;
103
+ font-weight: bold;
104
+ font-size: large;
105
+ border: 1px solid #000;
106
+ }
107
+
108
+ .faq-answer {
109
+ margin-left: 1em;
110
+ color: #000;
111
+ font-family: vera-sans, verdana, arial, sans-serif;
112
+ }
113
+
114
+ .faq-answer pre {
115
+ margin-left: 1em;
116
+ color: #000;
117
+ background: #FFE;
118
+ font-size: normal;
119
+ border: 1px dotted #CCC;
120
+ padding: 1em;
121
+ }
122
+
123
+ h1 {
124
+ background: #005;
125
+ color: #FFF;
126
+ font-family: vera-sans, verdana, arial, sans-serif;
127
+ padding-left: 1em;
128
+ padding-top: 1em;
129
+ padding-bottom: 1em;
130
+ font-weight: bold;
131
+ font-size: x-large;
132
+ border: 1px solid #00F;
133
+ }
134
+ </style>
135
+ </head>
136
+ <body>
137
+ <h1>SQLite/Ruby FAQ</h1>
138
+ <div class="faq-list">
139
+ EOF
140
+
141
+ process_faq_list( faqs )
142
+ puts "</div>"
143
+ process_faq_descriptions( faqs )
144
+
145
+ puts "</body></html>"