Class: SQLite3::Statement

Inherits:
Object
  • Object
show all
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, utf16 = false) ⇒ Statement

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.



65
66
67
68
69
70
 
# File 'lib/sqlite3/statement.rb', line 65

def initialize( db, sql, utf16=false )
  @db = db
  @driver = @db.driver
  result, @handle, @remainder = @driver.prepare( @db.handle, sql )
  Error.check( result, @db )
end

Instance Attribute Details

#handle ⇒ Object (readonly)

The underlying opaque handle used to access the SQLite @driver.



59
60
61
 
# File 'lib/sqlite3/statement.rb', line 59

def handle
  @handle
end

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



56
57
58
 
# File 'lib/sqlite3/statement.rb', line 56

def remainder
  @remainder
end

Instance Method Details

#bind_param(param, value) ⇒ Object

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.



106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
 
# File 'lib/sqlite3/statement.rb', line 106

def bind_param( param, value )
  if Fixnum === param
    case value
      when Integer then
        @driver.bind_int( @handle, param, value )
      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
    index = @driver.bind_parameter_index(
      @handle, param.to_s )
    raise Exception, "no such bind parameter '#{param}'" if index == 0
    bind_param index, value
  end
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.



89
90
91
92
93
94
95
96
97
98
99
 
# File 'lib/sqlite3/statement.rb', line 89

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

#close ⇒ Object 



72
73
74
 
# File 'lib/sqlite3/statement.rb', line 72

def close
  @driver.finalize( @handle )
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.



185
186
187
188
 
# File 'lib/sqlite3/statement.rb', line 185

def columns
  get_metadata unless @columns
  return @columns
end

#execute(*bind_vars) ⇒ 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!.



142
143
144
145
146
147
148
149
150
151
152
153
 
# File 'lib/sqlite3/statement.rb', line 142

def execute( *bind_vars )
  @driver.reset( @handle ) if @results

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

  if block_given?
    yield @results
  else
    return @results
  end
end

#execute!(*bind_vars) ⇒ 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.



169
170
171
172
173
174
175
176
177
178
179
180
 
# File 'lib/sqlite3/statement.rb', line 169

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

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



193
194
195
196
 
# File 'lib/sqlite3/statement.rb', line 193

def types
  get_metadata unless @types
  return @types
end