Class: DBI::DatabaseHandle

Inherits:
Handle
  • Object
show all
Defined in:
lib/dbi/handles/database.rb

Overview

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.

Instance Attribute Summary collapse

Attributes inherited from Handle

#convert_types, #handle, #trace_mode, #trace_output

Instance Method Summary collapse

Methods inherited from Handle

#func, #initialize, #trace

Constructor Details

This class inherits a constructor from DBI::Handle

Instance Attribute Details

#last_statement ⇒ Object

Returns the value of attribute last_statement.



12
13
14
 
# File 'lib/dbi/handles/database.rb', line 12

def last_statement
  @last_statement
end

#raise_error ⇒ Object

Returns the value of attribute raise_error.



13
14
15
 
# File 'lib/dbi/handles/database.rb', line 13

def raise_error
  @raise_error
end

Instance Method Details

#[](attr) ⇒ Object

Get an attribute from the DatabaseHandle.



218
219
220
221
 
# File 'lib/dbi/handles/database.rb', line 218

def [] (attr)
    sanity_check
    @handle[attr]
end

#[]=(attr, val) ⇒ Object

Set an attribute on the DatabaseHandle.



224
225
226
227
 
# File 'lib/dbi/handles/database.rb', line 224

def []= (attr, val)
    sanity_check
    @handle[attr] = val
end

#columns(table) ⇒ Object

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.



159
160
161
162
 
# File 'lib/dbi/handles/database.rb', line 159

def columns( table )
    sanity_check
    @handle.columns( table ).collect {|col| ColumnInfo.new(col) }
end

#commit ⇒ Object

Force a commit to the database immediately.



185
186
187
188
 
# File 'lib/dbi/handles/database.rb', line 185

def commit
    sanity_check
    @handle.commit
end

#connected? ⇒ Boolean

Boolean if we are still connected to the database. See #ping.

Returns:

  • (Boolean) 


32
33
34
 
# File 'lib/dbi/handles/database.rb', line 32

def connected?
    not @handle.nil?
end

#database_name ⇒ Object

Return the name of the database we are connected to.



141
142
143
144
 
# File 'lib/dbi/handles/database.rb', line 141

def database_name
    sanity_check
    @handle.database_name
end

#disconnect ⇒ Object

Disconnect from the database. Will raise InterfaceError if this was already done prior.



40
41
42
43
44
 
# File 'lib/dbi/handles/database.rb', line 40

def disconnect
    sanity_check
    @handle.disconnect
    @handle = nil
end

#do(stmt, *bindvars) ⇒ Object

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.



102
103
104
105
106
107
 
# 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 ⇒ Object

This is the driver name as supplied by the DBD’s driver_name method. Its primary utility is in DBI::TypeUtil#convert.



17
18
19
20
 
# File 'lib/dbi/handles/database.rb', line 17

def driver_name
    return @driver_name.dup if @driver_name
    return nil
end

#driver_name=(name) ⇒ Object

Assign the driver name. This can be leveraged to create custom type management via DBI::TypeUtil#convert.



24
25
26
27
 
# File 'lib/dbi/handles/database.rb', line 24

def driver_name=(name)
    @driver_name = name
    @driver_name.freeze
end

#execute(stmt, *bindvars) ⇒ Object

Prepare and execute a statement. It has block semantics equivalent to #prepare.



73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
 
# 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 ⇒ Object

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.



169
170
171
172
 
# File 'lib/dbi/handles/database.rb', line 169

def ping
    sanity_check
    @handle.ping
end

#prepare(stmt) ⇒ Object

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.



51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
 
# 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) ⇒ Object

Attempt to escape the value, rendering it suitable for inclusion in a SQL statement.



177
178
179
180
 
# File 'lib/dbi/handles/database.rb', line 177

def quote(value)
    sanity_check
    @handle.quote(value)
end

#rollback ⇒ Object

Force a rollback to the database immediately.



193
194
195
196
 
# File 'lib/dbi/handles/database.rb', line 193

def rollback
    sanity_check
    @handle.rollback
end

#select_all(stmt, *bindvars, &p) ⇒ Object

Executes a statement and returns all rows from the result. If a block is given, it is executed for each row.



125
126
127
128
129
130
131
132
133
134
135
136
 
# 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) ⇒ Object

Executes a statement and returns the first row from the result.



112
113
114
115
116
117
118
119
 
# 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 ⇒ Object

Return the tables available to this DatabaseHandle as an array of strings.



149
150
151
152
 
# File 'lib/dbi/handles/database.rb', line 149

def tables
    sanity_check
    @handle.tables
end

#transaction ⇒ Object

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.

Raises:



203
204
205
206
207
208
209
210
211
212
213
214
215
 
# 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