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.
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 # 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; 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)) { VALUE encoding = rb_funcall(db, rb_intern("encoding"), 0); rb_encoding * enc = NIL_P(encoding) ? rb_utf8_encoding() : rb_to_encoding(encoding); sql = rb_str_export_to_enc(sql, enc); } #endif status = sqlite3_prepare_v2( 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; }
Returns true if the statement is currently active, meaning it has an open result set.
# File lib/sqlite3/statement.rb, line 94 94: def active? 95: !done? 96: end
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 #.
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(!UTF8_P(value)) { VALUE db = rb_iv_get(self, "@connection"); VALUE encoding = rb_funcall(db, rb_intern("encoding"), 0); rb_encoding * enc = rb_to_encoding(encoding); value = rb_str_export_to_enc(value, enc); } #endif status = sqlite3_bind_text( ctx->st, index, (const char *)StringValuePtr(value), (int)RSTRING_LEN(value), SQLITE_TRANSIENT ); } break; case T_BIGNUM: #if SIZEOF_LONG < 8 if (RBIGNUM_LEN(value) * SIZEOF_BDIGITS <= 8) { status = sqlite3_bind_int64(ctx->st, index, (sqlite3_int64)NUM2LL(value)); break; } #endif 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; }
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)); }
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 #, #, Statement#bind_param, and Statement#bind_params.
# File lib/sqlite3/statement.rb, line 35 35: def bind_params( *bind_vars ) 36: index = 1 37: bind_vars.flatten.each do |var| 38: if Hash === var 39: var.each { |key, val| bind_param key, val } 40: else 41: bind_param index, var 42: index += 1 43: end 44: end 45: end
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; sqlite3 * db; Data_Get_Struct(self, sqlite3StmtRuby, ctx); REQUIRE_OPEN_STMT(ctx); db = sqlite3_db_handle(ctx->st); CHECK(db, sqlite3_finalize(ctx->st)); ctx->st = NULL; return self; }
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; }
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)); }
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; }
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 rb_str_new2(name); return Qnil; }
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 101: def columns 102: get_metadata unless @columns 103: return @columns 104: end
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))); }
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; }
# File lib/sqlite3/statement.rb, line 106 106: def each 107: loop do 108: val = step 109: break self if done? 110: yield val 111: end 112: end
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 #.
Example:
stmt = db.prepare( "select * from table" ) stmt.execute do |result| ... end
# File lib/sqlite3/statement.rb, line 61 61: def execute( *bind_vars ) 62: reset! if active? || done? 63: 64: bind_params(*bind_vars) unless bind_vars.empty? 65: @results = ResultSet.new(@connection, self) 66: 67: step if 0 == column_count 68: 69: yield @results if block_given? 70: @results 71: end
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 #.
Example:
stmt = db.prepare( "select * from table" ) stmt.execute! do |row| ... end
# File lib/sqlite3/statement.rb, line 87 87: def execute!( *bind_vars, &block ) 88: execute(*bind_vars) 89: block_given? ? each(&block) : to_a 90: end
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; int status; Data_Get_Struct(self, sqlite3StmtRuby, ctx); REQUIRE_OPEN_STMT(ctx); status = sqlite3_reset(ctx->st); CHECK(sqlite3_db_handle(ctx->st), status); ctx->done_p = 0; return self; }
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 117: def types 118: must_be_open! 119: get_metadata unless @types 120: @types 121: end
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 126 126: def get_metadata 127: @columns = [] 128: @types = [] 129: 130: column_count.times do |column| 131: @columns << column_name(column) 132: @types << column_decltype(column) 133: end 134: 135: @columns.freeze 136: @types.freeze 137: end
Disabled; run with --debug to generate this.
Generated with the Darkfish Rdoc Generator 1.1.6.