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