Class: SQLite3::Statement

Inherits:
Object
  • Object
show all
Includes:
Enumerable
Defined in:
lib/sqlite3-1.5.3-arm64-darwin/lib/sqlite3/statement.rb,
lib/sqlite3-1.5.3-x86_64-darwin/lib/sqlite3/statement.rb

Overview

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.

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#remainder ⇒ Object (readonly)

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.



20
21
22
 
# File 'lib/sqlite3-1.5.3-arm64-darwin/lib/sqlite3/statement.rb', line 20

def remainder
  @remainder
end

Instance Method Details

#active? ⇒ Boolean

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

Returns:

  • (Boolean) 


94
95
96
 
# File 'lib/sqlite3-1.5.3-arm64-darwin/lib/sqlite3/statement.rb', line 94

def active?
  !done?
end

#bind_params(*bind_vars) ⇒ Object

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.



35
36
37
38
39
40
41
42
43
44
45
 
# File 'lib/sqlite3-1.5.3-arm64-darwin/lib/sqlite3/statement.rb', line 35

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

#columns ⇒ Object

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.



101
102
103
104
 
# File 'lib/sqlite3-1.5.3-arm64-darwin/lib/sqlite3/statement.rb', line 101

def columns
  get_metadata unless @columns
  return @columns
end

#each ⇒ Object 



106
107
108
109
110
111
112
 
# File 'lib/sqlite3-1.5.3-arm64-darwin/lib/sqlite3/statement.rb', line 106

def each
  loop do
    val = step
    break self if done?
    yield val
  end
end

#execute(*bind_vars) {|@results| ... } ⇒ Object

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

Yields:

  • (@results) 


61
62
63
64
65
66
67
68
69
70
71
 
# File 'lib/sqlite3-1.5.3-arm64-darwin/lib/sqlite3/statement.rb', line 61

def execute( *bind_vars )
  reset! if active? || done?

  bind_params(*bind_vars) unless bind_vars.empty?
  @results = ResultSet.new(@connection, self)

  step if 0 == column_count

  yield @results if block_given?
  @results
end

#execute!(*bind_vars, &block) ⇒ Object

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.



87
88
89
90
 
# File 'lib/sqlite3-1.5.3-arm64-darwin/lib/sqlite3/statement.rb', line 87

def execute!( *bind_vars, &block )
  execute(*bind_vars)
  block_given? ? each(&block) : to_a
end

#must_be_open! ⇒ Object

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



125
126
127
128
129
 
# File 'lib/sqlite3-1.5.3-arm64-darwin/lib/sqlite3/statement.rb', line 125

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

#types ⇒ Object

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.



117
118
119
120
121
 
# File 'lib/sqlite3-1.5.3-arm64-darwin/lib/sqlite3/statement.rb', line 117

def types
  must_be_open!
  get_metadata unless @types
  @types
end