Class SQLite3::Statement
In: lib/sqlite3/statement.rb
Parent: Object

A statement represents a prepared-but-unexecuted SQL query. It will rarely (if ever) be instantiated directly by a client, and is most often obtained via the Database#prepare method.

Methods

active?   bind_param   bind_params   close   closed?   columns   execute   execute!   new   reset!   types  

Attributes

handle  [R]  The underlying opaque handle used to access the SQLite @driver.
remainder  [R]  This is any text that followed the first valid SQL statement in the text with which the statement was initialized. If there was no trailing text, this will be the empty string.

Public Class methods

Create a new statement attached to the given Database instance, and which encapsulates the given SQL text. If the text contains more than one statement (i.e., separated by semicolons), then the remainder property will be set to the trailing text.

[Source]

    # File lib/sqlite3/statement.rb, line 65
65:     def initialize( db, sql, utf16=false )
66:       @db = db
67:       @driver = @db.driver
68:       @closed = false
69:       @results = @columns = nil
70:       result, @handle, @remainder = @driver.prepare( @db.handle, sql )
71:       Error.check( result, @db )
72:     end

Public Instance methods

Returns true if the statement is currently active, meaning it has an open result set.

[Source]

     # File lib/sqlite3/statement.rb, line 208
208:     def active?
209:       not @results.nil?
210:     end

Binds value to the named (or positional) placeholder. If param is a Fixnum, it is treated as an index for a positional placeholder. Otherwise it is used as the name of the placeholder to bind to.

See also bind_params.

[Source]

     # File lib/sqlite3/statement.rb, line 117
117:     def bind_param( param, value )
118:       must_be_open!
119:       reset! if active?
120:       if Fixnum === param
121:         case value
122:           when Bignum then
123:             @driver.bind_int64( @handle, param, value )
124:           when Integer then
125:             @driver.bind_int( @handle, param, value )
126:           when Numeric then
127:             @driver.bind_double( @handle, param, value.to_f )
128:           when Blob then
129:             @driver.bind_blob( @handle, param, value )
130:           when nil then
131:             @driver.bind_null( @handle, param )
132:           else
133:             @driver.bind_text( @handle, param, value )
134:         end
135:       else
136:         param = param.to_s
137:         param = ":#{param}" unless param[0] == ?:
138:         index = @driver.bind_parameter_index( @handle, param )
139:         raise Exception, "no such bind parameter '#{param}'" if index == 0
140:         bind_param index, value
141:       end
142:     end

Binds the given variables to the corresponding placeholders in the SQL text.

See Database#execute for a description of the valid placeholder syntaxes.

Example:

  stmt = db.prepare( "select * from table where a=? and b=?" )
  stmt.bind_params( 15, "hello" )

See also execute, bind_param, Statement#bind_param, and Statement#bind_params.

[Source]

     # File lib/sqlite3/statement.rb, line 100
100:     def bind_params( *bind_vars )
101:       index = 1
102:       bind_vars.flatten.each do |var|
103:         if Hash === var
104:           var.each { |key, val| bind_param key, val }
105:         else
106:           bind_param index, var
107:           index += 1
108:         end
109:       end
110:     end

Closes the statement by finalizing the underlying statement handle. The statement must not be used after being closed.

[Source]

    # File lib/sqlite3/statement.rb, line 76
76:     def close
77:       must_be_open!
78:       @closed = true
79:       @driver.finalize( @handle )
80:     end

Returns true if the underlying statement has been closed.

[Source]

    # File lib/sqlite3/statement.rb, line 83
83:     def closed?
84:       @closed
85:     end

Return an array of the column names for this statement. Note that this may execute the statement in order to obtain the metadata; this makes it a (potentially) expensive operation.

[Source]

     # File lib/sqlite3/statement.rb, line 215
215:     def columns
216:       get_metadata unless @columns
217:       return @columns
218:     end

Execute the statement. This creates a new ResultSet object for the statement’s virtual machine. If a block was given, the new ResultSet will be yielded to it; otherwise, the ResultSet will be returned.

Any parameters will be bound to the statement using bind_params.

Example:

  stmt = db.prepare( "select * from table" )
  stmt.execute do |result|
    ...
  end

See also bind_params, execute!.

[Source]

     # File lib/sqlite3/statement.rb, line 158
158:     def execute( *bind_vars )
159:       must_be_open!
160:       reset! if active?
161: 
162:       bind_params(*bind_vars) unless bind_vars.empty?
163:       @results = ResultSet.new( @db, self )
164: 
165:       if block_given?
166:         yield @results
167:       else
168:         return @results
169:       end
170:     end

Execute the statement. If no block was given, this returns an array of rows returned by executing the statement. Otherwise, each row will be yielded to the block.

Any parameters will be bound to the statement using bind_params.

Example:

  stmt = db.prepare( "select * from table" )
  stmt.execute! do |row|
    ...
  end

See also bind_params, execute.

[Source]

     # File lib/sqlite3/statement.rb, line 186
186:     def execute!( *bind_vars )
187:       result = execute( *bind_vars )
188:       rows = [] unless block_given?
189:       while row = result.next
190:         if block_given?
191:           yield row
192:         else
193:           rows << row
194:         end
195:       end
196:       rows
197:     end

Resets the statement. This is typically done internally, though it might occassionally be necessary to manually reset the statement.

[Source]

     # File lib/sqlite3/statement.rb, line 201
201:     def reset!(clear_result=true)
202:       @driver.reset(@handle)
203:       @results = nil if clear_result
204:     end

Return an array of the data types for each column in this statement. Note that this may execute the statement in order to obtain the metadata; this makes it a (potentially) expensive operation.

[Source]

     # File lib/sqlite3/statement.rb, line 223
223:     def types
224:       get_metadata unless @types
225:       return @types
226:     end

[Validate]