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

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.

### Public Instance methods

active?()

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

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.

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.

close()

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

closed?()

Returns true if the underlying statement has been closed.

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.

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

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.

reset!(clear_result=true)

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

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.

[Validate]