sqlite3-ruby 0.9.0-mswin32
Sign up to get free protection for your applications and to get access to all the features.
Potentially problematic release.
This version of sqlite3-ruby might be problematic. Click here for more details.
- data/README +36 -0
- data/doc/faq/faq.html +382 -0
- data/doc/faq/faq.rb +177 -0
- data/doc/faq/faq.yml +426 -0
- data/ext/sqlite3_api/MANIFEST +4 -0
- data/ext/sqlite3_api/extconf.rb +8 -0
- data/ext/sqlite3_api/post-clean.rb +3 -0
- data/ext/sqlite3_api/post-distclean.rb +4 -0
- data/ext/sqlite3_api/sqlite3_api.i +339 -0
- data/lib/sqlite3.rb +33 -0
- data/lib/sqlite3/constants.rb +81 -0
- data/lib/sqlite3/database.rb +720 -0
- data/lib/sqlite3/driver/dl/api.rb +184 -0
- data/lib/sqlite3/driver/dl/driver.rb +334 -0
- data/lib/sqlite3/driver/native/driver.rb +218 -0
- data/lib/sqlite3/errors.rb +84 -0
- data/lib/sqlite3/pragmas.rb +254 -0
- data/lib/sqlite3/resultset.rb +172 -0
- data/lib/sqlite3/statement.rb +218 -0
- data/lib/sqlite3/translator.rb +135 -0
- data/lib/sqlite3/value.rb +89 -0
- data/lib/sqlite3/version.rb +45 -0
- data/lib/sqlite3_api.so +0 -0
- data/test/bm.rb +140 -0
- data/test/driver/dl/tc_driver.rb +322 -0
- data/test/mocks.rb +99 -0
- data/test/native-vs-dl.rb +126 -0
- data/test/tc_database.rb +216 -0
- data/test/tc_integration.rb +838 -0
- data/test/tests.rb +36 -0
- metadata +78 -0
data/README
ADDED
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
= SQLite3/Ruby Interface
|
|
2
|
+
|
|
3
|
+
This module allows Ruby programs to interface with the SQLite3
|
|
4
|
+
database engine (http://www.sqlite.org). You must have the
|
|
5
|
+
SQLite engine installed in order to build this module.
|
|
6
|
+
|
|
7
|
+
Note that this module is NOT compatible with SQLite 2.x.
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
== Compilation and Installation
|
|
11
|
+
|
|
12
|
+
Simply do the following, after installing SQLite3:
|
|
13
|
+
|
|
14
|
+
ruby setup.rb config
|
|
15
|
+
ruby setup.rb setup
|
|
16
|
+
ruby setup.rb install
|
|
17
|
+
|
|
18
|
+
Alternatively, you can download and install the RubyGem package for
|
|
19
|
+
SQLite3/Ruby (you must have RubyGems and SQLite3 installed, first):
|
|
20
|
+
|
|
21
|
+
gem install --remote sqlite3-ruby
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
== Usage
|
|
25
|
+
|
|
26
|
+
For help figuring out the SQLite3/Ruby interface, check out the
|
|
27
|
+
FAQ[http://sqlite-ruby.rubyforge.org/sqlite3/faq.html]. It includes examples of
|
|
28
|
+
usage. If you have any questions that you feel should be address in the
|
|
29
|
+
FAQ, please send them to jamis_buck@byu.edu.
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
== Contact Information
|
|
33
|
+
|
|
34
|
+
The project page is http://rubyforge.org/projects/sqlite-ruby. There, you can find
|
|
35
|
+
links to mailing lists and forums that you can use to discuss this library. Additionally,
|
|
36
|
+
there are trackers for submitting bugs and feature requests. Feel free to use them!
|
data/doc/faq/faq.html
ADDED
|
@@ -0,0 +1,382 @@
|
|
|
1
|
+
<html>
|
|
2
|
+
<head>
|
|
3
|
+
<title>SQLite3/Ruby FAQ</title>
|
|
4
|
+
<style type="text/css">
|
|
5
|
+
a, a:visited, a:active {
|
|
6
|
+
color: #00F;
|
|
7
|
+
text-decoration: none;
|
|
8
|
+
}
|
|
9
|
+
|
|
10
|
+
a:hover {
|
|
11
|
+
text-decoration: underline;
|
|
12
|
+
}
|
|
13
|
+
|
|
14
|
+
.faq-list {
|
|
15
|
+
color: #000;
|
|
16
|
+
font-family: vera-sans, verdana, arial, sans-serif;
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
.faq-title {
|
|
20
|
+
background: #007;
|
|
21
|
+
color: #FFF;
|
|
22
|
+
font-family: vera-sans, verdana, arial, sans-serif;
|
|
23
|
+
padding-left: 1em;
|
|
24
|
+
padding-top: 0.5em;
|
|
25
|
+
padding-bottom: 0.5em;
|
|
26
|
+
font-weight: bold;
|
|
27
|
+
font-size: large;
|
|
28
|
+
border: 1px solid #000;
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
.faq-answer {
|
|
32
|
+
margin-left: 1em;
|
|
33
|
+
color: #000;
|
|
34
|
+
font-family: vera-sans, verdana, arial, sans-serif;
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
.faq-answer pre {
|
|
38
|
+
margin-left: 1em;
|
|
39
|
+
color: #000;
|
|
40
|
+
background: #FFE;
|
|
41
|
+
font-size: normal;
|
|
42
|
+
border: 1px dotted #CCC;
|
|
43
|
+
padding: 1em;
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
h1 {
|
|
47
|
+
background: #005;
|
|
48
|
+
color: #FFF;
|
|
49
|
+
font-family: vera-sans, verdana, arial, sans-serif;
|
|
50
|
+
padding-left: 1em;
|
|
51
|
+
padding-top: 1em;
|
|
52
|
+
padding-bottom: 1em;
|
|
53
|
+
font-weight: bold;
|
|
54
|
+
font-size: x-large;
|
|
55
|
+
border: 1px solid #00F;
|
|
56
|
+
}
|
|
57
|
+
</style>
|
|
58
|
+
</head>
|
|
59
|
+
<body>
|
|
60
|
+
<h1>SQLite/Ruby FAQ</h1>
|
|
61
|
+
<div class="faq-list">
|
|
62
|
+
<ul>
|
|
63
|
+
<li>How do I do a database query?
|
|
64
|
+
<ul>
|
|
65
|
+
<li><a href='#538671086'>I just want an array of the rows…</a></li>
|
|
66
|
+
<li><a href='#538671046'>I’d like to use a block to iterate through the rows…</a></li>
|
|
67
|
+
<li><a href='#538671006'>I need to get the column names as well as the rows…</a></li>
|
|
68
|
+
<li><a href='#538670966'>I just want the first row of the result set…</a></li>
|
|
69
|
+
<li><a href='#538670926'>I just want the first value of the first row of the result set…</a></li>
|
|
70
|
+
</ul>
|
|
71
|
+
</li>
|
|
72
|
+
<li><a href='#538670856'>How do I prepare a statement for repeated execution?</a></li>
|
|
73
|
+
<li><a href='#538670816'>How do I use placeholders in an <span class="caps">SQL</span> statement?</a></li>
|
|
74
|
+
<li><a href='#538670776'>How do I discover metadata about a query?</a></li>
|
|
75
|
+
<li><a href='#538670736'>I’d like the rows to be indexible by column name.</a></li>
|
|
76
|
+
<li><a href='#538670696'>I’d like the values from a query to be the correct types, instead of String.</a></li>
|
|
77
|
+
<li><a href='#538670656'>How do insert binary data into the database?</a></li>
|
|
78
|
+
<li><a href='#538670616'>How do I do a <span class="caps">DDL </span>(insert, update, delete) statement?</a></li>
|
|
79
|
+
<li><a href='#538670576'>How do I execute multiple statements in a single string?</a></li>
|
|
80
|
+
<li><a href='#538670536'>How do I begin/end a transaction?</a></li>
|
|
81
|
+
</ul>
|
|
82
|
+
</div>
|
|
83
|
+
<a name='538671086'></a>
|
|
84
|
+
<div class='faq-title'>How do I do a database query? I just want an array of the rows…</div>
|
|
85
|
+
<div class='faq-answer'><p>Use the <a href='http://sqlite-ruby.rubyforge.org/classes/SQLite/Database.html'>Database#execute</a> method. If you don’t give it a block, it will return an array of all the rows:</p>
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
<pre>
|
|
89
|
+
require 'sqlite3'
|
|
90
|
+
|
|
91
|
+
db = SQLite3::<a href='http://sqlite-ruby.rubyforge.org/classes/SQLite/Database.html'>Database</a>.new( "test.db" )
|
|
92
|
+
rows = db.execute( "select * from test" )
|
|
93
|
+
</pre></div>
|
|
94
|
+
<a name='538671046'></a>
|
|
95
|
+
<div class='faq-title'>How do I do a database query? I’d like to use a block to iterate through the rows…</div>
|
|
96
|
+
<div class='faq-answer'><p>Use the <a href='http://sqlite-ruby.rubyforge.org/classes/SQLite/Database.html'>Database#execute</a> method. If you give it a block, each row of the result will be yielded to the block:</p>
|
|
97
|
+
|
|
98
|
+
|
|
99
|
+
<pre>
|
|
100
|
+
require 'sqlite3'
|
|
101
|
+
|
|
102
|
+
db = SQLite3::<a href='http://sqlite-ruby.rubyforge.org/classes/SQLite/Database.html'>Database</a>.new( "test.db" )
|
|
103
|
+
db.execute( "select * from test" ) do |row|
|
|
104
|
+
...
|
|
105
|
+
end
|
|
106
|
+
</pre></div>
|
|
107
|
+
<a name='538671006'></a>
|
|
108
|
+
<div class='faq-title'>How do I do a database query? I need to get the column names as well as the rows…</div>
|
|
109
|
+
<div class='faq-answer'><p>Use the <a href='http://sqlite-ruby.rubyforge.org/classes/SQLite/Database.html'>Database#execute2</a> method. This works just like <a href='http://sqlite-ruby.rubyforge.org/classes/SQLite/Database.html'>Database#execute</a>; if you don’t give it a block, it returns an array of rows; otherwise, it will yield each row to the block. <em>However</em>, the first row returned is always an array of the column names from the query:</p>
|
|
110
|
+
|
|
111
|
+
|
|
112
|
+
<pre>
|
|
113
|
+
require 'sqlite3'
|
|
114
|
+
|
|
115
|
+
db = SQLite3::<a href='http://sqlite-ruby.rubyforge.org/classes/SQLite/Database.html'>Database</a>.new( "test.db" )
|
|
116
|
+
columns, *rows = db.execute2( "select * from test" )
|
|
117
|
+
|
|
118
|
+
# or use a block:
|
|
119
|
+
|
|
120
|
+
columns = nil
|
|
121
|
+
db.execute2( "select * from test" ) do |row|
|
|
122
|
+
if columns.nil?
|
|
123
|
+
columns = row
|
|
124
|
+
else
|
|
125
|
+
# process row
|
|
126
|
+
end
|
|
127
|
+
end
|
|
128
|
+
</pre></div>
|
|
129
|
+
<a name='538670966'></a>
|
|
130
|
+
<div class='faq-title'>How do I do a database query? I just want the first row of the result set…</div>
|
|
131
|
+
<div class='faq-answer'><p>Easy. Just call <a href='http://sqlite-ruby.rubyforge.org/classes/SQLite/Database.html'>Database#get_first_row</a>:</p>
|
|
132
|
+
|
|
133
|
+
|
|
134
|
+
<pre>
|
|
135
|
+
row = db.get_first_row( "select * from table" )
|
|
136
|
+
</pre>
|
|
137
|
+
<p>This also supports bind variables, just like <a href='http://sqlite-ruby.rubyforge.org/classes/SQLite/Database.html'>Database#execute</a> and friends.</p></div>
|
|
138
|
+
<a name='538670926'></a>
|
|
139
|
+
<div class='faq-title'>How do I do a database query? I just want the first value of the first row of the result set…</div>
|
|
140
|
+
<div class='faq-answer'><p>Also easy. Just call <a href='http://sqlite-ruby.rubyforge.org/classes/SQLite/Database.html'>Database#get_first_value</a>:</p>
|
|
141
|
+
|
|
142
|
+
|
|
143
|
+
<pre>
|
|
144
|
+
count = db.get_first_value( "select count(*) from table" )
|
|
145
|
+
</pre>
|
|
146
|
+
<p>This also supports bind variables, just like <a href='http://sqlite-ruby.rubyforge.org/classes/SQLite/Database.html'>Database#execute</a> and friends.</p></div>
|
|
147
|
+
<a name='538670856'></a>
|
|
148
|
+
<div class='faq-title'>How do I prepare a statement for repeated execution?</div>
|
|
149
|
+
<div class='faq-answer'><p>If the same statement is going to be executed repeatedly, you can speed things up a bit by <em>preparing</em> the statement. You do this via the <a href='http://sqlite-ruby.rubyforge.org/classes/SQLite/Database.html'>Database#prepare</a> method. It returns a <a href='http://sqlite-ruby.rubyforge.org/classes/SQLite/Statement.html'>Statement</a> object, and you can then invoke #execute on that to get the <a href='http://sqlite-ruby.rubyforge.org/classes/SQLite/ResultSet.html'>ResultSet</a>:</p>
|
|
150
|
+
|
|
151
|
+
|
|
152
|
+
<pre>
|
|
153
|
+
stmt = db.prepare( "select * from person" )
|
|
154
|
+
|
|
155
|
+
1000.times do
|
|
156
|
+
stmt.execute do |result|
|
|
157
|
+
...
|
|
158
|
+
end
|
|
159
|
+
end
|
|
160
|
+
|
|
161
|
+
stmt.close
|
|
162
|
+
|
|
163
|
+
# or, use a block
|
|
164
|
+
|
|
165
|
+
db.prepare( "select * from person" ) do |stmt|
|
|
166
|
+
1000.times do
|
|
167
|
+
stmt.execute do |result|
|
|
168
|
+
...
|
|
169
|
+
end
|
|
170
|
+
end
|
|
171
|
+
end
|
|
172
|
+
</pre>
|
|
173
|
+
<p>This is made more useful by the ability to bind variables to placeholders via the <a href='http://sqlite-ruby.rubyforge.org/classes/SQLite/Statement.html'>Statement#bind_param</a> and <a href='http://sqlite-ruby.rubyforge.org/classes/SQLite/Statement.html'>Statement#bind_params</a> methods. (See the next <span class="caps">FAQ</span> for details.)</p></div>
|
|
174
|
+
<a name='538670816'></a>
|
|
175
|
+
<div class='faq-title'>How do I use placeholders in an <span class="caps">SQL</span> statement?</div>
|
|
176
|
+
<div class='faq-answer'><p>Placeholders in an <span class="caps">SQL</span> statement take any of the following formats:</p>
|
|
177
|
+
<ul>
|
|
178
|
+
<li><code>?</code></li>
|
|
179
|
+
<li><code>?<em>nnn</em></code></li>
|
|
180
|
+
<li><code>:<em>word</em></code></li>
|
|
181
|
+
</ul>
|
|
182
|
+
|
|
183
|
+
<p>Where <em>n</em> is an integer, and <em>word</em> is an alpha-numeric identifier (or number). When the placeholder is associated with a number, that number identifies the index of the bind variable to replace it with. When it is an identifier, it identifies the name of the correponding bind variable. (In the instance of the first format—a single question mark—the placeholder is assigned a number one greater than the last index used, or 1 if it is the first.)</p>
|
|
184
|
+
|
|
185
|
+
<p>For example, here is a query using these placeholder formats:</p>
|
|
186
|
+
|
|
187
|
+
|
|
188
|
+
<pre>
|
|
189
|
+
select *
|
|
190
|
+
from table
|
|
191
|
+
where ( c = ?2 or c = ? )
|
|
192
|
+
and d = :name
|
|
193
|
+
and e = :1
|
|
194
|
+
</pre>
|
|
195
|
+
<p>This defines 5 different placeholders: 1, 2, 3, and “name”.</p>
|
|
196
|
+
|
|
197
|
+
<p>You replace these placeholders by <em>binding</em> them to values. This can be accomplished in a variety of ways.</p>
|
|
198
|
+
|
|
199
|
+
<p>The <a href='http://sqlite-ruby.rubyforge.org/classes/SQLite/Database.html'>Database#execute</a>, and <a href='http://sqlite-ruby.rubyforge.org/classes/SQLite/Database.html'>Database#execute2</a> methods all accept additional arguments following the <span class="caps">SQL</span> statement. These arguments are assumed to be bind parameters, and they are bound (positionally) to their corresponding placeholders:</p>
|
|
200
|
+
|
|
201
|
+
|
|
202
|
+
<pre>
|
|
203
|
+
db.execute( "select * from table where a = ? and b = ?",
|
|
204
|
+
"hello",
|
|
205
|
+
"world" )
|
|
206
|
+
</pre>
|
|
207
|
+
<p>The above would replace the first question mark with ‘hello’ and the second with ‘world’. If the placeholders have an explicit index given, they will be replaced with the bind parameter at that index (1-based).</p>
|
|
208
|
+
|
|
209
|
+
<p>If a Hash is given as a bind parameter, then its key/value pairs are bound to the placeholders. This is how you bind by name:</p>
|
|
210
|
+
|
|
211
|
+
|
|
212
|
+
<pre>
|
|
213
|
+
db.execute( "select * from table where a = :name and b = :value",
|
|
214
|
+
"name" => "bob",
|
|
215
|
+
"value" => "priceless" )
|
|
216
|
+
</pre>
|
|
217
|
+
<p>You can also bind explicitly using the <a href='http://sqlite-ruby.rubyforge.org/classes/SQLite/Statement.html'>Statement</a> object itself. Just pass additional parameters to the <a href='http://sqlite-ruby.rubyforge.org/classes/SQLite/Statement.html'>Statement#execute</a> statement:</p>
|
|
218
|
+
|
|
219
|
+
|
|
220
|
+
<pre>
|
|
221
|
+
db.prepare( "select * from table where a = :name and b = ?" ) do |stmt|
|
|
222
|
+
stmt.execute "value", "name" => "bob"
|
|
223
|
+
end
|
|
224
|
+
</pre>
|
|
225
|
+
<p>Or do a <a href='http://sqlite-ruby.rubyforge.org/classes/SQLite/Database.html'>Database#prepare</a> to get the <a href='http://sqlite-ruby.rubyforge.org/classes/SQLite/Statement.html'>Statement</a>, and then use either <a href='http://sqlite-ruby.rubyforge.org/classes/SQLite/Statement.html'>Statement#bind_param</a> or <a href='http://sqlite-ruby.rubyforge.org/classes/SQLite/Statement.html'>Statement#bind_params</a>:</p>
|
|
226
|
+
|
|
227
|
+
|
|
228
|
+
<pre>
|
|
229
|
+
stmt = db.prepare( "select * from table where a = :name and b = ?" )
|
|
230
|
+
|
|
231
|
+
stmt.bind_param( "name", "bob" )
|
|
232
|
+
stmt.bind_param( 1, "value" )
|
|
233
|
+
|
|
234
|
+
# or
|
|
235
|
+
|
|
236
|
+
stmt.bind_params( "value", "name" => "bob" )
|
|
237
|
+
</pre></div>
|
|
238
|
+
<a name='538670776'></a>
|
|
239
|
+
<div class='faq-title'>How do I discover metadata about a query?</div>
|
|
240
|
+
<div class='faq-answer'><p>If you ever want to know the names or types of the columns in a result set, you can do it in several ways.</p>
|
|
241
|
+
|
|
242
|
+
<p>The first way is to ask the row object itself. Each row will have a property “fields” that returns an array of the column names. The row will also have a property “types” that returns an array of the column types:</p>
|
|
243
|
+
|
|
244
|
+
|
|
245
|
+
<pre>
|
|
246
|
+
rows = db.execute( "select * from table" )
|
|
247
|
+
p rows[0].fields
|
|
248
|
+
p rows[0].types
|
|
249
|
+
</pre>
|
|
250
|
+
<p>Obviously, this approach requires you to execute a statement that actually returns data. If you don’t know if the statement will return any rows, but you still need the metadata, you can use <a href='http://sqlite-ruby.rubyforge.org/classes/SQLite/Database.html'>Database#query</a> and ask the <a href='http://sqlite-ruby.rubyforge.org/classes/SQLite/ResultSet.html'>ResultSet</a> object itself:</p>
|
|
251
|
+
|
|
252
|
+
|
|
253
|
+
<pre>
|
|
254
|
+
db.query( "select * from table" ) do |result|
|
|
255
|
+
p result.columns
|
|
256
|
+
p result.types
|
|
257
|
+
...
|
|
258
|
+
end
|
|
259
|
+
</pre>
|
|
260
|
+
<p>Lastly, you can use <a href='http://sqlite-ruby.rubyforge.org/classes/SQLite/Database.html'>Database#prepare</a> and ask the <a href='http://sqlite-ruby.rubyforge.org/classes/SQLite/Statement.html'>Statement</a> object what the metadata are:</p>
|
|
261
|
+
|
|
262
|
+
|
|
263
|
+
<pre>
|
|
264
|
+
stmt = db.prepare( "select * from table" )
|
|
265
|
+
p stmt.columns
|
|
266
|
+
p stmt.types
|
|
267
|
+
</pre></div>
|
|
268
|
+
<a name='538670736'></a>
|
|
269
|
+
<div class='faq-title'>I’d like the rows to be indexible by column name.</div>
|
|
270
|
+
<div class='faq-answer'><p>By default, each row from a query is returned as an Array of values. This means that you can only obtain values by their index. Sometimes, however, you would like to obtain values by their column name.</p>
|
|
271
|
+
|
|
272
|
+
<p>The first way to do this is to set the <a href='http://sqlite-ruby.rubyforge.org/classes/SQLite/Database.html'>Database</a> property “results_as_hash” to true. If you do this, then all rows will be returned as Hash objects, with the column names as the keys. (In this case, the “fields” property is unavailable on the row, although the “types” property remains.)</p>
|
|
273
|
+
|
|
274
|
+
|
|
275
|
+
<pre>
|
|
276
|
+
db.results_as_hash = true
|
|
277
|
+
db.execute( "select * from table" ) do |row|
|
|
278
|
+
p row['column1']
|
|
279
|
+
p row['column2']
|
|
280
|
+
end
|
|
281
|
+
</pre>
|
|
282
|
+
<p>The other way is to use Ara Howard’s <a href="http://rubyforge.org/projects/arrayfields">ArrayFields</a> module. Just require “arrayfields”, and all of your rows will be indexable by column name, even though they are still arrays!</p>
|
|
283
|
+
|
|
284
|
+
|
|
285
|
+
<pre>
|
|
286
|
+
require 'arrayfields'
|
|
287
|
+
|
|
288
|
+
...
|
|
289
|
+
db.execute( "select * from table" ) do |row|
|
|
290
|
+
p row[0] == row['column1']
|
|
291
|
+
p row[1] == row['column2']
|
|
292
|
+
end
|
|
293
|
+
</pre></div>
|
|
294
|
+
<a name='538670696'></a>
|
|
295
|
+
<div class='faq-title'>I’d like the values from a query to be the correct types, instead of String.</div>
|
|
296
|
+
<div class='faq-answer'><p>You can turn on “type translation” by setting <a href='http://sqlite-ruby.rubyforge.org/classes/SQLite/Database.html'>Database#type_translation</a> to true:</p>
|
|
297
|
+
|
|
298
|
+
|
|
299
|
+
<pre>
|
|
300
|
+
db.type_translation = true
|
|
301
|
+
db.execute( "select * from table" ) do |row|
|
|
302
|
+
p row
|
|
303
|
+
end
|
|
304
|
+
</pre>
|
|
305
|
+
<p>By doing this, each return value for each row will be translated to its correct type, based on its declared column type.</p>
|
|
306
|
+
|
|
307
|
+
<p>You can even declare your own translation routines, if (for example) you are using an <span class="caps">SQL</span> type that is not handled by default:</p>
|
|
308
|
+
|
|
309
|
+
|
|
310
|
+
<pre>
|
|
311
|
+
# assume "objects" table has the following schema:
|
|
312
|
+
# create table objects (
|
|
313
|
+
# name varchar2(20),
|
|
314
|
+
# thing object
|
|
315
|
+
# )
|
|
316
|
+
|
|
317
|
+
db.type_translation = true
|
|
318
|
+
db.translator.add_translator( "object" ) do |type, value|
|
|
319
|
+
db.decode( value )
|
|
320
|
+
end
|
|
321
|
+
|
|
322
|
+
h = { :one=>:two, "three"=>"four", 5=>6 }
|
|
323
|
+
dump = db.encode( h )
|
|
324
|
+
|
|
325
|
+
db.execute( "insert into objects values ( ?, ? )", "bob", dump )
|
|
326
|
+
|
|
327
|
+
obj = db.get_first_value( "select thing from objects where name='bob'" )
|
|
328
|
+
p obj == h
|
|
329
|
+
</pre></div>
|
|
330
|
+
<a name='538670656'></a>
|
|
331
|
+
<div class='faq-title'>How do insert binary data into the database?</div>
|
|
332
|
+
<div class='faq-answer'><p>Use blobs. Blobs are new features of SQLite3. You have to use bind variables to make it work:</p>
|
|
333
|
+
|
|
334
|
+
|
|
335
|
+
<pre>
|
|
336
|
+
db.execute( "insert into foo ( ?, ? )",
|
|
337
|
+
SQLite3::Blob.new( "\0\1\2\3\4\5" ),
|
|
338
|
+
SQLite3::Blob.new( "a\0b\0c\0d ) )
|
|
339
|
+
</pre>
|
|
340
|
+
<p>The blob values must be indicated explicitly by binding each parameter to a value of type SQLite3::Blob.</p></div>
|
|
341
|
+
<a name='538670616'></a>
|
|
342
|
+
<div class='faq-title'>How do I do a <span class="caps">DDL </span>(insert, update, delete) statement?</div>
|
|
343
|
+
<div class='faq-answer'><p>You can actually do inserts, updates, and deletes in exactly the same way as selects, but in general the <a href='http://sqlite-ruby.rubyforge.org/classes/SQLite/Database.html'>Database#execute</a> method will be most convenient:</p>
|
|
344
|
+
|
|
345
|
+
|
|
346
|
+
<pre>
|
|
347
|
+
db.execute( "insert into table values ( ?, ? )", *bind_vars )
|
|
348
|
+
</pre></div>
|
|
349
|
+
<a name='538670576'></a>
|
|
350
|
+
<div class='faq-title'>How do I execute multiple statements in a single string?</div>
|
|
351
|
+
<div class='faq-answer'><p>The standard query methods (<a href='http://sqlite-ruby.rubyforge.org/classes/SQLite/Database.html'>Database#execute</a>, <a href='http://sqlite-ruby.rubyforge.org/classes/SQLite/Database.html'>Database#execute2</a>, <a href='http://sqlite-ruby.rubyforge.org/classes/SQLite/Database.html'>Database#query</a>, and <a href='http://sqlite-ruby.rubyforge.org/classes/SQLite/Statement.html'>Statement#execute</a>) will only execute the first statement in the string that is given to them. Thus, if you have a string with multiple <span class="caps">SQL</span> statements, each separated by a string, you can’t use those methods to execute them all at once.</p>
|
|
352
|
+
|
|
353
|
+
<p>Instead, use <a href='http://sqlite-ruby.rubyforge.org/classes/SQLite/Database.html'>Database#execute_batch</a>:</p>
|
|
354
|
+
|
|
355
|
+
|
|
356
|
+
<pre>
|
|
357
|
+
sql = <<SQL
|
|
358
|
+
create table the_table (
|
|
359
|
+
a varchar2(30),
|
|
360
|
+
b varchar2(30)
|
|
361
|
+
);
|
|
362
|
+
|
|
363
|
+
insert into the_table values ( 'one', 'two' );
|
|
364
|
+
insert into the_table values ( 'three', 'four' );
|
|
365
|
+
insert into the_table values ( 'five', 'six' );
|
|
366
|
+
SQL
|
|
367
|
+
|
|
368
|
+
db.execute_batch( sql )
|
|
369
|
+
</pre>
|
|
370
|
+
<p>Unlike the other query methods, <a href='http://sqlite-ruby.rubyforge.org/classes/SQLite/Database.html'>Database#execute_batch</a> accepts no block. It will also only ever return <ins>nil</ins>. Thus, it is really only suitable for batch processing of <span class="caps">DDL</span> statements.</p></div>
|
|
371
|
+
<a name='538670536'></a>
|
|
372
|
+
<div class='faq-title'>How do I begin/end a transaction?</div>
|
|
373
|
+
<div class='faq-answer'><p>Use <a href='http://sqlite-ruby.rubyforge.org/classes/SQLite/Database.html'>Database#transaction</a> to start a transaction. If you give it a block, the block will be automatically committed at the end of the block, unless an exception was raised, in which case the transaction will be rolled back. (Never explicitly call <a href='http://sqlite-ruby.rubyforge.org/classes/SQLite/Database.html'>Database#commit</a> or <a href='http://sqlite-ruby.rubyforge.org/classes/SQLite/Database.html'>Database#rollback</a> inside of a transaction block—you’ll get errors when the block terminates!)</p>
|
|
374
|
+
|
|
375
|
+
|
|
376
|
+
<pre> database.transaction do |db| db.execute( "insert into table values ( 'a', 'b', 'c' )" ) ... end </pre>
|
|
377
|
+
<p>Alternatively, if you don’t give a block to <a href='http://sqlite-ruby.rubyforge.org/classes/SQLite/Database.html'>Database#transaction</a>, the transaction remains open until you explicitly call <a href='http://sqlite-ruby.rubyforge.org/classes/SQLite/Database.html'>Database#commit</a> or <a href='http://sqlite-ruby.rubyforge.org/classes/SQLite/Database.html'>Database#rollback</a>.</p>
|
|
378
|
+
|
|
379
|
+
|
|
380
|
+
<pre> db.transaction db.execute( "insert into table values ( 'a', 'b', 'c' )" ) db.commit </pre>
|
|
381
|
+
<p>Note that SQLite does not allow nested transactions, so you’ll get errors if you try to open a new transaction while one is already active. Use <a href='http://sqlite-ruby.rubyforge.org/classes/SQLite/Database.html'>Database#transaction_active</a>? to determine whether a transaction is active or not.</p></div>
|
|
382
|
+
</body></html>
|
data/doc/faq/faq.rb
ADDED
|
@@ -0,0 +1,177 @@
|
|
|
1
|
+
#--
|
|
2
|
+
# =============================================================================
|
|
3
|
+
# Copyright (c) 2004, Jamis Buck (jgb3@email.byu.edu)
|
|
4
|
+
# All rights reserved.
|
|
5
|
+
#
|
|
6
|
+
# Redistribution and use in source and binary forms, with or without
|
|
7
|
+
# modification, are permitted provided that the following conditions are met:
|
|
8
|
+
#
|
|
9
|
+
# * Redistributions of source code must retain the above copyright notice,
|
|
10
|
+
# this list of conditions and the following disclaimer.
|
|
11
|
+
#
|
|
12
|
+
# * Redistributions in binary form must reproduce the above copyright
|
|
13
|
+
# notice, this list of conditions and the following disclaimer in the
|
|
14
|
+
# documentation and/or other materials provided with the distribution.
|
|
15
|
+
#
|
|
16
|
+
# * The names of its contributors may not be used to endorse or promote
|
|
17
|
+
# products derived from this software without specific prior written
|
|
18
|
+
# permission.
|
|
19
|
+
#
|
|
20
|
+
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
|
|
21
|
+
# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
22
|
+
# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
|
23
|
+
# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
|
|
24
|
+
# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
25
|
+
# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
|
|
26
|
+
# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
|
|
27
|
+
# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
|
|
28
|
+
# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
|
|
29
|
+
# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
30
|
+
# =============================================================================
|
|
31
|
+
#++
|
|
32
|
+
|
|
33
|
+
require 'yaml'
|
|
34
|
+
require 'redcloth'
|
|
35
|
+
|
|
36
|
+
def process_faq_list( faqs )
|
|
37
|
+
puts "<ul>"
|
|
38
|
+
faqs.each do |faq|
|
|
39
|
+
process_faq_list_item faq
|
|
40
|
+
end
|
|
41
|
+
puts "</ul>"
|
|
42
|
+
end
|
|
43
|
+
|
|
44
|
+
def process_faq_list_item( faq )
|
|
45
|
+
question = faq.keys.first
|
|
46
|
+
answer = faq.values.first
|
|
47
|
+
|
|
48
|
+
print "<li>"
|
|
49
|
+
|
|
50
|
+
question_text = RedCloth.new(question).to_html.gsub( %r{</?p>},"" )
|
|
51
|
+
if answer.is_a?( Array )
|
|
52
|
+
puts question_text
|
|
53
|
+
process_faq_list answer
|
|
54
|
+
else
|
|
55
|
+
print "<a href='##{question.id}'>#{question_text}</a>"
|
|
56
|
+
end
|
|
57
|
+
|
|
58
|
+
puts "</li>"
|
|
59
|
+
end
|
|
60
|
+
|
|
61
|
+
def process_faq_descriptions( faqs, path=nil )
|
|
62
|
+
faqs.each do |faq|
|
|
63
|
+
process_faq_description faq, path
|
|
64
|
+
end
|
|
65
|
+
end
|
|
66
|
+
|
|
67
|
+
def process_faq_description( faq, path )
|
|
68
|
+
question = faq.keys.first
|
|
69
|
+
path = ( path ? path + " " : "" ) + question
|
|
70
|
+
answer = faq.values.first
|
|
71
|
+
|
|
72
|
+
if answer.is_a?( Array )
|
|
73
|
+
process_faq_descriptions( answer, path )
|
|
74
|
+
else
|
|
75
|
+
title = RedCloth.new( path ).to_html.gsub( %r{</?p>}, "" )
|
|
76
|
+
answer = RedCloth.new( answer || "" )
|
|
77
|
+
|
|
78
|
+
puts "<a name='#{question.id}'></a>"
|
|
79
|
+
puts "<div class='faq-title'>#{title}</div>"
|
|
80
|
+
puts "<div class='faq-answer'>#{add_api_links(answer.to_html)}</div>"
|
|
81
|
+
end
|
|
82
|
+
end
|
|
83
|
+
|
|
84
|
+
API_OBJECTS = [ "Database", "Statement", "ResultSet",
|
|
85
|
+
"ParsedStatement", "Pragmas", "Translator" ].inject( "(" ) { |acc,name|
|
|
86
|
+
acc << "|" if acc.length > 1
|
|
87
|
+
acc << name
|
|
88
|
+
acc
|
|
89
|
+
} + ")"
|
|
90
|
+
|
|
91
|
+
def add_api_links( text )
|
|
92
|
+
text.gsub( /#{API_OBJECTS}(#(\w+))?/ ) do
|
|
93
|
+
disp_obj = obj = $1
|
|
94
|
+
|
|
95
|
+
case obj
|
|
96
|
+
when "Pragmas": disp_obj = "Database"
|
|
97
|
+
end
|
|
98
|
+
|
|
99
|
+
method = $3
|
|
100
|
+
s = "<a href='http://sqlite-ruby.rubyforge.org/classes/SQLite/#{obj}.html'>#{disp_obj}"
|
|
101
|
+
s << "##{method}" if method
|
|
102
|
+
s << "</a>"
|
|
103
|
+
s
|
|
104
|
+
end
|
|
105
|
+
end
|
|
106
|
+
|
|
107
|
+
faqs = YAML.load( File.read( "faq.yml" ) )
|
|
108
|
+
|
|
109
|
+
puts <<-EOF
|
|
110
|
+
<html>
|
|
111
|
+
<head>
|
|
112
|
+
<title>SQLite3/Ruby FAQ</title>
|
|
113
|
+
<style type="text/css">
|
|
114
|
+
a, a:visited, a:active {
|
|
115
|
+
color: #00F;
|
|
116
|
+
text-decoration: none;
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
a:hover {
|
|
120
|
+
text-decoration: underline;
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
.faq-list {
|
|
124
|
+
color: #000;
|
|
125
|
+
font-family: vera-sans, verdana, arial, sans-serif;
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
.faq-title {
|
|
129
|
+
background: #007;
|
|
130
|
+
color: #FFF;
|
|
131
|
+
font-family: vera-sans, verdana, arial, sans-serif;
|
|
132
|
+
padding-left: 1em;
|
|
133
|
+
padding-top: 0.5em;
|
|
134
|
+
padding-bottom: 0.5em;
|
|
135
|
+
font-weight: bold;
|
|
136
|
+
font-size: large;
|
|
137
|
+
border: 1px solid #000;
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
.faq-answer {
|
|
141
|
+
margin-left: 1em;
|
|
142
|
+
color: #000;
|
|
143
|
+
font-family: vera-sans, verdana, arial, sans-serif;
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
.faq-answer pre {
|
|
147
|
+
margin-left: 1em;
|
|
148
|
+
color: #000;
|
|
149
|
+
background: #FFE;
|
|
150
|
+
font-size: normal;
|
|
151
|
+
border: 1px dotted #CCC;
|
|
152
|
+
padding: 1em;
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
h1 {
|
|
156
|
+
background: #005;
|
|
157
|
+
color: #FFF;
|
|
158
|
+
font-family: vera-sans, verdana, arial, sans-serif;
|
|
159
|
+
padding-left: 1em;
|
|
160
|
+
padding-top: 1em;
|
|
161
|
+
padding-bottom: 1em;
|
|
162
|
+
font-weight: bold;
|
|
163
|
+
font-size: x-large;
|
|
164
|
+
border: 1px solid #00F;
|
|
165
|
+
}
|
|
166
|
+
</style>
|
|
167
|
+
</head>
|
|
168
|
+
<body>
|
|
169
|
+
<h1>SQLite/Ruby FAQ</h1>
|
|
170
|
+
<div class="faq-list">
|
|
171
|
+
EOF
|
|
172
|
+
|
|
173
|
+
process_faq_list( faqs )
|
|
174
|
+
puts "</div>"
|
|
175
|
+
process_faq_descriptions( faqs )
|
|
176
|
+
|
|
177
|
+
puts "</body></html>"
|