Class: SQLite::Statement

Class SQLite::Statement |
In: | lib/sqlite/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
- columns
- execute
- execute!
- new
- types

Attributes

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

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/sqlite/statement.rb, line 53
    53:     def initialize( db, sql )
    54:       @db = db
    55:       @statement = ParsedStatement.new( sql )
    56:       @remainder = @statement.trailing.strip
    57:       @sql = @statement.to_s
    58:     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/sqlite/statement.rb, line 82
    82:     def bind_param( param, value )
    83:       @statement.bind_param( param, value )
    84:     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/sqlite/statement.rb, line 73
    73:     def bind_params( *bind_vars )
    74:       @statement.bind_params( *bind_vars )
    75:     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/sqlite/statement.rb, line 149
    149:     def columns
    150:       get_metadata unless @columns
    151:       return @columns
    152:     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 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!.

[ show source ]

         # File lib/sqlite/statement.rb, line 102
    102:     def execute( *bind_vars )
    103:       bind_params *bind_vars unless bind_vars.empty?
    104:       results = ResultSet.new( @db, @statement.to_s )
    105:
    106:       if block_given?
    107:         begin
    108:           yield results
    109:         ensure
    110:           results.close
    111:         end
    112:       else
    113:         return results
    114:       end
    115:     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 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.

[ show source ]

         # File lib/sqlite/statement.rb, line 131
    131:     def execute!( *bind_vars )
    132:       result = execute( *bind_vars )
    133:       rows = [] unless block_given?
    134:       while row = result.next
    135:         if block_given?
    136:           yield row
    137:         else
    138:           rows << row
    139:         end
    140:       end
    141:       rows
    142:     ensure
    143:       result.close if result
    144:     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/sqlite/statement.rb, line 157
    157:     def types
    158:       get_metadata unless @types
    159:       return @types
    160:     end

[Validate]