sqlite3 1.5.0-arm-linux
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.
- checksums.yaml +7 -0
- data/.gemtest +0 -0
- data/API_CHANGES.md +49 -0
- data/CHANGELOG.md +425 -0
- data/CONTRIBUTING.md +24 -0
- data/ChangeLog.cvs +88 -0
- data/Gemfile +3 -0
- data/LICENSE +27 -0
- data/LICENSE-DEPENDENCIES +20 -0
- data/README.md +233 -0
- data/ext/sqlite3/aggregator.c +274 -0
- data/ext/sqlite3/aggregator.h +12 -0
- data/ext/sqlite3/backup.c +168 -0
- data/ext/sqlite3/backup.h +15 -0
- data/ext/sqlite3/database.c +853 -0
- data/ext/sqlite3/database.h +17 -0
- data/ext/sqlite3/exception.c +98 -0
- data/ext/sqlite3/exception.h +8 -0
- data/ext/sqlite3/extconf.rb +252 -0
- data/ext/sqlite3/sqlite3.c +163 -0
- data/ext/sqlite3/sqlite3_ruby.h +48 -0
- data/ext/sqlite3/statement.c +442 -0
- data/ext/sqlite3/statement.h +16 -0
- data/faq/faq.md +431 -0
- data/faq/faq.rb +145 -0
- data/faq/faq.yml +426 -0
- data/lib/sqlite3/2.6/sqlite3_native.so +0 -0
- data/lib/sqlite3/2.7/sqlite3_native.so +0 -0
- data/lib/sqlite3/3.0/sqlite3_native.so +0 -0
- data/lib/sqlite3/3.1/sqlite3_native.so +0 -0
- data/lib/sqlite3/constants.rb +50 -0
- data/lib/sqlite3/database.rb +741 -0
- data/lib/sqlite3/errors.rb +35 -0
- data/lib/sqlite3/pragmas.rb +595 -0
- data/lib/sqlite3/resultset.rb +187 -0
- data/lib/sqlite3/statement.rb +145 -0
- data/lib/sqlite3/translator.rb +118 -0
- data/lib/sqlite3/value.rb +57 -0
- data/lib/sqlite3/version.rb +23 -0
- data/lib/sqlite3.rb +15 -0
- data/test/helper.rb +27 -0
- data/test/test_backup.rb +33 -0
- data/test/test_collation.rb +82 -0
- data/test/test_database.rb +545 -0
- data/test/test_database_flags.rb +95 -0
- data/test/test_database_readonly.rb +36 -0
- data/test/test_database_readwrite.rb +41 -0
- data/test/test_deprecated.rb +44 -0
- data/test/test_encoding.rb +155 -0
- data/test/test_integration.rb +507 -0
- data/test/test_integration_aggregate.rb +336 -0
- data/test/test_integration_open_close.rb +30 -0
- data/test/test_integration_pending.rb +115 -0
- data/test/test_integration_resultset.rb +142 -0
- data/test/test_integration_statement.rb +194 -0
- data/test/test_result_set.rb +37 -0
- data/test/test_sqlite3.rb +30 -0
- data/test/test_statement.rb +263 -0
- data/test/test_statement_execute.rb +35 -0
- metadata +190 -0
data/faq/faq.yml
ADDED
@@ -0,0 +1,426 @@
|
|
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
|
+
|
9
|
+
<pre>
|
10
|
+
require 'sqlite3'
|
11
|
+
|
12
|
+
db = SQLite3::Database.new( "test.db" )
|
13
|
+
rows = db.execute( "select * from test" )
|
14
|
+
</pre>
|
15
|
+
|
16
|
+
- "I'd like to use a block to iterate through the rows...": >-
|
17
|
+
|
18
|
+
Use the Database#execute method. If you give it a block, each row of the
|
19
|
+
result will be yielded to the block:
|
20
|
+
|
21
|
+
|
22
|
+
<pre>
|
23
|
+
require 'sqlite3'
|
24
|
+
|
25
|
+
db = SQLite3::Database.new( "test.db" )
|
26
|
+
db.execute( "select * from test" ) do |row|
|
27
|
+
...
|
28
|
+
end
|
29
|
+
</pre>
|
30
|
+
|
31
|
+
- "I need to get the column names as well as the rows...": >-
|
32
|
+
|
33
|
+
Use the Database#execute2 method. This works just like Database#execute;
|
34
|
+
if you don't give it a block, it returns an array of rows; otherwise, it
|
35
|
+
will yield each row to the block. _However_, the first row returned is
|
36
|
+
always an array of the column names from the query:
|
37
|
+
|
38
|
+
|
39
|
+
<pre>
|
40
|
+
require 'sqlite3'
|
41
|
+
|
42
|
+
db = SQLite3::Database.new( "test.db" )
|
43
|
+
columns, *rows = db.execute2( "select * from test" )
|
44
|
+
|
45
|
+
# or use a block:
|
46
|
+
|
47
|
+
columns = nil
|
48
|
+
db.execute2( "select * from test" ) do |row|
|
49
|
+
if columns.nil?
|
50
|
+
columns = row
|
51
|
+
else
|
52
|
+
# process row
|
53
|
+
end
|
54
|
+
end
|
55
|
+
</pre>
|
56
|
+
|
57
|
+
- "I just want the first row of the result set...": >-
|
58
|
+
|
59
|
+
Easy. Just call Database#get_first_row:
|
60
|
+
|
61
|
+
|
62
|
+
<pre>
|
63
|
+
row = db.get_first_row( "select * from table" )
|
64
|
+
</pre>
|
65
|
+
|
66
|
+
|
67
|
+
This also supports bind variables, just like Database#execute
|
68
|
+
and friends.
|
69
|
+
|
70
|
+
- "I just want the first value of the first row of the result set...": >-
|
71
|
+
|
72
|
+
Also easy. Just call Database#get_first_value:
|
73
|
+
|
74
|
+
|
75
|
+
<pre>
|
76
|
+
count = db.get_first_value( "select count(*) from table" )
|
77
|
+
</pre>
|
78
|
+
|
79
|
+
|
80
|
+
This also supports bind variables, just like Database#execute
|
81
|
+
and friends.
|
82
|
+
|
83
|
+
- "How do I prepare a statement for repeated execution?": >-
|
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
|
+
<pre>
|
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
|
+
</pre>
|
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
|
+
Placeholders in an SQL statement take any of the following formats:
|
119
|
+
|
120
|
+
|
121
|
+
* @?@
|
122
|
+
|
123
|
+
* @?_nnn_@
|
124
|
+
|
125
|
+
* @:_word_@
|
126
|
+
|
127
|
+
|
128
|
+
Where _n_ is an integer, and _word_ is an alpha-numeric identifier (or
|
129
|
+
number). When the placeholder is associated with a number, that number
|
130
|
+
identifies the index of the bind variable to replace it with. When it
|
131
|
+
is an identifier, it identifies the name of the corresponding bind
|
132
|
+
variable. (In the instance of the first format--a single question
|
133
|
+
mark--the placeholder is assigned a number one greater than the last
|
134
|
+
index used, or 1 if it is the first.)
|
135
|
+
|
136
|
+
|
137
|
+
For example, here is a query using these placeholder formats:
|
138
|
+
|
139
|
+
|
140
|
+
<pre>
|
141
|
+
select *
|
142
|
+
from table
|
143
|
+
where ( c = ?2 or c = ? )
|
144
|
+
and d = :name
|
145
|
+
and e = :1
|
146
|
+
</pre>
|
147
|
+
|
148
|
+
|
149
|
+
This defines 5 different placeholders: 1, 2, 3, and "name".
|
150
|
+
|
151
|
+
|
152
|
+
You replace these placeholders by _binding_ them to values. This can be
|
153
|
+
accomplished in a variety of ways.
|
154
|
+
|
155
|
+
|
156
|
+
The Database#execute, and Database#execute2 methods all accept additional
|
157
|
+
arguments following the SQL statement. These arguments are assumed to be
|
158
|
+
bind parameters, and they are bound (positionally) to their corresponding
|
159
|
+
placeholders:
|
160
|
+
|
161
|
+
|
162
|
+
<pre>
|
163
|
+
db.execute( "select * from table where a = ? and b = ?",
|
164
|
+
"hello",
|
165
|
+
"world" )
|
166
|
+
</pre>
|
167
|
+
|
168
|
+
|
169
|
+
The above would replace the first question mark with 'hello' and the
|
170
|
+
second with 'world'. If the placeholders have an explicit index given, they
|
171
|
+
will be replaced with the bind parameter at that index (1-based).
|
172
|
+
|
173
|
+
|
174
|
+
If a Hash is given as a bind parameter, then its key/value pairs are bound
|
175
|
+
to the placeholders. This is how you bind by name:
|
176
|
+
|
177
|
+
|
178
|
+
<pre>
|
179
|
+
db.execute( "select * from table where a = :name and b = :value",
|
180
|
+
"name" => "bob",
|
181
|
+
"value" => "priceless" )
|
182
|
+
</pre>
|
183
|
+
|
184
|
+
|
185
|
+
You can also bind explicitly using the Statement object itself. Just pass
|
186
|
+
additional parameters to the Statement#execute statement:
|
187
|
+
|
188
|
+
|
189
|
+
<pre>
|
190
|
+
db.prepare( "select * from table where a = :name and b = ?" ) do |stmt|
|
191
|
+
stmt.execute "value", "name" => "bob"
|
192
|
+
end
|
193
|
+
</pre>
|
194
|
+
|
195
|
+
|
196
|
+
Or do a Database#prepare to get the Statement, and then use either
|
197
|
+
Statement#bind_param or Statement#bind_params:
|
198
|
+
|
199
|
+
|
200
|
+
<pre>
|
201
|
+
stmt = db.prepare( "select * from table where a = :name and b = ?" )
|
202
|
+
|
203
|
+
stmt.bind_param( "name", "bob" )
|
204
|
+
stmt.bind_param( 1, "value" )
|
205
|
+
|
206
|
+
# or
|
207
|
+
|
208
|
+
stmt.bind_params( "value", "name" => "bob" )
|
209
|
+
</pre>
|
210
|
+
|
211
|
+
- "How do I discover metadata about a query?": >-
|
212
|
+
|
213
|
+
If you ever want to know the names or types of the columns in a result
|
214
|
+
set, you can do it in several ways.
|
215
|
+
|
216
|
+
|
217
|
+
The first way is to ask the row object itself. Each row will have a
|
218
|
+
property "fields" that returns an array of the column names. The row
|
219
|
+
will also have a property "types" that returns an array of the column
|
220
|
+
types:
|
221
|
+
|
222
|
+
|
223
|
+
<pre>
|
224
|
+
rows = db.execute( "select * from table" )
|
225
|
+
p rows[0].fields
|
226
|
+
p rows[0].types
|
227
|
+
</pre>
|
228
|
+
|
229
|
+
|
230
|
+
Obviously, this approach requires you to execute a statement that actually
|
231
|
+
returns data. If you don't know if the statement will return any rows, but
|
232
|
+
you still need the metadata, you can use Database#query and ask the
|
233
|
+
ResultSet object itself:
|
234
|
+
|
235
|
+
|
236
|
+
<pre>
|
237
|
+
db.query( "select * from table" ) do |result|
|
238
|
+
p result.columns
|
239
|
+
p result.types
|
240
|
+
...
|
241
|
+
end
|
242
|
+
</pre>
|
243
|
+
|
244
|
+
|
245
|
+
Lastly, you can use Database#prepare and ask the Statement object what
|
246
|
+
the metadata are:
|
247
|
+
|
248
|
+
|
249
|
+
<pre>
|
250
|
+
stmt = db.prepare( "select * from table" )
|
251
|
+
p stmt.columns
|
252
|
+
p stmt.types
|
253
|
+
</pre>
|
254
|
+
|
255
|
+
- "I'd like the rows to be indexible by column name.": >-
|
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
|
+
<pre>
|
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
|
+
</pre>
|
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
|
+
<pre>
|
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
|
+
</pre>
|
291
|
+
|
292
|
+
- "I'd like the values from a query to be the correct types, instead of String.": >-
|
293
|
+
You can turn on "type translation" by setting Database#type_translation to
|
294
|
+
true:
|
295
|
+
|
296
|
+
|
297
|
+
<pre>
|
298
|
+
db.type_translation = true
|
299
|
+
db.execute( "select * from table" ) do |row|
|
300
|
+
p row
|
301
|
+
end
|
302
|
+
</pre>
|
303
|
+
|
304
|
+
|
305
|
+
By doing this, each return value for each row will be translated to its
|
306
|
+
correct type, based on its declared column type.
|
307
|
+
|
308
|
+
|
309
|
+
You can even declare your own translation routines, if (for example) you are
|
310
|
+
using an SQL type that is not handled by default:
|
311
|
+
|
312
|
+
|
313
|
+
<pre>
|
314
|
+
# assume "objects" table has the following schema:
|
315
|
+
# create table objects (
|
316
|
+
# name varchar2(20),
|
317
|
+
# thing object
|
318
|
+
# )
|
319
|
+
|
320
|
+
db.type_translation = true
|
321
|
+
db.translator.add_translator( "object" ) do |type, value|
|
322
|
+
db.decode( value )
|
323
|
+
end
|
324
|
+
|
325
|
+
h = { :one=>:two, "three"=>"four", 5=>6 }
|
326
|
+
dump = db.encode( h )
|
327
|
+
|
328
|
+
db.execute( "insert into objects values ( ?, ? )", "bob", dump )
|
329
|
+
|
330
|
+
obj = db.get_first_value( "select thing from objects where name='bob'" )
|
331
|
+
p obj == h
|
332
|
+
</pre>
|
333
|
+
|
334
|
+
- "How do I insert binary data into the database?": >-
|
335
|
+
Use blobs. Blobs are new features of SQLite3. You have to use bind
|
336
|
+
variables to make it work:
|
337
|
+
|
338
|
+
|
339
|
+
<pre>
|
340
|
+
db.execute( "insert into foo ( ?, ? )",
|
341
|
+
SQLite3::Blob.new( "\0\1\2\3\4\5" ),
|
342
|
+
SQLite3::Blob.new( "a\0b\0c\0d ) )
|
343
|
+
</pre>
|
344
|
+
|
345
|
+
|
346
|
+
The blob values must be indicated explicitly by binding each parameter to
|
347
|
+
a value of type SQLite3::Blob.
|
348
|
+
|
349
|
+
- "How do I do a DDL (insert, update, delete) statement?": >-
|
350
|
+
You can actually do inserts, updates, and deletes in exactly the same way
|
351
|
+
as selects, but in general the Database#execute method will be most
|
352
|
+
convenient:
|
353
|
+
|
354
|
+
|
355
|
+
<pre>
|
356
|
+
db.execute( "insert into table values ( ?, ? )", *bind_vars )
|
357
|
+
</pre>
|
358
|
+
|
359
|
+
- "How do I execute multiple statements in a single string?": >-
|
360
|
+
The standard query methods (Database#execute, Database#execute2,
|
361
|
+
Database#query, and Statement#execute) will only execute the first
|
362
|
+
statement in the string that is given to them. Thus, if you have a
|
363
|
+
string with multiple SQL statements, each separated by a string,
|
364
|
+
you can't use those methods to execute them all at once.
|
365
|
+
|
366
|
+
|
367
|
+
Instead, use Database#execute_batch:
|
368
|
+
|
369
|
+
|
370
|
+
<pre>
|
371
|
+
sql = <<SQL
|
372
|
+
create table the_table (
|
373
|
+
a varchar2(30),
|
374
|
+
b varchar2(30)
|
375
|
+
);
|
376
|
+
|
377
|
+
insert into the_table values ( 'one', 'two' );
|
378
|
+
insert into the_table values ( 'three', 'four' );
|
379
|
+
insert into the_table values ( 'five', 'six' );
|
380
|
+
SQL
|
381
|
+
|
382
|
+
db.execute_batch( sql )
|
383
|
+
</pre>
|
384
|
+
|
385
|
+
|
386
|
+
Unlike the other query methods, Database#execute_batch accepts no
|
387
|
+
block. It will also only ever return +nil+. Thus, it is really only
|
388
|
+
suitable for batch processing of DDL statements.
|
389
|
+
|
390
|
+
- "How do I begin/end a transaction?":
|
391
|
+
Use Database#transaction to start a transaction. If you give it a block,
|
392
|
+
the block will be automatically committed at the end of the block,
|
393
|
+
unless an exception was raised, in which case the transaction will be
|
394
|
+
rolled back. (Never explicitly call Database#commit or Database#rollback
|
395
|
+
inside of a transaction block--you'll get errors when the block
|
396
|
+
terminates!)
|
397
|
+
|
398
|
+
|
399
|
+
<pre>
|
400
|
+
database.transaction do |db|
|
401
|
+
db.execute( "insert into table values ( 'a', 'b', 'c' )" )
|
402
|
+
...
|
403
|
+
end
|
404
|
+
</pre>
|
405
|
+
|
406
|
+
|
407
|
+
Alternatively, if you don't give a block to Database#transaction, the
|
408
|
+
transaction remains open until you explicitly call Database#commit or
|
409
|
+
Database#rollback.
|
410
|
+
|
411
|
+
|
412
|
+
<pre>
|
413
|
+
db.transaction
|
414
|
+
db.execute( "insert into table values ( 'a', 'b', 'c' )" )
|
415
|
+
db.commit
|
416
|
+
</pre>
|
417
|
+
|
418
|
+
|
419
|
+
Note that SQLite does not allow nested transactions, so you'll get errors
|
420
|
+
if you try to open a new transaction while one is already active. Use
|
421
|
+
Database#transaction_active? to determine whether a transaction is
|
422
|
+
active or not.
|
423
|
+
|
424
|
+
#- "How do I discover metadata about a table/index?":
|
425
|
+
#
|
426
|
+
#- "How do I do tweak database settings?":
|
Binary file
|
Binary file
|
Binary file
|
Binary file
|
@@ -0,0 +1,50 @@
|
|
1
|
+
module SQLite3 ; module Constants
|
2
|
+
|
3
|
+
module TextRep
|
4
|
+
UTF8 = 1
|
5
|
+
UTF16LE = 2
|
6
|
+
UTF16BE = 3
|
7
|
+
UTF16 = 4
|
8
|
+
ANY = 5
|
9
|
+
DETERMINISTIC = 0x800
|
10
|
+
end
|
11
|
+
|
12
|
+
module ColumnType
|
13
|
+
INTEGER = 1
|
14
|
+
FLOAT = 2
|
15
|
+
TEXT = 3
|
16
|
+
BLOB = 4
|
17
|
+
NULL = 5
|
18
|
+
end
|
19
|
+
|
20
|
+
module ErrorCode
|
21
|
+
OK = 0 # Successful result
|
22
|
+
ERROR = 1 # SQL error or missing database
|
23
|
+
INTERNAL = 2 # An internal logic error in SQLite
|
24
|
+
PERM = 3 # Access permission denied
|
25
|
+
ABORT = 4 # Callback routine requested an abort
|
26
|
+
BUSY = 5 # The database file is locked
|
27
|
+
LOCKED = 6 # A table in the database is locked
|
28
|
+
NOMEM = 7 # A malloc() failed
|
29
|
+
READONLY = 8 # Attempt to write a readonly database
|
30
|
+
INTERRUPT = 9 # Operation terminated by sqlite_interrupt()
|
31
|
+
IOERR = 10 # Some kind of disk I/O error occurred
|
32
|
+
CORRUPT = 11 # The database disk image is malformed
|
33
|
+
NOTFOUND = 12 # (Internal Only) Table or record not found
|
34
|
+
FULL = 13 # Insertion failed because database is full
|
35
|
+
CANTOPEN = 14 # Unable to open the database file
|
36
|
+
PROTOCOL = 15 # Database lock protocol error
|
37
|
+
EMPTY = 16 # (Internal Only) Database table is empty
|
38
|
+
SCHEMA = 17 # The database schema changed
|
39
|
+
TOOBIG = 18 # Too much data for one row of a table
|
40
|
+
CONSTRAINT = 19 # Abort due to constraint violation
|
41
|
+
MISMATCH = 20 # Data type mismatch
|
42
|
+
MISUSE = 21 # Library used incorrectly
|
43
|
+
NOLFS = 22 # Uses OS features not supported on host
|
44
|
+
AUTH = 23 # Authorization denied
|
45
|
+
|
46
|
+
ROW = 100 # sqlite_step() has another row ready
|
47
|
+
DONE = 101 # sqlite_step() has finished executing
|
48
|
+
end
|
49
|
+
|
50
|
+
end ; end
|