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 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
Returns true if the statement is currently active, meaning it has an open result set.
[ show source ]
# File lib/sqlite3/statement.rb, line 180 180: def active? 181: not @results.nil? 182: 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 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
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 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
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 44 44: def close 45: must_be_open! 46: @closed = true 47: @driver.finalize( @handle ) 48: end
Returns true if the underlying statement has been closed.
[ show source ]
# File lib/sqlite3/statement.rb, line 51 51: def closed? 52: @closed 53: 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 187 187: def columns 188: get_metadata unless @columns 189: return @columns 190: 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 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 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 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
Resets the statement. This is typically done internally, though it might occassionally be necessary to manually reset the statement.
[ show source ]
# 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
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 195 195: def types 196: get_metadata unless @types 197: return @types 198: end