Class: SQLite::Statement

Inherits:
Object
  • Object
show all
Defined in:
lib/sqlite/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

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.



53
54
55
56
57
58
 
# File 'lib/sqlite/statement.rb', line 53

def initialize( db, sql )
  @db = db
  @statement = ParsedStatement.new( sql )
  @remainder = @statement.trailing
  @sql = @statement.to_s
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.



47
48
49
 
# File 'lib/sqlite/statement.rb', line 47

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.



82
83
84
 
# File 'lib/sqlite/statement.rb', line 82

def bind_param( param, value )
  @statement.bind_param( param, value )
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.



73
74
75
 
# File 'lib/sqlite/statement.rb', line 73

def bind_params( *bind_vars )
  @statement.bind_params( *bind_vars )
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.



117
118
119
120
 
# File 'lib/sqlite/statement.rb', line 117

def columns
  get_metadata unless @columns
  return @columns
end

#execute ⇒ 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 and then closed; otherwise, the ResultSet will be returned. In that case, it is the client’s responsibility to close the ResultSet.

Example:

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

See also #bind_params.



100
101
102
103
104
105
106
107
108
109
110
111
112
 
# File 'lib/sqlite/statement.rb', line 100

def execute
  results = ResultSet.new( @db, @statement.to_s )

  if block_given?
    begin
      yield results
    ensure
      results.close
    end
  else
    return results
  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.



125
126
127
128
 
# File 'lib/sqlite/statement.rb', line 125

def types
  get_metadata unless @types
  return @types
end