sqlite3 1.5.0-arm64-darwin

Sign up to get free protection for your applications and to get access to all the features.

Potentially problematic release.


This version of sqlite3 might be problematic. Click here for more details.

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 +425 -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 +274 -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 +252 -0
  20. data/ext/sqlite3/sqlite3.c +163 -0
  21. data/ext/sqlite3/sqlite3_ruby.h +48 -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 +23 -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 +545 -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 +30 -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>"