| Class | DBI::DatabaseHandle |
| In: |
lib/dbi/handles/database.rb
|
| Parent: | Handle |
DatabaseHandle is the interface the consumer sees after connecting to the database via DBI.connect.
It is strongly discouraged that DBDs inherit from this class directly; please inherit from the DBI::BaseDatabase instead.
Note: almost all methods in this class will raise InterfaceError if the database is not connected.
| last_statement | [RW] | |
| raise_error | [RW] |
Get an attribute from the DatabaseHandle.
# File lib/dbi/handles/database.rb, line 218
218: def [] (attr)
219: sanity_check
220: @handle[attr]
221: end
Set an attribute on the DatabaseHandle.
# File lib/dbi/handles/database.rb, line 224
224: def []= (attr, val)
225: sanity_check
226: @handle[attr] = val
227: end
Returns the columns of the provided table as an array of ColumnInfo objects. See BaseDatabase#columns for the minimum parameters that this method must provide.
# File lib/dbi/handles/database.rb, line 159
159: def columns( table )
160: sanity_check
161: @handle.columns( table ).collect {|col| ColumnInfo.new(col) }
162: end
Return the name of the database we are connected to.
# File lib/dbi/handles/database.rb, line 141
141: def database_name
142: sanity_check
143: @handle.database_name
144: end
Disconnect from the database. Will raise InterfaceError if this was already done prior.
# File lib/dbi/handles/database.rb, line 40
40: def disconnect
41: sanity_check
42: @handle.disconnect
43: @handle = nil
44: end
Perform a statement. This goes straight to the DBD‘s implementation of do (and consequently, BaseDatabase#do), and does not work like execute and prepare. Should return a row modified count.
# File lib/dbi/handles/database.rb, line 102
102: def do(stmt, *bindvars)
103: sanity_check(stmt)
104:
105: @last_statement = stmt
106: @handle.do(stmt, *DBI::Utils::ConvParam.conv_param(driver_name, *bindvars))
107: end
This is the driver name as supplied by the DBD‘s driver_name method. Its primary utility is in DBI::TypeUtil#convert.
# File lib/dbi/handles/database.rb, line 17
17: def driver_name
18: return @driver_name.dup if @driver_name
19: return nil
20: end
Assign the driver name. This can be leveraged to create custom type management via DBI::TypeUtil#convert.
# File lib/dbi/handles/database.rb, line 24
24: def driver_name=(name)
25: @driver_name = name
26: @driver_name.freeze
27: end
Prepare and execute a statement. It has block semantics equivalent to prepare.
# File lib/dbi/handles/database.rb, line 73
73: def execute(stmt, *bindvars)
74: sanity_check(stmt)
75:
76: @last_statement = stmt
77: if @convert_types
78: bindvars = DBI::Utils::ConvParam.conv_param(driver_name, *bindvars)
79: end
80:
81: sth = StatementHandle.new(@handle.execute(stmt, *bindvars), true, true, @convert_types, true)
82: # FIXME trace sth.trace(@trace_mode, @trace_output)
83: sth.dbh = self
84: sth.raise_error = raise_error
85:
86: if block_given?
87: begin
88: yield sth
89: ensure
90: sth.finish unless sth.finished?
91: end
92: else
93: return sth
94: end
95: end
Attempt to establish if the database is still connected. While connected? returns the state the DatabaseHandle thinks is true, this is an active operation that will contact the database.
# File lib/dbi/handles/database.rb, line 169
169: def ping
170: sanity_check
171: @handle.ping
172: end
Prepare a StatementHandle and return it. If given a block, it will supply that StatementHandle as the first argument to the block, and BaseStatement#finish it when the block is done executing.
# File lib/dbi/handles/database.rb, line 51
51: def prepare(stmt)
52: sanity_check(stmt)
53: @last_statement = stmt
54: sth = StatementHandle.new(@handle.prepare(stmt), false, true, @convert_types)
55: # FIXME trace sth.trace(@trace_mode, @trace_output)
56: sth.dbh = self
57: sth.raise_error = raise_error
58:
59: if block_given?
60: begin
61: yield sth
62: ensure
63: sth.finish unless sth.finished?
64: end
65: else
66: return sth
67: end
68: end
Executes a statement and returns all rows from the result. If a block is given, it is executed for each row.
# File lib/dbi/handles/database.rb, line 125
125: def select_all(stmt, *bindvars, &p)
126: sanity_check(stmt)
127: rows = nil
128: execute(stmt, *bindvars) do |sth|
129: if block_given?
130: sth.each(&p)
131: else
132: rows = sth.fetch_all
133: end
134: end
135: return rows
136: end
Executes a statement and returns the first row from the result.
# File lib/dbi/handles/database.rb, line 112
112: def select_one(stmt, *bindvars)
113: sanity_check(stmt)
114: row = nil
115: execute(stmt, *bindvars) do |sth|
116: row = sth.fetch
117: end
118: row
119: end
Return the tables available to this DatabaseHandle as an array of strings.
# File lib/dbi/handles/database.rb, line 149
149: def tables
150: sanity_check
151: @handle.tables
152: end
Commits, runs the block provided, yielding the DatabaseHandle as it‘s argument. If an exception is raised through the block, rollback occurs. Otherwise, commit occurs.
# File lib/dbi/handles/database.rb, line 203
203: def transaction
204: sanity_check
205: raise InterfaceError, "No block given" unless block_given?
206:
207: commit
208: begin
209: yield self
210: commit
211: rescue Exception
212: rollback
213: raise
214: end
215: end
basic sanity checks for statements
# File lib/dbi/handles/database.rb, line 237
237: def check_statement(stmt)
238: raise InterfaceError, "Statement is empty, or contains nothing but whitespace" if stmt !~ /\S/
239: end