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.
[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. |
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.
[ show 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: result, @handle, @remainder = @driver.prepare( @db.handle, sql ) 70: Error.check( result, @db ) 71: 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.
[ show source ]
# File lib/sqlite3/statement.rb, line 116 116: def bind_param( param, value ) 117: must_be_open! 118: if Fixnum === param 119: case value 120: when Integer then 121: @driver.bind_int( @handle, param, value ) 122: when Numeric then 123: @driver.bind_double( @handle, param, value.to_f ) 124: when Blob then 125: @driver.bind_blob( @handle, param, value ) 126: when nil then 127: @driver.bind_null( @handle, param ) 128: else 129: @driver.bind_text( @handle, param, value ) 130: end 131: else 132: index = @driver.bind_parameter_index( 133: @handle, param.to_s ) 134: raise Exception, "no such bind parameter '#{param}'" if index == 0 135: bind_param index, value 136: end 137: 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.
[ show source ]
# File lib/sqlite3/statement.rb, line 99 99: def bind_params( *bind_vars ) 100: index = 1 101: bind_vars.flatten.each do |var| 102: if Hash === var 103: var.each { |key, val| bind_param key, val } 104: else 105: bind_param index, var 106: index += 1 107: end 108: end 109: end
Closes the statement by finalizing the underlying statement handle. The statement must not be used after being closed.
[ show source ]
# File lib/sqlite3/statement.rb, line 75 75: def close 76: must_be_open! 77: @closed = true 78: @driver.finalize( @handle ) 79: end
Returns true if the underlying statement has been closed.
[ show source ]
# File lib/sqlite3/statement.rb, line 82 82: def closed? 83: @closed 84: 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.
[ show source ]
# File lib/sqlite3/statement.rb, line 197 197: def columns 198: get_metadata unless @columns 199: return @columns 200: 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!.
[ show source ]
# File lib/sqlite3/statement.rb, line 153 153: def execute( *bind_vars ) 154: must_be_open! 155: @driver.reset( @handle ) if @results 156: 157: bind_params *bind_vars unless bind_vars.empty? 158: @results = ResultSet.new( @db, self ) 159: 160: if block_given? 161: yield @results 162: else 163: return @results 164: end 165: 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.
[ show source ]
# File lib/sqlite3/statement.rb, line 181 181: def execute!( *bind_vars ) 182: result = execute( *bind_vars ) 183: rows = [] unless block_given? 184: while row = result.next 185: if block_given? 186: yield row 187: else 188: rows << row 189: end 190: end 191: rows 192: 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.
[ show source ]
# File lib/sqlite3/statement.rb, line 205 205: def types 206: get_metadata unless @types 207: return @types 208: end