rdbi 0.9.0
Sign up to get free protection for your applications and to get access to all the features.
- data/.document +5 -0
- data/.gitignore +33 -0
- data/LICENSE +20 -0
- data/README.rdoc +194 -0
- data/Rakefile +109 -0
- data/VERSION +1 -0
- data/docs/external-api.pdf +0 -0
- data/docs/external-api.texi +365 -0
- data/lib/rdbi.rb +189 -0
- data/lib/rdbi/cursor.rb +90 -0
- data/lib/rdbi/database.rb +262 -0
- data/lib/rdbi/driver.rb +35 -0
- data/lib/rdbi/pool.rb +236 -0
- data/lib/rdbi/result.rb +402 -0
- data/lib/rdbi/schema.rb +121 -0
- data/lib/rdbi/statement.rb +204 -0
- data/lib/rdbi/types.rb +200 -0
- data/rdbi.gemspec +94 -0
- data/test/helper.rb +32 -0
- data/test/test_database.rb +246 -0
- data/test/test_pool.rb +181 -0
- data/test/test_rdbi.rb +85 -0
- data/test/test_result.rb +269 -0
- data/test/test_statement.rb +66 -0
- data/test/test_types.rb +114 -0
- data/test/test_util.rb +61 -0
- metadata +201 -0
data/.document
ADDED
data/.gitignore
ADDED
@@ -0,0 +1,33 @@
|
|
1
|
+
## MAC OS
|
2
|
+
.DS_Store
|
3
|
+
|
4
|
+
## TEXTMATE
|
5
|
+
*.tmproj
|
6
|
+
tmtags
|
7
|
+
|
8
|
+
## EMACS
|
9
|
+
*~
|
10
|
+
\#*
|
11
|
+
.\#*
|
12
|
+
|
13
|
+
## VIM
|
14
|
+
*.swp
|
15
|
+
|
16
|
+
## PROJECT::GENERAL
|
17
|
+
coverage
|
18
|
+
rdoc
|
19
|
+
doc
|
20
|
+
pkg
|
21
|
+
.yardoc
|
22
|
+
|
23
|
+
## PROJECT::SPECIFIC
|
24
|
+
*.aux
|
25
|
+
*.cp
|
26
|
+
*.fn
|
27
|
+
*.fns
|
28
|
+
*.ky
|
29
|
+
*.log
|
30
|
+
*.pg
|
31
|
+
*.toc
|
32
|
+
*.tp
|
33
|
+
*.vr
|
data/LICENSE
ADDED
@@ -0,0 +1,20 @@
|
|
1
|
+
Copyright (c) 2009 Erik Hollensbe
|
2
|
+
|
3
|
+
Permission is hereby granted, free of charge, to any person obtaining
|
4
|
+
a copy of this software and associated documentation files (the
|
5
|
+
"Software"), to deal in the Software without restriction, including
|
6
|
+
without limitation the rights to use, copy, modify, merge, publish,
|
7
|
+
distribute, sublicense, and/or sell copies of the Software, and to
|
8
|
+
permit persons to whom the Software is furnished to do so, subject to
|
9
|
+
the following conditions:
|
10
|
+
|
11
|
+
The above copyright notice and this permission notice shall be
|
12
|
+
included in all copies or substantial portions of the Software.
|
13
|
+
|
14
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
15
|
+
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
16
|
+
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
|
17
|
+
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
|
18
|
+
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
|
19
|
+
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
|
20
|
+
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
data/README.rdoc
ADDED
@@ -0,0 +1,194 @@
|
|
1
|
+
= RDBI - Low-level Database Access Re-imagined
|
2
|
+
|
3
|
+
RDBI is intended primarily as an alternative to the heavier database layers in
|
4
|
+
the Ruby ecosystem. It provides a consistent interface to databases for working
|
5
|
+
with query languages directly, instead of providing an extremely high level
|
6
|
+
interface which does this work for you. While usable, it largely targets
|
7
|
+
high-level database libraries, similar to how +rack+ targets web frameworks.
|
8
|
+
|
9
|
+
== I'd like to get started
|
10
|
+
|
11
|
+
If you'd prefer to head straight to sinking your teeth into the API, here's a
|
12
|
+
path down the rabbit hole:
|
13
|
+
|
14
|
+
* RDBI is what you'll use to get your RDBI::Database handle. If you need
|
15
|
+
collections of database handles, look at RDBI::Pool.
|
16
|
+
* RDBI::Database contains methods for dealing with database level operations
|
17
|
+
and preparing and executing RDBI::Statement objects.
|
18
|
+
* RDBI::Statement works with RDBI::Cursor to yield RDBI::Result objects, which
|
19
|
+
leverage RDBI::Result::Driver classes to yield data.
|
20
|
+
* If you're interested in how schemas and types are dealt with, see
|
21
|
+
RDBI::Schema, RDBI::Column, and RDBI::Type.
|
22
|
+
|
23
|
+
== Give me a code sample already!
|
24
|
+
|
25
|
+
# connect to an in-memory sqlite3 database:
|
26
|
+
dbh = RDBI.connect(:SQLite3, :database => ":memory:")
|
27
|
+
|
28
|
+
# execute this CREATE TABLE statement:
|
29
|
+
dbh.execute("create table foo (bar integer, baz varchar)")
|
30
|
+
|
31
|
+
# prepare an insert statement for execution with two placeholders:
|
32
|
+
dbh.prepare("insert into foo (bar, baz) values (?, ?)") do |sth|
|
33
|
+
|
34
|
+
# and execute it with bound variables:
|
35
|
+
sth.execute(1, "foo")
|
36
|
+
sth.execute(2, "bar")
|
37
|
+
sth.execute(3, "quux")
|
38
|
+
end
|
39
|
+
|
40
|
+
# get a result handle from a select statement:
|
41
|
+
result = dbh.execute("select * from foo")
|
42
|
+
|
43
|
+
# and fetch the first row
|
44
|
+
result.fetch(:first) # [1, "foo"]
|
45
|
+
|
46
|
+
== What +is+ RDBI all about, anyway?
|
47
|
+
|
48
|
+
Here are some important pieces of information about RDBI that you may find
|
49
|
+
compelling (or off-putting. We're pragmatists.):
|
50
|
+
|
51
|
+
* RDBI is, at the time of this writing, fewer than 1000 lines of code.
|
52
|
+
* RDBI is light and fast. Eventually we will show you benchmarks.
|
53
|
+
* RDBI can be tested without a database, or even a database driver.
|
54
|
+
* RDBI is almost 100% thread-safe.
|
55
|
+
* RDBI can transform your results through a driver system. Want a CSV? Use the
|
56
|
+
CSV driver, don't bother transforming it yourself. Transform to JSON or YAML
|
57
|
+
with another gem. Drivers can be independently installed, used and swapped.
|
58
|
+
* RDBI contains no monkeypatching, core extensions, or other hell that will
|
59
|
+
conflict with your other libraries.
|
60
|
+
* RDBI is designed around properties of a relational database, but there is
|
61
|
+
nothing in it that demands one -- use it with Mongo or Redis if you want.
|
62
|
+
* RDBI database drivers are *small* -- our sqlite driver is about 150 lines and
|
63
|
+
our PostgreSQL driver is about 300. Our mock driver is about 50.
|
64
|
+
* RDBI has an active community of experienced Rails and Ruby programmers.
|
65
|
+
|
66
|
+
== I'd like some more, please.
|
67
|
+
|
68
|
+
# result objects are very flexible and amenable to method chaining:
|
69
|
+
dbh.execute("select * from foo").fetch(2) # [[1, "foo"], [2, "bar"]]
|
70
|
+
|
71
|
+
result = dbh.execute("select * from foo")
|
72
|
+
|
73
|
+
# select iteratively, then rewind to the first item:
|
74
|
+
result.fetch(2)
|
75
|
+
result.rewind
|
76
|
+
|
77
|
+
# change the way the results are presented:
|
78
|
+
result.as(:CSV).fetch(2) # '1,"foo"\n2,"bar"\n'
|
79
|
+
|
80
|
+
# :CSV is shorthand for RDBI::Result::Driver::CSV. you can also use literal
|
81
|
+
# class names:
|
82
|
+
result.as(RDBI::Result::Driver::CSV)
|
83
|
+
|
84
|
+
# or maybe your own:
|
85
|
+
result.as(MyCoolDriver)
|
86
|
+
|
87
|
+
# Here's another included driver:
|
88
|
+
str = result.as(:Struct).fetch(:first)
|
89
|
+
str.bar # 1
|
90
|
+
str.baz # "foo"
|
91
|
+
|
92
|
+
result.rewind
|
93
|
+
|
94
|
+
# select a single item in CSV format
|
95
|
+
csv = result.fetch(:first, :CSV)
|
96
|
+
|
97
|
+
# get the whole thing as an array of structs, keyed by column
|
98
|
+
ary_of_struct = result.as(:Struct).fetch(:all)
|
99
|
+
|
100
|
+
# as() automagically rewinds for you, so select twice for multi-dimension
|
101
|
+
# presentations:
|
102
|
+
ary = result.as(:Array).fetch(:all)
|
103
|
+
|
104
|
+
# and we're done! Disconnect from the database.
|
105
|
+
dbh.disconnect
|
106
|
+
|
107
|
+
Here are some things that it does:
|
108
|
+
|
109
|
+
* Connection pooling with aggregate transforms of your connections (that's a
|
110
|
+
fancy way of saying it uses Enumerable in the Pools). It can be responsible
|
111
|
+
for n segmented pools which relate to different logical databases.
|
112
|
+
* Native client binding *and* interpolated binding for databases that do not
|
113
|
+
support it.
|
114
|
+
* Don't like our drivers? No one's requiring you to use them -- RDBI drivers
|
115
|
+
aren't coupled with RDBI in any way.
|
116
|
+
* Result *drivers* can be used to transform your output into whatever you need --
|
117
|
+
never write a transformation skeleton again.
|
118
|
+
* Result *handles* can be used to work with results like real data structures.
|
119
|
+
Rewind them, ask the database to re-query the data, select a struct then select
|
120
|
+
an array (*without* requerying), select n items at a time as tuples (which
|
121
|
+
may be more than one or less than all).
|
122
|
+
* Cursors are used underneath the hood to ensure as performant a situation as
|
123
|
+
your database (and underlying driver) can provide.
|
124
|
+
* RDBI's core test suite passes in MRI 1.8, 1.9, and JRuby 1.5.
|
125
|
+
|
126
|
+
Aaaaaand here are some things RDBI won't do:
|
127
|
+
|
128
|
+
* RDBI won't write your queries for you. (There are libraries that use RDBI for
|
129
|
+
that.)
|
130
|
+
* RDBI won't dictate your schema.
|
131
|
+
* RDBI won't prevent you from being stupid or clever.
|
132
|
+
* It won't save you tons of time because you can't be bothered to think about
|
133
|
+
how you access your data.
|
134
|
+
* It won't make you (or anyone, really) a rockstar.
|
135
|
+
* Do not taunt RDBI.
|
136
|
+
|
137
|
+
== Show me even more awesome!
|
138
|
+
|
139
|
+
# retrieve cached handles 5 times -- handles will be yielded twice if there
|
140
|
+
# is a smaller Pool size:
|
141
|
+
5.times do
|
142
|
+
RDBI.connect_cached(:SQLite3, :database => ":memory:")
|
143
|
+
end
|
144
|
+
|
145
|
+
# omg! this handle is really already connected!
|
146
|
+
dbh = RDBI.connect_cached(:SQLite3, :database => ":memory:")
|
147
|
+
|
148
|
+
# finer-grained control via RDBI::Pool:
|
149
|
+
# 2 connections:
|
150
|
+
pool = RDBI::Pool.new("my_pool_name", [:SQLite3, :database => ":memory:"], 2)
|
151
|
+
|
152
|
+
# zomg!
|
153
|
+
dbh = pool.get_dbh
|
154
|
+
|
155
|
+
# oh lordy lord! still 2 connections
|
156
|
+
10.times { pool.get_dbh }
|
157
|
+
|
158
|
+
pool.disconnect # disconnect the entire pool
|
159
|
+
pool.reconnect # reconnect the entire pool
|
160
|
+
|
161
|
+
pool.resize(10) # resize the pool to 10 connections.
|
162
|
+
|
163
|
+
== Who is responsible for this madness?
|
164
|
+
|
165
|
+
* Erik Hollensbe (erikh)
|
166
|
+
* Pistos (... Pistos)
|
167
|
+
* Lee Jarvis (injekt)
|
168
|
+
* James Tucker (raggi)
|
169
|
+
|
170
|
+
== I found a bug!
|
171
|
+
|
172
|
+
We use the trackers in the github +RDBI+ project: http://github.com/RDBI for
|
173
|
+
each gem. Please find the appropriate place to add your ticket.
|
174
|
+
|
175
|
+
Not sure? Just add it to the +rdbi+ tracker: http://github.com/RDBI/rdbi/issues
|
176
|
+
|
177
|
+
== I'd like to patch and/or help maintain RDBI. How can I?
|
178
|
+
|
179
|
+
* Fork the project: http://github.com/RDBI
|
180
|
+
* Make your feature addition or bug fix.
|
181
|
+
* Please add tests for it, or indicate there are none. Patches without tests
|
182
|
+
will get integrated slower and must be very compelling.
|
183
|
+
* We use +jeweler+ for our repository management -- patches that mess with this
|
184
|
+
will be rejected regardless of merit.
|
185
|
+
* If you fork it permanently, be prepared to support it; we won't.
|
186
|
+
|
187
|
+
== Let's chat
|
188
|
+
|
189
|
+
* \#ruby-dbi on irc.freenode.net
|
190
|
+
* rdbi-devel@groups.google.com - for developers
|
191
|
+
|
192
|
+
== Copyright
|
193
|
+
|
194
|
+
Copyright (c) 2010 Erik Hollensbe. See LICENSE for details.
|
data/Rakefile
ADDED
@@ -0,0 +1,109 @@
|
|
1
|
+
require 'rubygems'
|
2
|
+
require 'rake'
|
3
|
+
|
4
|
+
version = (File.exist?('VERSION') ? File.read('VERSION') : "").chomp
|
5
|
+
|
6
|
+
begin
|
7
|
+
require 'jeweler'
|
8
|
+
Jeweler::Tasks.new do |gem|
|
9
|
+
gem.name = "rdbi"
|
10
|
+
gem.summary = %Q{RDBI provides sane query-level database access with low magic.}
|
11
|
+
gem.description = %Q{RDBI is a rearchitecture of the Ruby/DBI project by its maintainer and others. It intends to fully supplant Ruby/DBI in the future for similar database access needs.}
|
12
|
+
gem.email = "erik@hollensbe.org"
|
13
|
+
gem.homepage = "http://github.com/RDBI/rdbi"
|
14
|
+
gem.authors = ["Erik Hollensbe"]
|
15
|
+
|
16
|
+
gem.add_development_dependency 'rdbi-driver-mock'
|
17
|
+
gem.add_development_dependency 'test-unit'
|
18
|
+
gem.add_development_dependency 'rdoc'
|
19
|
+
## for now, install hanna from here: http://github.com/erikh/hanna
|
20
|
+
#gem.add_development_dependency 'hanna'
|
21
|
+
gem.add_development_dependency 'fastercsv'
|
22
|
+
|
23
|
+
gem.add_dependency 'methlab', '>= 0.0.9'
|
24
|
+
gem.add_dependency 'epoxy', '>= 0.3.1'
|
25
|
+
gem.add_dependency 'typelib'
|
26
|
+
|
27
|
+
# gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
|
28
|
+
end
|
29
|
+
Jeweler::GemcutterTasks.new
|
30
|
+
rescue LoadError
|
31
|
+
puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
|
32
|
+
end
|
33
|
+
|
34
|
+
begin
|
35
|
+
gem 'test-unit'
|
36
|
+
require 'rake/testtask'
|
37
|
+
Rake::TestTask.new(:test) do |test|
|
38
|
+
test.libs << 'lib' << 'test'
|
39
|
+
test.pattern = 'test/**/test_*.rb'
|
40
|
+
test.verbose = true
|
41
|
+
end
|
42
|
+
rescue LoadError
|
43
|
+
task :test do
|
44
|
+
abort "test-unit gem is not available. In order to run test-unit, you must: sudo gem install test-unit"
|
45
|
+
end
|
46
|
+
end
|
47
|
+
|
48
|
+
|
49
|
+
begin
|
50
|
+
require 'rcov/rcovtask'
|
51
|
+
Rcov::RcovTask.new do |test|
|
52
|
+
test.libs << 'test'
|
53
|
+
test.pattern = 'test/**/test_*.rb'
|
54
|
+
test.verbose = true
|
55
|
+
end
|
56
|
+
rescue LoadError
|
57
|
+
task :rcov do
|
58
|
+
abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
|
59
|
+
end
|
60
|
+
end
|
61
|
+
|
62
|
+
task :test => :check_dependencies
|
63
|
+
|
64
|
+
begin
|
65
|
+
require 'roodi'
|
66
|
+
require 'roodi_task'
|
67
|
+
RoodiTask.new do |t|
|
68
|
+
t.verbose = false
|
69
|
+
end
|
70
|
+
rescue LoadError
|
71
|
+
task :roodi do
|
72
|
+
abort "Roodi is not available. In order to run roodi, you must: sudo gem install roodi"
|
73
|
+
end
|
74
|
+
end
|
75
|
+
|
76
|
+
task :default => :test
|
77
|
+
|
78
|
+
begin
|
79
|
+
require 'hanna'
|
80
|
+
require 'rdoc/task'
|
81
|
+
RDoc::Task.new do |rdoc|
|
82
|
+
version = File.exist?('VERSION') ? File.read('VERSION') : ""
|
83
|
+
|
84
|
+
rdoc.options.push '-f', 'hanna'
|
85
|
+
rdoc.main = 'README.rdoc'
|
86
|
+
rdoc.rdoc_dir = 'rdoc'
|
87
|
+
rdoc.title = "RDBI #{version} Documentation"
|
88
|
+
rdoc.rdoc_files.include('README*')
|
89
|
+
rdoc.rdoc_files.include('lib/**/*.rb')
|
90
|
+
end
|
91
|
+
rescue LoadError => e
|
92
|
+
rdoc_missing = lambda do
|
93
|
+
abort "What, were you born in a barn? Install rdoc and hanna at http://github.com/raggi/hanna ."
|
94
|
+
end
|
95
|
+
task :rdoc, &rdoc_missing
|
96
|
+
task :clobber_rdoc, &rdoc_missing
|
97
|
+
end
|
98
|
+
|
99
|
+
task :to_blog => [:clobber_rdoc, :rdoc] do
|
100
|
+
sh "rm -fr $git/blog/content/docs/rdbi && mv doc $git/blog/content/docs/rdbi"
|
101
|
+
end
|
102
|
+
|
103
|
+
task :install => [:test, :build]
|
104
|
+
|
105
|
+
task :docview => [:rerdoc] do
|
106
|
+
sh "open rdoc/index.html"
|
107
|
+
end
|
108
|
+
|
109
|
+
# vim: syntax=ruby ts=2 et sw=2 sts=2
|
data/VERSION
ADDED
@@ -0,0 +1 @@
|
|
1
|
+
0.9.0
|
Binary file
|
@@ -0,0 +1,365 @@
|
|
1
|
+
\input texinfo
|
2
|
+
@setfilename external-api.texi
|
3
|
+
@settitle RDBI External API specification 1.0 draft
|
4
|
+
|
5
|
+
@copying
|
6
|
+
Copyright @copyright{} 2010 Erik Hollensbe. My dad can distribute this work
|
7
|
+
better than your dad.
|
8
|
+
@end copying
|
9
|
+
|
10
|
+
@titlepage
|
11
|
+
@title RDBI External API specification 1.0 draft
|
12
|
+
@author Erik Hollensbe <erik@@hollensbe.org>
|
13
|
+
@page
|
14
|
+
@vskip 0pt plus 1filll
|
15
|
+
@insertcopying
|
16
|
+
|
17
|
+
@end titlepage
|
18
|
+
|
19
|
+
@contents
|
20
|
+
@node Top
|
21
|
+
|
22
|
+
|
23
|
+
|
24
|
+
@chapter All Classes
|
25
|
+
|
26
|
+
|
27
|
+
|
28
|
+
@deftypemethod {All Classes} Boolean reload
|
29
|
+
this method will semantically refresh items, such as Schema objects or
|
30
|
+
rows, depending on the context of the object in question.
|
31
|
+
@end deftypemethod
|
32
|
+
|
33
|
+
|
34
|
+
|
35
|
+
@chapter module DBI
|
36
|
+
|
37
|
+
|
38
|
+
|
39
|
+
@deftypemethod DBI DBH connect (Class @var{klass}, Array @var{*args}, Proc @var{&block})
|
40
|
+
class is a ruby class which corresponds to the database driver. it is no longer
|
41
|
+
a string.
|
42
|
+
|
43
|
+
*args is a hash with parameter -> value associations, such as :host or
|
44
|
+
:username.
|
45
|
+
|
46
|
+
Optionally yields a block for usage, yields a freshly connected DBH.
|
47
|
+
@end deftypemethod
|
48
|
+
|
49
|
+
@deftypemethod DBI {Array of Class} drivers
|
50
|
+
accessor to get at known classes that can be used as drivers.
|
51
|
+
@end deftypemethod
|
52
|
+
|
53
|
+
@deftypemethod DBI DBH connect_cached (Class @var{klass}, Array @var{*args}, Proc @var{&block})
|
54
|
+
connect to a new resource if one is required (or desired, see below) with
|
55
|
+
similar parameters as connect().
|
56
|
+
|
57
|
+
additional arguments :pool_name and :pool_size can be used to define a
|
58
|
+
Pool (object, see below) which holds a specific subset of connected
|
59
|
+
database handles. Playing with the size here introduces the ability for
|
60
|
+
connect_cached to maintain a minimum number of connections which can be
|
61
|
+
re-used over the lifetime of a program.
|
62
|
+
@end deftypemethod
|
63
|
+
|
64
|
+
@deftypemethod DBI Pool pool (String @var{pool_name})
|
65
|
+
a pool as described above is an array of database handles. this returns
|
66
|
+
that data as a "Pool" object, with its own API. See later on in the
|
67
|
+
document.
|
68
|
+
@end deftypemethod
|
69
|
+
|
70
|
+
@deftypemethod DBI Pool all_connections
|
71
|
+
similar to pool(), this returns all the connections, but ignores pools.
|
72
|
+
@end deftypemethod
|
73
|
+
|
74
|
+
@deftypemethod DBI Integer ping (Class @var{klass}, Array @var{*args})
|
75
|
+
similar to connect(), this issues a ping to the databases. This may issue
|
76
|
+
a connect() before the ping() to do it properly depending on the database
|
77
|
+
implementation.
|
78
|
+
@end deftypemethod
|
79
|
+
|
80
|
+
@deftypemethod DBI Boolean reconnect_all
|
81
|
+
reconnects all the known database handles.
|
82
|
+
@end deftypemethod
|
83
|
+
|
84
|
+
@deftypemethod DBI DBH last_dbh
|
85
|
+
returns the last returned dbh from connect() or connect_cached()
|
86
|
+
|
87
|
+
this method, by definition, can be unpredictable in threaded environments.
|
88
|
+
@end deftypemethod
|
89
|
+
|
90
|
+
|
91
|
+
|
92
|
+
@chapter class DBH
|
93
|
+
|
94
|
+
|
95
|
+
|
96
|
+
@deftypemethod DBH NilClass transaction (Proc @var{&block})
|
97
|
+
opens a transaction and executes the statements in the block. Yields self.
|
98
|
+
@end deftypemethod
|
99
|
+
|
100
|
+
@deftypemethod DBH Schema table_schema (Symbol @var{table_name})
|
101
|
+
returns information about a specific table in a Schema object
|
102
|
+
@end deftypemethod
|
103
|
+
|
104
|
+
@deftypemethod DBH {Array of Schema} schema (Symbol @var{schema_name})
|
105
|
+
returns information about a specific schema, the current one if none is
|
106
|
+
specified.
|
107
|
+
@end deftypemethod
|
108
|
+
|
109
|
+
@deftypemethod DBH Boolean reconnect
|
110
|
+
reconnects to the database
|
111
|
+
@end deftypemethod
|
112
|
+
|
113
|
+
@deftypemethod DBH Integer ping
|
114
|
+
attempts to contact the database, measuring round-trip.
|
115
|
+
@end deftypemethod
|
116
|
+
|
117
|
+
@deftypemethod DBH Object driver
|
118
|
+
returns the underlying driver.
|
119
|
+
@end deftypemethod
|
120
|
+
|
121
|
+
@deftypemethod DBH String last_query
|
122
|
+
returns the last query executed or prepared.
|
123
|
+
@end deftypemethod
|
124
|
+
|
125
|
+
@deftypemethod DBH STH last_sth
|
126
|
+
returns the last statement handle prepared.
|
127
|
+
@end deftypemethod
|
128
|
+
|
129
|
+
@deftypemethod DBH Mutex mutex
|
130
|
+
returns the mutex for this database. thread management will be per-dbh.
|
131
|
+
@end deftypemethod
|
132
|
+
|
133
|
+
@deftypemethod DBH String preprocess_query (String @var{query})
|
134
|
+
preprocesses the query and returns what it would look like right before
|
135
|
+
it gets sent to the database.
|
136
|
+
@end deftypemethod
|
137
|
+
|
138
|
+
@deftypemethod DBH Boolean disconnect
|
139
|
+
disconnects from the database. returns success.
|
140
|
+
@end deftypemethod
|
141
|
+
|
142
|
+
@deftypemethod DBH Symbol bind_style ({Symbol of [native, preprocessed]} @var{style})
|
143
|
+
Accessor. Native style delegates to the underlying database connector. preprocessed
|
144
|
+
means we do it.
|
145
|
+
@end deftypemethod
|
146
|
+
|
147
|
+
|
148
|
+
|
149
|
+
@section Query Methods
|
150
|
+
these methods all optionally use a block and yield a result or sth depending
|
151
|
+
on context. Additionally in async environments, they return immediately,
|
152
|
+
the block being transformed into a callback which will yield when the query
|
153
|
+
completes.
|
154
|
+
|
155
|
+
|
156
|
+
@deftypemethod DBH STH prepare (String @var{query})
|
157
|
+
prepares a query for execution and returns a statement handle.
|
158
|
+
@end deftypemethod
|
159
|
+
|
160
|
+
@deftypemethod DBH Result execute (String @var{query}, Array @var{*binds})
|
161
|
+
executes a query and returns a result. If a block is not provided, an async
|
162
|
+
result will be provided which will slowly result in items being fetchable.
|
163
|
+
@end deftypemethod
|
164
|
+
|
165
|
+
|
166
|
+
|
167
|
+
@chapter class STH
|
168
|
+
|
169
|
+
|
170
|
+
@deftypemethod STH String query
|
171
|
+
accessor for the query that was used to generate this sth.
|
172
|
+
@end deftypemethod
|
173
|
+
|
174
|
+
@deftypemethod STH Result execute (Array @var{*binds})
|
175
|
+
executes the prepared statement. optionally yielding a result if block given.
|
176
|
+
@end deftypemethod
|
177
|
+
|
178
|
+
@deftypemethod STH Object driver
|
179
|
+
if any, returns the underlying statement handle from the database object.
|
180
|
+
@end deftypemethod
|
181
|
+
|
182
|
+
@deftypemethod STH Result last_result
|
183
|
+
Returns the last Result this prepared statement has yielded.
|
184
|
+
@end deftypemethod
|
185
|
+
|
186
|
+
@deftypemethod STH Boolean finish
|
187
|
+
finishes the statement
|
188
|
+
@end deftypemethod
|
189
|
+
|
190
|
+
@deftypemethod STH DBH dbh
|
191
|
+
returns the dbh this statement handle was created from.
|
192
|
+
@end deftypemethod
|
193
|
+
|
194
|
+
|
195
|
+
|
196
|
+
@chapter class Pool
|
197
|
+
|
198
|
+
|
199
|
+
|
200
|
+
@deftypemethod Pool Boolean reconnect
|
201
|
+
attempts to reconnect the entire pool of database connections.
|
202
|
+
@end deftypemethod
|
203
|
+
|
204
|
+
@deftypemethod Pool Integer ping
|
205
|
+
attempts to ping and average the response time of all database
|
206
|
+
connections.
|
207
|
+
@end deftypemethod
|
208
|
+
|
209
|
+
@deftypemethod Pool Boolean disconnect
|
210
|
+
disconnects all the database connections in the pool.
|
211
|
+
@end deftypemethod
|
212
|
+
|
213
|
+
|
214
|
+
|
215
|
+
@chapter class Result
|
216
|
+
|
217
|
+
|
218
|
+
|
219
|
+
@deftypemethod Result Boolean complete?
|
220
|
+
Always returns true in a sync environment. In an async environment, only
|
221
|
+
returns true if all result processing has been completed.
|
222
|
+
@end deftypemethod
|
223
|
+
|
224
|
+
@deftypemethod Result Boolean has_data?
|
225
|
+
Always returns true in a sync environment. In an async environment, only
|
226
|
+
returns true if there is outstanding data to fetch.
|
227
|
+
@end deftypemethod
|
228
|
+
|
229
|
+
@deftypemethod Result Boolean eof?
|
230
|
+
Returns true if all results have been fetched.
|
231
|
+
@end deftypemethod
|
232
|
+
|
233
|
+
@deftypemethod Result NilClass rewind
|
234
|
+
resets the fetch iterator to the beginning. See also: #reload.
|
235
|
+
@end deftypemethod
|
236
|
+
|
237
|
+
@deftypemethod Result Integer rows
|
238
|
+
If available, returns the number of rows in this result. Else, nil.
|
239
|
+
@end deftypemethod
|
240
|
+
|
241
|
+
@deftypemethod Result Array binds
|
242
|
+
accessor for the binds that created this method
|
243
|
+
@end deftypemethod
|
244
|
+
|
245
|
+
@deftypemethod Result NilClass as (Class @var{kind}, Array @var{*args})
|
246
|
+
Given a Class and arguments, uses it to interpret the array. The class is
|
247
|
+
constructed with the result object and the arguments provided at the end,
|
248
|
+
and then a method called fetch() is attempted with the row count.
|
249
|
+
|
250
|
+
Especially for specific class designations, (XML formatting is a good
|
251
|
+
example) output formats may not necessarily equate to a single row, in that
|
252
|
+
case, one "unit" should be returned from #fetch, and this entailings of
|
253
|
+
this unit should be specified in the driver.
|
254
|
+
|
255
|
+
If this this method is not called, fetch yields a standard array with type
|
256
|
+
converted items.
|
257
|
+
@end deftypemethod
|
258
|
+
|
259
|
+
@deftypemethod Result Object fetch (Integer @var{row_count})
|
260
|
+
fetches one item, or given an argument, @var{row_count} rows. If the
|
261
|
+
row_count is ":all", fetches all outstanding rows. See #as for how rows may
|
262
|
+
be interpreted.
|
263
|
+
@end deftypemethod
|
264
|
+
|
265
|
+
@deftypemethod Result {Array of Object} raw_fetch (Integer @var{row_count})
|
266
|
+
Raw fetch performs no conversions -- returns an array of objects yielding
|
267
|
+
whatever the underlying driver gave us.
|
268
|
+
@end deftypemethod
|
269
|
+
|
270
|
+
@deftypemethod Result Boolean finish
|
271
|
+
finishes the underlying statement handle and invalidates the data.
|
272
|
+
reloading will no longer be possible once this is called and should
|
273
|
+
raise (or maybe we should reprepare/execute?).
|
274
|
+
@end deftypemethod
|
275
|
+
|
276
|
+
@deftypemethod Result STH sth
|
277
|
+
returns the statement handle that yielded this result.
|
278
|
+
@end deftypemethod
|
279
|
+
|
280
|
+
@deftypemethod Result Schema schema
|
281
|
+
returns a Schema object that corresponds to the data in this result.
|
282
|
+
@end deftypemethod
|
283
|
+
|
284
|
+
@deftypemethod Result NilClass each (@var{&block})
|
285
|
+
similar to calling fetch iteratively with a callback. With proper async
|
286
|
+
driver support, will register a callback from the block which will only
|
287
|
+
process when there are new rows to be had.
|
288
|
+
@end deftypemethod
|
289
|
+
|
290
|
+
|
291
|
+
@chapter class CursorResult < Result
|
292
|
+
|
293
|
+
This class is just a cursor-oriented method of transmitting results.
|
294
|
+
|
295
|
+
|
296
|
+
|
297
|
+
@chapter class Row
|
298
|
+
|
299
|
+
row is just an array, but this needs to be thought out a little more.
|
300
|
+
|
301
|
+
|
302
|
+
|
303
|
+
@chapter Schema
|
304
|
+
|
305
|
+
|
306
|
+
|
307
|
+
@deftypemethod Schema {Array of Column} columns
|
308
|
+
returns column information (see Column object below) for all elements of
|
309
|
+
the Schema.
|
310
|
+
@end deftypemethod
|
311
|
+
|
312
|
+
@deftypemethod Schema {Array of Symbol} table_names
|
313
|
+
returns table names (there may be more than one in the event of a query
|
314
|
+
Schema) for all the objects a part of this Schema.
|
315
|
+
@end deftypemethod
|
316
|
+
|
317
|
+
|
318
|
+
|
319
|
+
@chapter Column
|
320
|
+
|
321
|
+
|
322
|
+
|
323
|
+
@deftypemethod Column String name
|
324
|
+
@end deftypemethod
|
325
|
+
|
326
|
+
@deftypemethod Column String type
|
327
|
+
this is the type the database yields
|
328
|
+
@end deftypemethod
|
329
|
+
|
330
|
+
@deftypemethod Column Class ruby_type
|
331
|
+
Accessor. this is what ruby thinks this type should be, or you can set it directly
|
332
|
+
which will be used at type conversion time.
|
333
|
+
@end deftypemethod
|
334
|
+
|
335
|
+
@deftypemethod Column Integer precision
|
336
|
+
(alias: length)
|
337
|
+
precision is the first number in a database type. it is aliased to the
|
338
|
+
method 'length' because sometimes that's what precision actually is
|
339
|
+
depending on the type.
|
340
|
+
@end deftypemethod
|
341
|
+
|
342
|
+
@deftypemethod Column Integer scale
|
343
|
+
scale is the second number in a database type. this is often the right
|
344
|
+
side of a decimal value or sometimes a factoring quotient.
|
345
|
+
@end deftypemethod
|
346
|
+
|
347
|
+
@deftypemethod Column Boolean nullable@?
|
348
|
+
can this column be null?
|
349
|
+
@end deftypemethod
|
350
|
+
|
351
|
+
@deftypemethod Column String metadata
|
352
|
+
metadata is a bucket for things we don't understand; namely things like AUTOINCREMENT.
|
353
|
+
@end deftypemethod
|
354
|
+
|
355
|
+
@deftypemethod Column String default
|
356
|
+
default is the column default -- this is provided for informational
|
357
|
+
aspects only and should not be used for anything sane.
|
358
|
+
@end deftypemethod
|
359
|
+
|
360
|
+
@page
|
361
|
+
@node Method Index
|
362
|
+
@unnumbered Method Index
|
363
|
+
@printindex fn
|
364
|
+
|
365
|
+
@bye
|