Parent

Files

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

last_statement[RW]
raise_error[RW]

Public Instance Methods

[](attr) click to toggle source

Get an attribute from the DatabaseHandle.

# File lib/dbi/handles/database.rb, line 218
def [] (attr)
    sanity_check
    @handle[attr]
end
[]=(attr, val) click to toggle source

Set an attribute on the DatabaseHandle.

# File lib/dbi/handles/database.rb, line 224
def []= (attr, val)
    sanity_check
    @handle[attr] = val
end
columns( table ) click to toggle source

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
def columns( table )
    sanity_check
    @handle.columns( table ).collect {|col| ColumnInfo.new(col) }
end
commit() click to toggle source

Force a commit to the database immediately.

# File lib/dbi/handles/database.rb, line 185
def commit
    sanity_check
    @handle.commit
end
connected?() click to toggle source

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
database_name() click to toggle source

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() click to toggle source

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
do(stmt, *bindvars) click to toggle source

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
def do(stmt, *bindvars)
    sanity_check(stmt)

    @last_statement = stmt
    @handle.do(stmt, *DBI::Utils::ConvParam.conv_param(driver_name, *bindvars))
end
driver_name() click to toggle source

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
driver_name=(name) click to toggle source

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
execute(stmt, *bindvars) click to toggle source

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
ping() click to toggle source

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(stmt) click to toggle source

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
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
quote(value) click to toggle source

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
rollback() click to toggle source

Force a rollback to the database immediately.

# File lib/dbi/handles/database.rb, line 193
def rollback
    sanity_check
    @handle.rollback
end
select_all(stmt, *bindvars, &p) click to toggle source

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
select_one(stmt, *bindvars) click to toggle source

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
tables() click to toggle source

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
transaction() click to toggle source

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

check_statement(stmt) click to toggle source

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
sanity_check(stmt=nil) click to toggle source
# 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

[Validate]

Generated with the Darkfish Rdoc Generator 2.