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

#raise_error ⇒ Object

Returns the value of attribute raise_error.



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

def raise_error
  @raise_error
end

Instance Method Details

#[](attr) ⇒ Object

Get an attribute from the DatabaseHandle.



206
207
208
209
 
# File 'lib/dbi/handles/database.rb', line 206

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

#[]=(attr, val) ⇒ Object

Set an attribute on the DatabaseHandle.



212
213
214
215
 
# File 'lib/dbi/handles/database.rb', line 212

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.



147
148
149
150
 
# File 'lib/dbi/handles/database.rb', line 147

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

#commit ⇒ Object

Force a commit to the database immediately.



173
174
175
176
 
# File 'lib/dbi/handles/database.rb', line 173

def commit
  sanity_check
  @handle.commit
end

#connected? ⇒ Boolean

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

Returns:

  • (Boolean) 


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

def connected?
  not @handle.nil?
end

#disconnect ⇒ Object

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



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

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.



99
100
101
102
103
 
# File 'lib/dbi/handles/database.rb', line 99

def do(stmt, bindvars={})
  sanity_check(stmt)
  @handle.do(stmt, bindvars)
  #@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.



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

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.



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

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.



71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
 
# File 'lib/dbi/handles/database.rb', line 71

def execute(stmt, bindvars={})
  sanity_check(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.



157
158
159
160
 
# File 'lib/dbi/handles/database.rb', line 157

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.



50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
 
# File 'lib/dbi/handles/database.rb', line 50

def prepare(stmt)
  sanity_check(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.



165
166
167
168
 
# File 'lib/dbi/handles/database.rb', line 165

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

#rollback ⇒ Object

Force a rollback to the database immediately.



181
182
183
184
 
# File 'lib/dbi/handles/database.rb', line 181

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.



121
122
123
124
125
126
127
128
129
130
131
132
 
# File 'lib/dbi/handles/database.rb', line 121

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.



108
109
110
111
112
113
114
115
 
# File 'lib/dbi/handles/database.rb', line 108

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.



137
138
139
140
 
# File 'lib/dbi/handles/database.rb', line 137

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:



191
192
193
194
195
196
197
198
199
200
201
202
203
 
# File 'lib/dbi/handles/database.rb', line 191

def transaction
  sanity_check
  raise InterfaceError, "No block given" unless block_given?

  commit
  begin
    yield self
    commit
  rescue Exception
    rollback
    raise
  end
end