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.
raise_error | [RW] |
Get an attribute from the DatabaseHandle.
# File lib/dbi/handles/database.rb, line 206 206: def [] (attr) 207: sanity_check 208: @handle[attr] 209: end
Set an attribute on the DatabaseHandle.
# File lib/dbi/handles/database.rb, line 212 212: def []= (attr, val) 213: sanity_check 214: @handle[attr] = val 215: 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 147 147: def columns( table ) 148: sanity_check 149: @handle.columns( table ).collect {|col| ColumnInfo.new(col) } 150: end
Disconnect from the database. Will raise InterfaceError if this was already done prior.
# File lib/dbi/handles/database.rb, line 39 39: def disconnect 40: sanity_check 41: @handle.disconnect 42: @handle = nil 43: 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 99 99: def do(stmt, *bindvars) 100: sanity_check(stmt) 101: 102: @handle.do(stmt, *DBI::Utils::ConvParam.conv_param(driver_name, *bindvars)) 103: 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 16 16: def driver_name 17: return @driver_name.dup if @driver_name 18: return nil 19: 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 23 23: def driver_name=(name) 24: @driver_name = name 25: @driver_name.freeze 26: end
Prepare and execute a statement. It has block semantics equivalent to prepare.
# File lib/dbi/handles/database.rb, line 71 71: def execute(stmt, *bindvars) 72: sanity_check(stmt) 73: 74: if @convert_types 75: bindvars = DBI::Utils::ConvParam.conv_param(driver_name, *bindvars) 76: end 77: 78: sth = StatementHandle.new(@handle.execute(stmt, *bindvars), true, true, @convert_types, true) 79: # FIXME trace sth.trace(@trace_mode, @trace_output) 80: sth.dbh = self 81: sth.raise_error = raise_error 82: 83: if block_given? 84: begin 85: yield sth 86: ensure 87: sth.finish unless sth.finished? 88: end 89: else 90: return sth 91: end 92: 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 157 157: def ping 158: sanity_check 159: @handle.ping 160: 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 50 50: def prepare(stmt) 51: sanity_check(stmt) 52: sth = StatementHandle.new(@handle.prepare(stmt), false, true, @convert_types) 53: # FIXME trace sth.trace(@trace_mode, @trace_output) 54: sth.dbh = self 55: sth.raise_error = raise_error 56: 57: if block_given? 58: begin 59: yield sth 60: ensure 61: sth.finish unless sth.finished? 62: end 63: else 64: return sth 65: end 66: 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 121 121: def select_all(stmt, *bindvars, &p) 122: sanity_check(stmt) 123: rows = nil 124: execute(stmt, *bindvars) do |sth| 125: if block_given? 126: sth.each(&p) 127: else 128: rows = sth.fetch_all 129: end 130: end 131: return rows 132: end
Executes a statement and returns the first row from the result.
# File lib/dbi/handles/database.rb, line 108 108: def select_one(stmt, *bindvars) 109: sanity_check(stmt) 110: row = nil 111: execute(stmt, *bindvars) do |sth| 112: row = sth.fetch 113: end 114: row 115: end
Return the tables available to this DatabaseHandle as an array of strings.
# File lib/dbi/handles/database.rb, line 137 137: def tables 138: sanity_check 139: @handle.tables 140: 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 191 191: def transaction 192: sanity_check 193: raise InterfaceError, "No block given" unless block_given? 194: 195: commit 196: begin 197: yield self 198: commit 199: rescue Exception 200: rollback 201: raise 202: end 203: end
basic sanity checks for statements
# File lib/dbi/handles/database.rb, line 225 225: def check_statement(stmt) 226: raise InterfaceError, "Statement is empty, or contains nothing but whitespace" if stmt !~ /\S/ 227: end