Class: RDBI::Statement

Inherits:
Object
  • Object
show all
Defined in:
lib/rdbi/statement.rb

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(query, dbh) ⇒ Statement

Initialize a statement handle, given a text query and the RDBI::Database handle that created it.



141
142
143
144
145
146
147
148
149
 
# File 'lib/rdbi/statement.rb', line 141

def initialize(query, dbh)
  @query                 = query
  @dbh                   = dbh
  @finished              = false
  @input_type_map        = self.class.input_type_map
  @finish_block          = nil

  self.rewindable_result = dbh.rewindable_result
end

Instance Attribute Details

#dbh ⇒ Object (readonly)

the RDBI::Database handle that created this statement.



90
91
92
 
# File 'lib/rdbi/statement.rb', line 90

def dbh
  @dbh
end

#finished ⇒ Object (readonly) Also known as: finished?

Has this statement been finished?



123
124
125
 
# File 'lib/rdbi/statement.rb', line 123

def finished
  @finished
end

#input_type_map ⇒ Object (readonly)

The input type map provided during statement creation – used for binding.



94
95
96
 
# File 'lib/rdbi/statement.rb', line 94

def input_type_map
  @input_type_map
end

#last_result ⇒ Object

:attr_reader: last_result

The last RDBI::Result this statement yielded.



100
101
102
 
# File 'lib/rdbi/statement.rb', line 100

def last_result
  @last_result
end

#query ⇒ Object (readonly)

The query this statement was created for.



92
93
94
 
# File 'lib/rdbi/statement.rb', line 92

def query
  @query
end

#rewindable_result ⇒ Object

:attr_reader: rewindable_result

Allows the user to request a fully rewindable result, allowing the use of fetching the last item, direct indexing, and rewinding.

This can be a huge performance impact and thus should be used with great caution.

Cascades from RDBI::Database#rewindable_result and through RDBI::Result#rewindable_result.



114
115
116
 
# File 'lib/rdbi/statement.rb', line 114

def rewindable_result
  @rewindable_result
end

Class Method Details

.input_type_map ⇒ Object 



132
133
134
 
# File 'lib/rdbi/statement.rb', line 132

def input_type_map
  @input_type_map ||= RDBI::Type.create_type_hash(RDBI::Type::In)
end

Instance Method Details

#driver ⇒ Object

The RDBI::Driver object that this statement belongs to.



127
128
129
 
# File 'lib/rdbi/statement.rb', line 127

def driver
  dbh.driver
end

#execute(*binds) ⇒ Object

Execute the statement with the supplied binds.



163
164
165
166
167
168
169
170
171
 
# File 'lib/rdbi/statement.rb', line 163

def execute(*binds)
  binds = pre_execute(*binds)

  cursor, schema, type_map = new_execution(*binds)
  cursor.rewindable_result = self.rewindable_result
  r = RDBI::Result.new(self, binds, cursor, schema, type_map)
  self.last_result = ::WeakRef.new(r)
  r
end

#execute_modification(*binds) ⇒ Object

Execute the statement with the supplied binds. Intended for DDL and other statements which return no rows (e.g., INSERT, DELETE).



177
178
179
180
181
 
# File 'lib/rdbi/statement.rb', line 177

def execute_modification(*binds)
  binds = pre_execute(*binds)

  return new_modification(*binds)
end

#finish ⇒ Object

Deallocate any internal resources devoted to the statement. It will not be usable after this is called.

Driver implementors will want to subclass this, do their thing and call ‘super’ as their last statement.



190
191
192
193
194
 
# File 'lib/rdbi/statement.rb', line 190

def finish
  @finish_block.call if @finish_block
  @dbh.open_statements.delete(self.object_id)
  @finished = true
end

#new_execution ⇒ Object

:method: new_execution :call-seq: new_execution(*binds)

Database drivers will override this method in their respective RDBI::Statement subclasses. This method is called when RDBI::Statement#execute or RDBI::Database#execute is called.

Implementations of this method must return, in order:

  • A RDBI::Cursor object which encapsulates the result

  • a RDBI::Schema struct which represents the kinds of data being queried

  • a type_hash for on-fetch conversion which corresponds to the RDBI::Column information (see RDBI::Schema) and follows a structure similar to RDBI::Type::Out

These return values are passed (along with this object and the binds passed to this call) to RDBI::Result.new.

Raises:

  • (NoMethodError) 


216
217
218
 
# File 'lib/rdbi/statement.rb', line 216

def new_execution
  raise NoMethodError, "this method is not implemented in this driver"
end

#new_modification(*binds) ⇒ Object

Executes the statement, returning the number of rows affected.

Database drivers may override this method in their Statement subclasses for efficiency. This method is called when #execute_modification() is called for an RDBI::Statement or RDBI::Database object.



229
230
231
232
 
# File 'lib/rdbi/statement.rb', line 229

def new_modification(*binds)
  cursor = new_execution(*binds)[0]
  cursor.affected_count
end

#prep_finalizer(&block) ⇒ Object 



151
152
153
154
155
156
157
158
 
# File 'lib/rdbi/statement.rb', line 151

def prep_finalizer(&block)
  if block
    @finish_block = block
    ObjectSpace.define_finalizer(self, lambda do |x| 
      block.call
    end)
  end
end