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.strip
  @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.



149
150
151
152
 
# File 'lib/sqlite/statement.rb', line 149

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

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



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

def execute( *bind_vars )
  bind_params *bind_vars unless bind_vars.empty?
  results = ResultSet.new( @db, @statement.to_s )

  if block_given?
    begin
      yield results
    ensure
      results.close
    end
  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 and then closed.

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.



131
132
133
134
135
136
137
138
139
140
141
142
143
144
 
# File 'lib/sqlite/statement.rb', line 131

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
ensure
  result.close if result
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.



157
158
159
160
 
# File 'lib/sqlite/statement.rb', line 157

def types
  get_metadata unless @types
  return @types
end