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
Attributes
[R] handle The underlying opaque handle used to access the SQLite @driver.
[R] remainder 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
new( db, sql, utf16=false )

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.

    # File lib/sqlite3/statement.rb, line 33
33:     def initialize( db, sql, utf16=false )
34:       @db = db
35:       @driver = @db.driver
36:       @closed = false
37:       @results = @columns = nil
38:       result, @handle, @remainder = @driver.prepare( @db.handle, sql )
39:       Error.check( result, @db )
40:     end
Public Instance methods
active?()

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

     # File lib/sqlite3/statement.rb, line 180
180:     def active?
181:       not @results.nil?
182:     end
bind_param( param, value )

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.

     # File lib/sqlite3/statement.rb, line 85
 85:     def bind_param( param, value )
 86:       must_be_open!
 87:       reset! if active?
 88:       if Fixnum === param
 89:         case value
 90:           when Bignum then
 91:             @driver.bind_int64( @handle, param, value )
 92:           when Integer then
 93:             if value >= (2 ** 31)
 94:               @driver.bind_int64( @handle, param, value )
 95:             else
 96:               @driver.bind_int( @handle, param, value )
 97:             end
 98:           when Numeric then
 99:             @driver.bind_double( @handle, param, value.to_f )
100:           when Blob then
101:             @driver.bind_blob( @handle, param, value )
102:           when nil then
103:             @driver.bind_null( @handle, param )
104:           else
105:             @driver.bind_text( @handle, param, value )
106:         end
107:       else
108:         param = param.to_s
109:         param = ":#{param}" unless param[0] == ?:
110:         index = @driver.bind_parameter_index( @handle, param )
111:         raise Exception, "no such bind parameter '#{param}'" if index == 0
112:         bind_param index, value
113:       end
114:     end
bind_params( *bind_vars )

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.

    # File lib/sqlite3/statement.rb, line 68
68:     def bind_params( *bind_vars )
69:       index = 1
70:       bind_vars.flatten.each do |var|
71:         if Hash === var
72:           var.each { |key, val| bind_param key, val }
73:         else
74:           bind_param index, var
75:           index += 1
76:         end
77:       end
78:     end
close()

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

    # File lib/sqlite3/statement.rb, line 44
44:     def close
45:       must_be_open!
46:       @closed = true
47:       @driver.finalize( @handle )
48:     end
closed?()

Returns true if the underlying statement has been closed.

    # File lib/sqlite3/statement.rb, line 51
51:     def closed?
52:       @closed
53:     end
columns()

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.

     # File lib/sqlite3/statement.rb, line 187
187:     def columns
188:       get_metadata unless @columns
189:       return @columns
190:     end
execute( *bind_vars ) {|@results| ...}

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!.

     # File lib/sqlite3/statement.rb, line 130
130:     def execute( *bind_vars )
131:       must_be_open!
132:       reset! if active?
133: 
134:       bind_params(*bind_vars) unless bind_vars.empty?
135:       @results = ResultSet.new( @db, self )
136: 
137:       if block_given?
138:         yield @results
139:       else
140:         return @results
141:       end
142:     end
execute!( *bind_vars ) {|row| ...}

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.

     # File lib/sqlite3/statement.rb, line 158
158:     def execute!( *bind_vars )
159:       result = execute( *bind_vars )
160:       rows = [] unless block_given?
161:       while row = result.next
162:         if block_given?
163:           yield row
164:         else
165:           rows << row
166:         end
167:       end
168:       rows
169:     end
reset!(clear_result=true)

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

     # File lib/sqlite3/statement.rb, line 173
173:     def reset!(clear_result=true)
174:       @driver.reset(@handle)
175:       @results = nil if clear_result
176:     end
types()

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.

     # File lib/sqlite3/statement.rb, line 195
195:     def types
196:       get_metadata unless @types
197:       return @types
198:     end