Class: SQLite3::Statement

Class SQLite3::Statement |
In: | lib/sqlite3/statement.rb
Parent: | Object

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.

Methods

- bind_param
- bind_params
- close
- closed?
- columns
- execute
- execute!
- new
- types

Attributes

[R] | handle | The underlying opaque handle used to access the SQLite @driver.
[R] | remainder | 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.

Public Class methods
new( db, sql, utf16=false )

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.

[ show source ]

        # File lib/sqlite3/statement.rb, line 65
    65:     def initialize( db, sql, utf16=false )
    66:       @db = db
    67:       @driver = @db.driver
    68:       @closed = false
    69:       result, @handle, @remainder = @driver.prepare( @db.handle, sql )
    70:       Error.check( result, @db )
    71:     end

Public Instance methods
bind_param( param, value )

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.

[ show source ]

         # File lib/sqlite3/statement.rb, line 116
    116:     def bind_param( param, value )
    117:       must_be_open!
    118:       if Fixnum === param
    119:         case value
    120:           when Integer then
    121:             @driver.bind_int( @handle, param, value )
    122:           when Numeric then
    123:             @driver.bind_double( @handle, param, value.to_f )
    124:           when Blob then
    125:             @driver.bind_blob( @handle, param, value )
    126:           when nil then
    127:             @driver.bind_null( @handle, param )
    128:           else
    129:             @driver.bind_text( @handle, param, value )
    130:         end
    131:       else
    132:         index = @driver.bind_parameter_index(
    133:           @handle, param.to_s )
    134:         raise Exception, "no such bind parameter '#{param}'" if index == 0
    135:         bind_param index, value
    136:       end
    137:     end

bind_params( *bind_vars )

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.

[ show source ]

         # File lib/sqlite3/statement.rb, line 99
     99:     def bind_params( *bind_vars )
    100:       index = 1
    101:       bind_vars.flatten.each do |var|
    102:         if Hash === var
    103:           var.each { |key, val| bind_param key, val }
    104:         else
    105:           bind_param index, var
    106:           index += 1
    107:         end
    108:       end
    109:     end

close()

Closes the statement by finalizing the underlying statement handle. The statement must not be used after being closed.

[ show source ]

        # File lib/sqlite3/statement.rb, line 75
    75:     def close
    76:       must_be_open!
    77:       @closed = true
    78:       @driver.finalize( @handle )
    79:     end

closed?()

Returns true if the underlying statement has been closed.

[ show source ]

        # File lib/sqlite3/statement.rb, line 82
    82:     def closed?
    83:       @closed
    84:     end

columns()

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.

[ show source ]

         # File lib/sqlite3/statement.rb, line 197
    197:     def columns
    198:       get_metadata unless @columns
    199:       return @columns
    200:     end

execute( *bind_vars ) {|@results| ...}

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

[ show source ]

         # File lib/sqlite3/statement.rb, line 153
    153:     def execute( *bind_vars )
    154:       must_be_open!
    155:       @driver.reset( @handle ) if @results
    156:
    157:       bind_params *bind_vars unless bind_vars.empty?
    158:       @results = ResultSet.new( @db, self )
    159:
    160:       if block_given?
    161:         yield @results
    162:       else
    163:         return @results
    164:       end
    165:     end

execute!( *bind_vars ) {|row| ...}

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.

[ show source ]

         # File lib/sqlite3/statement.rb, line 181
    181:     def execute!( *bind_vars )
    182:       result = execute( *bind_vars )
    183:       rows = [] unless block_given?
    184:       while row = result.next
    185:         if block_given?
    186:           yield row
    187:         else
    188:           rows << row
    189:         end
    190:       end
    191:       rows
    192:     end

types()

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.

[ show source ]

         # File lib/sqlite3/statement.rb, line 205
    205:     def types
    206:       get_metadata unless @types
    207:       return @types
    208:     end

[Validate]