# class SQLite3::Statement

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 SQLite3::Database#prepare method.

### Attributes

remainder[R]

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

SQLite3::Statement.new(db, sql) click to toggle source

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.

    static VALUE initialize(VALUE self, VALUE db, VALUE sql)
    {
      sqlite3RubyPtr db_ctx;
      sqlite3StmtRubyPtr ctx;
      const char *tail = NULL;
      int status;

      StringValue(sql);

      Data_Get_Struct(db, sqlite3Ruby, db_ctx);
      Data_Get_Struct(self, sqlite3StmtRuby, ctx);

      if(!db_ctx->db)
        rb_raise(rb_eArgError, "prepare called on a closed database");

    #ifdef HAVE_RUBY_ENCODING_H
      if(!UTF8_P(sql)) {
        sql               = rb_str_export_to_enc(sql, rb_utf8_encoding());
      }
    #endif

    #ifdef HAVE_SQLITE3_PREPARE_V2
      status = sqlite3_prepare_v2(
    #else
      status = sqlite3_prepare(
    #endif
          db_ctx->db,
          (const char *)StringValuePtr(sql),
          (int)RSTRING_LEN(sql),
          &ctx->st,
          &tail
      );

      CHECK(db_ctx->db, status);

      rb_iv_set(self, "@connection", db);
      rb_iv_set(self, "@remainder", rb_str_new2(tail));
      rb_iv_set(self, "@columns", Qnil);
      rb_iv_set(self, "@types", Qnil);

      return self;
    }

### Public Instance Methods

active?() click to toggle source

Returns true if the statement is currently active, meaning it has an open result set.

    # File lib/sqlite3/statement.rb, line 94
    def active?
      !done?
    end

bind_param(key, value) click to toggle source

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.

    static VALUE bind_param(VALUE self, VALUE key, VALUE value)
    {
      sqlite3StmtRubyPtr ctx;
      int status;
      int index;

      Data_Get_Struct(self, sqlite3StmtRuby, ctx);
      REQUIRE_OPEN_STMT(ctx);

      switch(TYPE(key)) {
        case T_SYMBOL:
          key = rb_funcall(key, rb_intern("to_s"), 0);
        case T_STRING:
          if(RSTRING_PTR(key)[0] != ':') key = rb_str_plus(rb_str_new2(":"), key);
          index = sqlite3_bind_parameter_index(ctx->st, StringValuePtr(key));
          break;
        default:
          index = (int)NUM2INT(key);
      }

      if(index == 0)
        rb_raise(rb_path2class("SQLite3::Exception"), "no such bind parameter");

      switch(TYPE(value)) {
        case T_STRING:
          if(CLASS_OF(value) == cSqlite3Blob
    #ifdef HAVE_RUBY_ENCODING_H
                  || rb_enc_get_index(value) == rb_ascii8bit_encindex()
    #endif
            ) {
            status = sqlite3_bind_blob(
                ctx->st,
                index,
                (const char *)StringValuePtr(value),
                (int)RSTRING_LEN(value),
                SQLITE_TRANSIENT
                );
          } else {

    #ifdef HAVE_RUBY_ENCODING_H
            if (UTF16_LE_P(value)) {
              status = sqlite3_bind_text16(
                  ctx->st,
                  index,
                  (const char *)StringValuePtr(value),
                  (int)RSTRING_LEN(value),
                  SQLITE_TRANSIENT
                  );
            } else {
              if (!UTF8_P(value) || !USASCII_P(value)) {
                  value = rb_str_encode(value, rb_enc_from_encoding(rb_utf8_encoding()), 0, Qnil);
              }
    #endif
            status = sqlite3_bind_text(
                ctx->st,
                index,
                (const char *)StringValuePtr(value),
                (int)RSTRING_LEN(value),
                SQLITE_TRANSIENT
                );
    #ifdef HAVE_RUBY_ENCODING_H
            }
    #endif
          }
          break;
        case T_BIGNUM: {
          sqlite3_int64 num64;
          if (bignum_to_int64(value, &num64)) {
              status = sqlite3_bind_int64(ctx->st, index, num64);
              break;
          }
        }
        case T_FLOAT:
          status = sqlite3_bind_double(ctx->st, index, NUM2DBL(value));
          break;
        case T_FIXNUM:
          status = sqlite3_bind_int64(ctx->st, index, (sqlite3_int64)FIX2LONG(value));
          break;
        case T_NIL:
          status = sqlite3_bind_null(ctx->st, index);
          break;
        default:
          rb_raise(rb_eRuntimeError, "can't prepare %s",
              rb_class2name(CLASS_OF(value)));
          break;
      }

      CHECK(sqlite3_db_handle(ctx->st), status);

      return self;
    }

bind_parameter_count click to toggle source

Return the number of bind parameters

    static VALUE bind_parameter_count(VALUE self)
    {
      sqlite3StmtRubyPtr ctx;
      Data_Get_Struct(self, sqlite3StmtRuby, ctx);
      REQUIRE_OPEN_STMT(ctx);

      return INT2NUM((long)sqlite3_bind_parameter_count(ctx->st));
    }

bind_params( *bind_vars ) click to toggle source

Binds the given variables to the corresponding placeholders in the SQL text.

See SQLite3::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, #bind_param, and #bind_params.

    # File lib/sqlite3/statement.rb, line 35
    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

clear_bindings! click to toggle source

Resets the statement. This is typically done internally, though it might occassionally be necessary to manually reset the statement.

    static VALUE clear_bindings(VALUE self)
    {
      sqlite3StmtRubyPtr ctx;

      Data_Get_Struct(self, sqlite3StmtRuby, ctx);
      REQUIRE_OPEN_STMT(ctx);

      sqlite3_clear_bindings(ctx->st);

      ctx->done_p = 0;

      return self;
    }

close click to toggle source

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

    static VALUE sqlite3_rb_close(VALUE self)
    {
      sqlite3StmtRubyPtr ctx;

      Data_Get_Struct(self, sqlite3StmtRuby, ctx);

      REQUIRE_OPEN_STMT(ctx);

      sqlite3_finalize(ctx->st);
      ctx->st = NULL;

      return self;
    }

closed? click to toggle source

Returns true if the statement has been closed.

    static VALUE closed_p(VALUE self)
    {
      sqlite3StmtRubyPtr ctx;
      Data_Get_Struct(self, sqlite3StmtRuby, ctx);

      if(!ctx->st) return Qtrue;

      return Qfalse;
    }

column_count click to toggle source

Returns the number of columns to be returned for this statement

    static VALUE column_count(VALUE self)
    {
      sqlite3StmtRubyPtr ctx;
      Data_Get_Struct(self, sqlite3StmtRuby, ctx);
      REQUIRE_OPEN_STMT(ctx);

      return INT2NUM((long)sqlite3_column_count(ctx->st));
    }

column_decltype(index) click to toggle source

Get the column type at `index`. 0 based.

    static VALUE column_decltype(VALUE self, VALUE index)
    {
      sqlite3StmtRubyPtr ctx;
      const char * name;

      Data_Get_Struct(self, sqlite3StmtRuby, ctx);
      REQUIRE_OPEN_STMT(ctx);

      name = sqlite3_column_decltype(ctx->st, (int)NUM2INT(index));

      if(name) return rb_str_new2(name);
      return Qnil;
    }

column_name(index) click to toggle source

Get the column name at `index`. 0 based.

    static VALUE column_name(VALUE self, VALUE index)
    {
      sqlite3StmtRubyPtr ctx;
      const char * name;

      Data_Get_Struct(self, sqlite3StmtRuby, ctx);
      REQUIRE_OPEN_STMT(ctx);

      name = sqlite3_column_name(ctx->st, (int)NUM2INT(index));

      if(name) return SQLITE3_UTF8_STR_NEW2(name);
      return Qnil;
    }

columns() click to toggle source

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.

    # File lib/sqlite3/statement.rb, line 101
    def columns
      get_metadata unless @columns
      return @columns
    end

database_name(column_index) click to toggle source

Return the database name for the column at `column_index`

    static VALUE database_name(VALUE self, VALUE index)
    {
      sqlite3StmtRubyPtr ctx;
      Data_Get_Struct(self, sqlite3StmtRuby, ctx);
      REQUIRE_OPEN_STMT(ctx);

      return SQLITE3_UTF8_STR_NEW2(
          sqlite3_column_database_name(ctx->st, NUM2INT(index)));
    }

done? click to toggle source

returns true if all rows have been returned.

    static VALUE done_p(VALUE self)
    {
      sqlite3StmtRubyPtr ctx;
      Data_Get_Struct(self, sqlite3StmtRuby, ctx);

      if(ctx->done_p) return Qtrue;
      return Qfalse;
    }

each() { |val| ... } click to toggle source

    # File lib/sqlite3/statement.rb, line 106
    def each
      loop do
        val = step
        break self if done?
        yield val
      end
    end

execute( *bind_vars ) { |results| ... } click to toggle source

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

    # File lib/sqlite3/statement.rb, line 61
    def execute( *bind_vars )
      reset! if active? || done?

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

      step if 0 == column_count

      yield @results if block_given?
      @results
    end

execute!( *bind_vars, &block ) click to toggle source

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.

    # File lib/sqlite3/statement.rb, line 87
    def execute!( *bind_vars, &block )
      execute(*bind_vars)
      block_given? ? each(&block) : to_a
    end

reset! click to toggle source

Resets the statement. This is typically done internally, though it might occassionally be necessary to manually reset the statement.

    static VALUE reset_bang(VALUE self)
    {
      sqlite3StmtRubyPtr ctx;

      Data_Get_Struct(self, sqlite3StmtRuby, ctx);
      REQUIRE_OPEN_STMT(ctx);

      sqlite3_reset(ctx->st);

      ctx->done_p = 0;

      return self;
    }

step() click to toggle source

    static VALUE step(VALUE self)
    {
      sqlite3StmtRubyPtr ctx;
      sqlite3_stmt *stmt;
      int value, length;
      VALUE list;
    #ifdef HAVE_RUBY_ENCODING_H
      rb_encoding * internal_encoding;
    #endif

      Data_Get_Struct(self, sqlite3StmtRuby, ctx);

      REQUIRE_OPEN_STMT(ctx);

      if(ctx->done_p) return Qnil;

    #ifdef HAVE_RUBY_ENCODING_H
      {
          VALUE db          = rb_iv_get(self, "@connection");
          rb_funcall(db, rb_intern("encoding"), 0);
          internal_encoding = rb_default_internal_encoding();
      }
    #endif

      stmt = ctx->st;

      value = sqlite3_step(stmt);
      length = sqlite3_column_count(stmt);
      list = rb_ary_new2((long)length);

      switch(value) {
        case SQLITE_ROW:
          {
            int i;
            for(i = 0; i < length; i++) {
              switch(sqlite3_column_type(stmt, i)) {
                case SQLITE_INTEGER:
                  rb_ary_push(list, LL2NUM(sqlite3_column_int64(stmt, i)));
                  break;
                case SQLITE_FLOAT:
                  rb_ary_push(list, rb_float_new(sqlite3_column_double(stmt, i)));
                  break;
                case SQLITE_TEXT:
                  {
                    VALUE str = rb_tainted_str_new(
                        (const char *)sqlite3_column_text(stmt, i),
                        (long)sqlite3_column_bytes(stmt, i)
                    );
    #ifdef HAVE_RUBY_ENCODING_H
                    rb_enc_associate_index(str, rb_utf8_encindex());
                    if(internal_encoding)
                      str = rb_str_export_to_enc(str, internal_encoding);
    #endif
                    rb_ary_push(list, str);
                  }
                  break;
                case SQLITE_BLOB:
                  {
                    VALUE str = rb_tainted_str_new(
                        (const char *)sqlite3_column_blob(stmt, i),
                        (long)sqlite3_column_bytes(stmt, i)
                    );
                    rb_ary_push(list, str);
                  }
                  break;
                case SQLITE_NULL:
                  rb_ary_push(list, Qnil);
                  break;
                default:
                  rb_raise(rb_eRuntimeError, "bad type");
              }
            }
          }
          break;
        case SQLITE_DONE:
          ctx->done_p = 1;
          return Qnil;
          break;
        default:
          sqlite3_reset(stmt);
          ctx->done_p = 0;
          CHECK(sqlite3_db_handle(ctx->st), value);
      }

      return list;
    }

types() click to toggle source

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.

    # File lib/sqlite3/statement.rb, line 117
    def types
      must_be_open!
      get_metadata unless @types
      @types
    end

### Private Instance Methods

get_metadata() click to toggle source

A convenience method for obtaining the metadata about the query. Note that this will actually execute the SQL, which means it can be a (potentially) expensive operation.

    # File lib/sqlite3/statement.rb, line 135
    def get_metadata
      @columns = Array.new(column_count) do |column|
        column_name column
      end
      @types = Array.new(column_count) do |column|
        column_decltype column
      end
    end