Class: SQLite3::Statement

Inherits:
Object
  • Object
show all
Includes:
Enumerable
Defined in:
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

Constructor Details

#initialize(db, sql) ⇒ Statement

call-seq: SQLite3::Statement.new(db, sql)

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.

Raises:

  • (ArgumentError) 


28
29
30
31
32
33
34
35
36
37
 
# File 'lib/sqlite3/statement.rb', line 28

def initialize(db, sql)
  raise ArgumentError, "prepare called on a closed database" if db.closed?

  sql = sql.encode(Encoding::UTF_8) if sql && sql.encoding != Encoding::UTF_8

  @connection = db
  @columns = nil
  @types = nil
  @remainder = prepare db, sql
end

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/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) 


111
112
113
 
# File 'lib/sqlite3/statement.rb', line 111

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.



52
53
54
55
56
57
58
59
60
61
62
 
# File 'lib/sqlite3/statement.rb', line 52

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.



118
119
120
121
 
# File 'lib/sqlite3/statement.rb', line 118

def columns
  get_metadata unless @columns
  @columns
end

#each ⇒ Object 



123
124
125
126
127
128
129
 
# File 'lib/sqlite3/statement.rb', line 123

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) 


78
79
80
81
82
83
84
85
86
87
88
 
# File 'lib/sqlite3/statement.rb', line 78

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

  bind_params(*bind_vars) unless bind_vars.empty?
  results = @connection.build_result_set self

  step if column_count == 0

  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.



104
105
106
107
 
# File 'lib/sqlite3/statement.rb', line 104

def execute!(*bind_vars, &block)
  execute(*bind_vars)
  block ? 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.



142
143
144
145
146
 
# File 'lib/sqlite3/statement.rb', line 142

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

#stat(key = nil) ⇒ Object

Returns a Hash containing information about the statement. The contents of the hash are implementation specific and may change in the future without notice. The hash includes information about internal statistics about the statement such as:

- +fullscan_steps+: the number of times that SQLite has stepped forward

in a table as part of a full table scan

- +sorts+: the number of sort operations that have occurred
- +autoindexes+: the number of rows inserted into transient indices

that were created automatically in order to help joins run faster

- +vm_steps+: the number of virtual machine operations executed by the

prepared statement

- +reprepares+: the number of times that the prepare statement has been

automatically regenerated due to schema changes or changes to bound parameters that might affect the query plan

- +runs+: the number of times that the prepared statement has been run
- +filter_misses+: the number of times that the Bloom filter returned

a find, and thus the join step had to be processed as normal

- +filter_hits+: the number of times that a join step was bypassed

because a Bloom filter returned not-found



167
168
169
170
171
172
173
 
# File 'lib/sqlite3/statement.rb', line 167

def stat key = nil
  if key
    stat_for(key)
  else
    stats_as_hash
  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.



134
135
136
137
138
 
# File 'lib/sqlite3/statement.rb', line 134

def types
  must_be_open!
  get_metadata unless @types
  @types
end