class SQLite3::Statement

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

def active?

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

def active?
  not @results.nil?
end

def bind_param(param, value)

See also #bind_params.

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

def bind_param(param, value)
  must_be_open!
  reset! if active?
  if Fixnum === param
    case value
    when Bignum then
      @driver.bind_int64(@handle, param, value)
    when Integer then
      if value >= (2 ** 31)
        @driver.bind_int64(@handle, param, value)
      else
        @driver.bind_int(@handle, param, value)
      end
    when Numeric then
      @driver.bind_double(@handle, param, value.to_f)
    when Blob then
      @driver.bind_blob(@handle, param, value)
    when nil then
      @driver.bind_null(@handle, param)
    else
      @driver.bind_text(@handle, param, value)
    end
  else
    param = param.to_s
    param = ":#{param}" unless param[0] == ?:
    index = @driver.bind_parameter_index(@handle, param)
    raise Exception, "no such bind parameter '#{param}'" if index == 0
    bind_param index, value
  end
end

def bind_params(*bind_vars)

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

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

Example:

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

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

def bind_params(*bind_vars)
  index = 1
  bind_vars.flatten.each do |var|
    if Hash === var
      var.each { |key, val| bind_param key, val }
    else
      bind_param index, var
      index += 1
    end
  end
end

def close

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

def close
  must_be_open!
  @closed = true
  @driver.finalize(@handle)
end

def closed?

Returns true if the underlying statement has been closed.

def closed?
  @closed
end

def columns

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

def columns
  get_metadata unless @columns
  return @columns
end

def execute(*bind_vars)

See also #bind_params, #execute!.

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

Example:

Any parameters will be bound to the statement using #bind_params.

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

def execute(*bind_vars)
  must_be_open!
  reset! if active?
  bind_params(*bind_vars) unless bind_vars.empty?
  @results = ResultSet.new(@db, self)
  if block_given?
    yield @results
  else
    return @results
  end
end

def execute!(*bind_vars)

See also #bind_params, #execute.

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

Example:

Any parameters will be bound to the statement using #bind_params.

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

def execute!(*bind_vars)
  result = execute(*bind_vars)
  rows = [] unless block_given?
  while row = result.next
    if block_given?
      yield row
    else
      rows << row
    end
  end
  rows
end

def get_metadata

(potentially) expensive operation.
that this will actually execute the SQL, which means it can be a
A convenience method for obtaining the metadata about the query. Note

def get_metadata
  must_be_open!
  @columns = []
  @types = []
  column_count = @driver.column_count(@handle)
  column_count.times do |column|
    @columns << @driver.column_name(@handle, column)
    @types << @driver.column_decltype(@handle, column)
  end
  @columns.freeze
  @types.freeze
end

def initialize(db, sql, utf16 = false)

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

def initialize(db, sql, utf16 = false)
  raise ArgumentError, "nil argument passed as sql text" unless sql
  @db = db
  @driver = @db.driver
  @closed = false
  @results = @columns = nil
  result, @handle, @remainder = @driver.prepare(@db.handle, sql)
  Error.check(result, @db)
end

def must_be_open! # :nodoc:

:nodoc:
closed. If it is, an exception is raised.
Performs a sanity check to ensure that the statement is not

def must_be_open! # :nodoc:
  if @closed
    raise SQLite3::Exception, "cannot use a closed statement"
  end
end

def reset!(clear_result=true)

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

def reset!(clear_result=true)
  @driver.reset(@handle)
  @results = nil if clear_result
end

def types

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

def types
  get_metadata unless @types
  return @types
end

Modules

Classes