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

raise_error  [RW] 

Public Instance methods

Get an attribute from the DatabaseHandle.

[Source]

     # File lib/dbi/handles/database.rb, line 206
206:         def [] (attr)
207:             sanity_check
208:             @handle[attr]
209:         end

Set an attribute on the DatabaseHandle.

[Source]

     # File lib/dbi/handles/database.rb, line 212
212:         def []= (attr, val)
213:             sanity_check
214:             @handle[attr] = val
215:         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 147
147:         def columns( table )
148:             sanity_check
149:             @handle.columns( table ).collect {|col| ColumnInfo.new(col) }
150:         end

Force a commit to the database immediately.

[Source]

     # File lib/dbi/handles/database.rb, line 173
173:         def commit
174:             sanity_check
175:             @handle.commit
176:         end

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

[Source]

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

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

[Source]

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

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

[Source]

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

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

[Source]

     # File lib/dbi/handles/database.rb, line 165
165:         def quote(value)
166:             sanity_check
167:             @handle.quote(value)
168:         end

Force a rollback to the database immediately.

[Source]

     # File lib/dbi/handles/database.rb, line 181
181:         def rollback
182:             sanity_check
183:             @handle.rollback
184:         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 121
121:         def select_all(stmt, *bindvars, &p)
122:             sanity_check(stmt)
123:             rows = nil
124:             execute(stmt, *bindvars) do |sth|
125:                 if block_given?
126:                     sth.each(&p)
127:                 else
128:                     rows = sth.fetch_all 
129:                 end
130:             end
131:             return rows
132:         end

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

[Source]

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

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

[Source]

     # File lib/dbi/handles/database.rb, line 137
137:         def tables
138:             sanity_check
139:             @handle.tables
140:         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 191
191:         def transaction
192:             sanity_check
193:             raise InterfaceError, "No block given" unless block_given?
194: 
195:             commit
196:             begin
197:                 yield self
198:                 commit
199:             rescue Exception
200:                 rollback
201:                 raise
202:             end
203:         end

Protected Instance methods

basic sanity checks for statements

[Source]

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

[Source]

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

[Validate]