Class: DBI::DatabaseHandle

### Home Classes Methods

### In Files

- lib/dbi/handles/database.rb

### Parent

Handle

### Methods

- #[]
- #[]=
- #check_statement
- #columns
- #commit
- #connected?
- #database_name
- #disconnect
- #do
- #driver_name
- #driver_name=
- #execute
- #ping
- #prepare
- #quote
- #rollback
- #sanity_check
- #select_all
- #select_one
- #tables
- #transaction

### Files

- ChangeLog
- LICENSE
- README

### Class/Module Index

Quicksearch

- DBI
- DBI::BaseDatabase
- DBI::BaseDriver
- DBI::BaseStatement
- DBI::Binary
- DBI::ColumnInfo
- DBI::DataError
- DBI::DatabaseError
- DBI::DatabaseHandle
- DBI::Date
- DBI::DriverHandle
- DBI::Error
- DBI::Handle
- DBI::HandleTracer
- DBI::IntegrityError
- DBI::InterfaceError
- DBI::InternalError
- DBI::NotImplementedError
- DBI::NotSupportedError
- DBI::OperationalError
- DBI::ProgrammingError
- DBI::Row
- DBI::SQL
- DBI::SQL::PreparedStatement
- DBI::StatementHandle
- DBI::Time
- DBI::Timestamp
- DBI::Type
- DBI::Type::Boolean
- DBI::Type::Decimal
- DBI::Type::Float
- DBI::Type::Integer
- DBI::Type::Null
- DBI::Type::Timestamp
- DBI::Type::Varchar
- DBI::TypeUtil
- DBI::Utils
- DBI::Utils::ConvParam
- DBI::Utils::TableFormatter
- DBI::Utils::XMLFormatter
- DBI::Warning
- Class

No matching classes.

# 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.