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.

Methods

Attributes

last_statement  [RW] 
raise_error  [RW] 

Public Instance methods

Get an attribute from the DatabaseHandle.

[Source]

# File lib/dbi/handles/database.rb, line 218
        def [] (attr)
            sanity_check
            @handle[attr]
        end

Set an attribute on the DatabaseHandle.

[Source]

# 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 BaseDatabase#columns for the minimum parameters that this method must provide.

[Source]

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

[Source]

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

[Source]

# File lib/dbi/handles/database.rb, line 32
        def connected?
            not @handle.nil?
        end

Return the name of the database we are connected to.

[Source]

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

[Source]

# 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, BaseDatabase#do), and does not work like execute and prepare. Should return a row modified count.

[Source]

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

[Source]

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

[Source]

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

[Source]

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

[Source]

# 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 BaseStatement#finish it when the block is done executing.

[Source]

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

[Source]

# File lib/dbi/handles/database.rb, line 177
        def quote(value)
            sanity_check
            @handle.quote(value)
        end

Force a rollback to the database immediately.

[Source]

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

[Source]

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

[Source]

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

[Source]

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

[Source]

# 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

[Source]

# 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

[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]