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
218:         def [] (attr)
219:             sanity_check
220:             @handle[attr]
221:         end

Set an attribute on the DatabaseHandle.

[Source]

     # File lib/dbi/handles/database.rb, line 224
224:         def []= (attr, val)
225:             sanity_check
226:             @handle[attr] = val
227:         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
159:         def columns( table )
160:             sanity_check
161:             @handle.columns( table ).collect {|col| ColumnInfo.new(col) }
162:         end

Force a commit to the database immediately.

[Source]

     # File lib/dbi/handles/database.rb, line 185
185:         def commit
186:             sanity_check
187:             @handle.commit
188:         end

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

[Source]

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

Return the name of the database we are connected to.

[Source]

     # File lib/dbi/handles/database.rb, line 141
141:         def database_name
142:             sanity_check
143:             @handle.database_name
144:         end

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

[Source]

    # File lib/dbi/handles/database.rb, line 40
40:         def disconnect
41:             sanity_check
42:             @handle.disconnect
43:             @handle = nil
44:         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
102:         def do(stmt, *bindvars)
103:             sanity_check(stmt)
104: 
105:             @last_statement = stmt
106:             @handle.do(stmt, *DBI::Utils::ConvParam.conv_param(driver_name, *bindvars))
107:         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
17:         def driver_name
18:             return @driver_name.dup if @driver_name
19:             return nil
20:         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
24:         def driver_name=(name)
25:             @driver_name = name
26:             @driver_name.freeze
27:         end

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

[Source]

    # File lib/dbi/handles/database.rb, line 73
73:         def execute(stmt, *bindvars)
74:             sanity_check(stmt)
75: 
76:             @last_statement = stmt
77:             if @convert_types
78:                 bindvars = DBI::Utils::ConvParam.conv_param(driver_name, *bindvars)
79:             end
80: 
81:             sth = StatementHandle.new(@handle.execute(stmt, *bindvars), true, true, @convert_types, true)
82:             # FIXME trace sth.trace(@trace_mode, @trace_output)
83:             sth.dbh = self
84:             sth.raise_error = raise_error
85: 
86:             if block_given?
87:                 begin
88:                     yield sth
89:                 ensure
90:                     sth.finish unless sth.finished?
91:                 end
92:             else
93:                 return sth
94:             end 
95:         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
169:         def ping
170:             sanity_check
171:             @handle.ping
172:         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
51:         def prepare(stmt)
52:             sanity_check(stmt)
53:             @last_statement = stmt
54:             sth = StatementHandle.new(@handle.prepare(stmt), false, true, @convert_types)
55:             # FIXME trace sth.trace(@trace_mode, @trace_output)
56:             sth.dbh = self
57:             sth.raise_error = raise_error
58: 
59:             if block_given?
60:                 begin
61:                     yield sth
62:                 ensure
63:                     sth.finish unless sth.finished?
64:                 end
65:             else
66:                 return sth
67:             end 
68:         end

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

[Source]

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

Force a rollback to the database immediately.

[Source]

     # File lib/dbi/handles/database.rb, line 193
193:         def rollback
194:             sanity_check
195:             @handle.rollback
196:         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
125:         def select_all(stmt, *bindvars, &p)
126:             sanity_check(stmt)
127:             rows = nil
128:             execute(stmt, *bindvars) do |sth|
129:                 if block_given?
130:                     sth.each(&p)
131:                 else
132:                     rows = sth.fetch_all 
133:                 end
134:             end
135:             return rows
136:         end

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

[Source]

     # File lib/dbi/handles/database.rb, line 112
112:         def select_one(stmt, *bindvars)
113:             sanity_check(stmt)
114:             row = nil
115:             execute(stmt, *bindvars) do |sth|
116:                 row = sth.fetch 
117:             end
118:             row
119:         end

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

[Source]

     # File lib/dbi/handles/database.rb, line 149
149:         def tables
150:             sanity_check
151:             @handle.tables
152:         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
203:         def transaction
204:             sanity_check
205:             raise InterfaceError, "No block given" unless block_given?
206: 
207:             commit
208:             begin
209:                 yield self
210:                 commit
211:             rescue Exception
212:                 rollback
213:                 raise
214:             end
215:         end

Protected Instance methods

basic sanity checks for statements

[Source]

     # File lib/dbi/handles/database.rb, line 237
237:         def check_statement(stmt)
238:             raise InterfaceError, "Statement is empty, or contains nothing but whitespace" if stmt !~ /\S/
239:         end

[Source]

     # File lib/dbi/handles/database.rb, line 231
231:         def sanity_check(stmt=nil)      
232:             raise InterfaceError, "Database connection was already closed!" if @handle.nil?
233:             check_statement(stmt) if stmt
234:         end

[Validate]