class DBI::DatabaseHandle
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.
Attributes
Public Instance Methods
Get an attribute from the DatabaseHandle.
# File lib/dbi/handles/database.rb, line 218 def [] (attr) sanity_check @handle[attr] end
Set an attribute on the DatabaseHandle.
# File lib/dbi/handles/database.rb, line 224 def []= (attr, val) sanity_check @handle[attr] = val end
Returns the columns of the provided table as an array of ColumnInfo objects. See DBI::BaseDatabase#columns for the minimum parameters that this method must provide.
# File lib/dbi/handles/database.rb, line 159 def columns( table ) sanity_check @handle.columns( table ).collect {|col| ColumnInfo.new(col) } end
Force a commit to the database immediately.
# File lib/dbi/handles/database.rb, line 185 def commit sanity_check @handle.commit end
Boolean if we are still connected to the database. See ping.
# File lib/dbi/handles/database.rb, line 32 def connected? not @handle.nil? end
Return the name of the database we are connected to.
# File lib/dbi/handles/database.rb, line 141 def database_name sanity_check @handle.database_name end
Disconnect from the database. Will raise InterfaceError if this was already done prior.
# File lib/dbi/handles/database.rb, line 40 def disconnect sanity_check @handle.disconnect @handle = nil end
Perform a statement. This goes straight to the DBD's implementation of do (and consequently, DBI::BaseDatabase#do), and does not work like execute and prepare. Should return a row modified count.
# File lib/dbi/handles/database.rb, line 102 def do(stmt, *bindvars) sanity_check(stmt) @last_statement = stmt @handle.do(stmt, *DBI::Utils::ConvParam.conv_param(driver_name, *bindvars)) 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 def driver_name return @driver_name.dup if @driver_name return nil 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 def driver_name=(name) @driver_name = name @driver_name.freeze end
Prepare and execute a statement. It has block semantics equivalent to prepare.
# File lib/dbi/handles/database.rb, line 73 def execute(stmt, *bindvars) sanity_check(stmt) @last_statement = stmt if @convert_types bindvars = DBI::Utils::ConvParam.conv_param(driver_name, *bindvars) end sth = StatementHandle.new(@handle.execute(stmt, *bindvars), true, true, @convert_types, true) # FIXME trace sth.trace(@trace_mode, @trace_output) sth.dbh = self sth.raise_error = raise_error if block_given? begin yield sth ensure sth.finish unless sth.finished? end else return sth end 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 def ping sanity_check @handle.ping end
Prepare a StatementHandle and return it. If given a block, it will supply that StatementHandle as the first argument to the block, and DBI::BaseStatement#finish it when the block is done executing.
# File lib/dbi/handles/database.rb, line 51 def prepare(stmt) sanity_check(stmt) @last_statement = stmt sth = StatementHandle.new(@handle.prepare(stmt), false, true, @convert_types) # FIXME trace sth.trace(@trace_mode, @trace_output) sth.dbh = self sth.raise_error = raise_error if block_given? begin yield sth ensure sth.finish unless sth.finished? end else return sth end end
Attempt to escape the value, rendering it suitable for inclusion in a SQL statement.
# File lib/dbi/handles/database.rb, line 177 def quote(value) sanity_check @handle.quote(value) end
Force a rollback to the database immediately.
# File lib/dbi/handles/database.rb, line 193 def rollback sanity_check @handle.rollback 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 def select_all(stmt, *bindvars, &p) sanity_check(stmt) rows = nil execute(stmt, *bindvars) do |sth| if block_given? sth.each(&p) else rows = sth.fetch_all end end return rows end
Executes a statement and returns the first row from the result.
# File lib/dbi/handles/database.rb, line 112 def select_one(stmt, *bindvars) sanity_check(stmt) row = nil execute(stmt, *bindvars) do |sth| row = sth.fetch end row end
Return the tables available to this DatabaseHandle as an array of strings.
# File lib/dbi/handles/database.rb, line 149 def tables sanity_check @handle.tables 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 def transaction sanity_check raise InterfaceError, "No block given" unless block_given? commit begin yield self commit rescue Exception rollback raise end end
Protected Instance Methods
basic sanity checks for statements
# File lib/dbi/handles/database.rb, line 237 def check_statement(stmt) raise InterfaceError, "Statement is empty, or contains nothing but whitespace" if stmt !~ /\S/ end
# File lib/dbi/handles/database.rb, line 231 def sanity_check(stmt=nil) raise InterfaceError, "Database connection was already closed!" if @handle.nil? check_statement(stmt) if stmt end