class SQLite3::Database
Public Class Methods
Create a new Database object that opens the
given file. If utf16 is true
, the filename is interpreted as a
UTF-16 encoded string.
By default, the new database will return result rows as arrays (#results_as_hash) and has type translation disabled (#type_translation=).
static VALUE initialize(int argc, VALUE *argv, VALUE self) { sqlite3RubyPtr ctx; VALUE file; VALUE opts; VALUE zvfs; #ifdef HAVE_SQLITE3_OPEN_V2 int mode = SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE; #endif int status; Data_Get_Struct(self, sqlite3Ruby, ctx); rb_scan_args(argc, argv, "12", &file, &opts, &zvfs); #if defined StringValueCStr StringValuePtr(file); rb_check_safe_obj(file); #else Check_SafeStr(file); #endif if(NIL_P(opts)) opts = rb_hash_new(); else Check_Type(opts, T_HASH); #ifdef HAVE_RUBY_ENCODING_H if(UTF16_LE_P(file) || UTF16_BE_P(file)) { status = sqlite3_open16(utf16_string_value_ptr(file), &ctx->db); } else { #endif if(Qtrue == rb_hash_aref(opts, sym_utf16)) { status = sqlite3_open16(utf16_string_value_ptr(file), &ctx->db); } else { #ifdef HAVE_RUBY_ENCODING_H if(!UTF8_P(file)) { file = rb_str_export_to_enc(file, rb_utf8_encoding()); } #endif if (Qtrue == rb_hash_aref(opts, ID2SYM(rb_intern("readonly")))) { #ifdef HAVE_SQLITE3_OPEN_V2 mode = SQLITE_OPEN_READONLY; #else rb_raise(rb_eNotImpError, "sqlite3-ruby was compiled against a version of sqlite that does not support readonly databases"); #endif } #ifdef HAVE_SQLITE3_OPEN_V2 status = sqlite3_open_v2( StringValuePtr(file), &ctx->db, mode, NIL_P(zvfs) ? NULL : StringValuePtr(zvfs) ); #else status = sqlite3_open( StringValuePtr(file), &ctx->db ); #endif } #ifdef HAVE_RUBY_ENCODING_H } #endif CHECK(ctx->db, status) rb_iv_set(self, "@tracefunc", Qnil); rb_iv_set(self, "@authorizer", Qnil); rb_iv_set(self, "@encoding", Qnil); rb_iv_set(self, "@busy_handler", Qnil); rb_iv_set(self, "@collations", rb_hash_new()); rb_iv_set(self, "@functions", rb_hash_new()); rb_iv_set(self, "@results_as_hash", rb_hash_aref(opts, sym_results_as_hash)); rb_iv_set(self, "@type_translation", rb_hash_aref(opts, sym_type_translation)); #ifdef HAVE_SQLITE3_OPEN_V2 rb_iv_set(self, "@readonly", mode == SQLITE_OPEN_READONLY ? Qtrue : Qfalse); #else rb_iv_set(self, "@readonly", Qfalse); #endif if(rb_block_given_p()) { rb_yield(self); rb_funcall(self, rb_intern("close"), 0); } return self; }
Public Instance Methods
Register a busy handler with this database instance. When a requested
resource is busy, this handler will be invoked. If the handler returns
false
, the operation will be aborted; otherwise, the resource
will be requested again.
The handler will be invoked with the name of the resource that was busy, and the number of times it has been retried.
See also the mutually exclusive busy_timeout.
static VALUE busy_handler(int argc, VALUE *argv, VALUE self) { sqlite3RubyPtr ctx; VALUE block; int status; Data_Get_Struct(self, sqlite3Ruby, ctx); REQUIRE_OPEN_DB(ctx); rb_scan_args(argc, argv, "01", &block); if(NIL_P(block) && rb_block_given_p()) block = rb_block_proc(); rb_iv_set(self, "@busy_handler", block); status = sqlite3_busy_handler( ctx->db, NIL_P(block) ? NULL : rb_sqlite3_busy_handler, (void *)self); CHECK(ctx->db, status); return self; }
Indicates that if a request for a resource terminates because that resource
is busy, SQLite should sleep and retry for up to the indicated number of
milliseconds. By default, SQLite does not retry busy resources. To restore
the default behavior, send 0 as the ms
parameter.
See also the mutually exclusive busy_handler.
static VALUE set_busy_timeout(VALUE self, VALUE timeout) { sqlite3RubyPtr ctx; Data_Get_Struct(self, sqlite3Ruby, ctx); REQUIRE_OPEN_DB(ctx); CHECK(ctx->db, sqlite3_busy_timeout(ctx->db, (int)NUM2INT(timeout))); return self; }
Returns the number of changes made to this database instance by the last operation performed. Note that a “delete from table” without a where clause will not affect this value.
static VALUE changes(VALUE self) { sqlite3RubyPtr ctx; Data_Get_Struct(self, sqlite3Ruby, ctx); REQUIRE_OPEN_DB(ctx); return INT2NUM(sqlite3_changes(ctx->db)); }
Closes this database.
static VALUE sqlite3_rb_close(VALUE self) { sqlite3RubyPtr ctx; sqlite3 * db; Data_Get_Struct(self, sqlite3Ruby, ctx); db = ctx->db; CHECK(db, sqlite3_close(ctx->db)); ctx->db = NULL; return self; }
Returns true
if this database instance has been closed (see close).
static VALUE closed_p(VALUE self) { sqlite3RubyPtr ctx; Data_Get_Struct(self, sqlite3Ruby, ctx); if(!ctx->db) return Qtrue; return Qfalse; }
Add a collation with name name
, and a comparator
object. The comparator
object should implement a method
called “compare” that takes two parameters and returns an integer less
than, equal to, or greater than 0.
static VALUE collation(VALUE self, VALUE name, VALUE comparator) { sqlite3RubyPtr ctx; Data_Get_Struct(self, sqlite3Ruby, ctx); REQUIRE_OPEN_DB(ctx); CHECK(ctx->db, sqlite3_create_collation( ctx->db, StringValuePtr(name), SQLITE_UTF8, (void *)comparator, NIL_P(comparator) ? NULL : rb_comparator_func)); /* Make sure our comparator doesn't get garbage collected. */ rb_hash_aset(rb_iv_get(self, "@collations"), name, comparator); return self; }
Return true
if the string is a valid (ie, parsable) SQL
statement, and false
otherwise.
static VALUE complete_p(VALUE UNUSED(self), VALUE sql) { if(sqlite3_complete(StringValuePtr(sql))) return Qtrue; return Qfalse; }
Define an aggregate function named name
using the object
aggregator
. aggregator
must respond to
step
and finalize
. step
will be
called with row information and finalize
must return the
return value for the aggregator function.
static VALUE define_aggregator(VALUE self, VALUE name, VALUE aggregator) { sqlite3RubyPtr ctx; int arity, status; Data_Get_Struct(self, sqlite3Ruby, ctx); REQUIRE_OPEN_DB(ctx); arity = sqlite3_obj_method_arity(aggregator, rb_intern("step")); status = sqlite3_create_function( ctx->db, StringValuePtr(name), arity, SQLITE_UTF8, (void *)aggregator, NULL, rb_sqlite3_step, rb_sqlite3_final ); rb_iv_set(self, "@agregator", aggregator); CHECK(ctx->db, status); return self; }
Define a function named name
with args
. The
arity of the block will be used as the arity for the function defined.
static VALUE define_function(VALUE self, VALUE name) { sqlite3RubyPtr ctx; VALUE block; int status; Data_Get_Struct(self, sqlite3Ruby, ctx); REQUIRE_OPEN_DB(ctx); block = rb_block_proc(); status = sqlite3_create_function( ctx->db, StringValuePtr(name), rb_proc_arity(block), SQLITE_UTF8, (void *)block, rb_sqlite3_func, NULL, NULL ); CHECK(ctx->db, status); rb_hash_aset(rb_iv_get(self, "@functions"), name, block); return self; }
Enable or disable extension loading.
static VALUE enable_load_extension(VALUE self, VALUE onoff) { sqlite3RubyPtr ctx; int onoffparam; Data_Get_Struct(self, sqlite3Ruby, ctx); REQUIRE_OPEN_DB(ctx); if (Qtrue == onoff) { onoffparam = 1; } else if (Qfalse == onoff) { onoffparam = 0; } else { onoffparam = (int)NUM2INT(onoff); } CHECK(ctx->db, sqlite3_enable_load_extension(ctx->db, onoffparam)); return self; }
Fetch the encoding set on this database
static VALUE db_encoding(VALUE self) { sqlite3RubyPtr ctx; VALUE enc; Data_Get_Struct(self, sqlite3Ruby, ctx); REQUIRE_OPEN_DB(ctx); enc = rb_iv_get(self, "@encoding"); if(NIL_P(enc)) { sqlite3_exec(ctx->db, "PRAGMA encoding", enc_cb, (void *)self, NULL); } return rb_iv_get(self, "@encoding"); }
Return an integer representing the last error to have occurred with this database.
static VALUE errcode_(VALUE self) { sqlite3RubyPtr ctx; Data_Get_Struct(self, sqlite3Ruby, ctx); REQUIRE_OPEN_DB(ctx); return INT2NUM((long)sqlite3_errcode(ctx->db)); }
Return a string describing the last error to have occurred with this database.
static VALUE errmsg(VALUE self) { sqlite3RubyPtr ctx; Data_Get_Struct(self, sqlite3Ruby, ctx); REQUIRE_OPEN_DB(ctx); return rb_str_new2(sqlite3_errmsg(ctx->db)); }
Interrupts the currently executing operation, causing it to abort.
static VALUE interrupt(VALUE self) { sqlite3RubyPtr ctx; Data_Get_Struct(self, sqlite3Ruby, ctx); REQUIRE_OPEN_DB(ctx); sqlite3_interrupt(ctx->db); return self; }
Obtains the unique row ID of the last row to be inserted by this Database instance.
static VALUE last_insert_row_id(VALUE self) { sqlite3RubyPtr ctx; Data_Get_Struct(self, sqlite3Ruby, ctx); REQUIRE_OPEN_DB(ctx); return LL2NUM(sqlite3_last_insert_rowid(ctx->db)); }
Loads an SQLite extension library from the named file. Extension loading must be enabled using db.enable_load_extension(true) prior to calling this API.
static VALUE load_extension(VALUE self, VALUE file) { sqlite3RubyPtr ctx; int status; char *errMsg; VALUE errexp; Data_Get_Struct(self, sqlite3Ruby, ctx); REQUIRE_OPEN_DB(ctx); status = sqlite3_load_extension(ctx->db, RSTRING_PTR(file), 0, &errMsg); if (status != SQLITE_OK) { errexp = rb_exc_new2(rb_eRuntimeError, errMsg); sqlite3_free(errMsg); rb_exc_raise(errexp); } return self; }
Returns the total number of changes made to this database instance since it was opened.
static VALUE total_changes(VALUE self) { sqlite3RubyPtr ctx; Data_Get_Struct(self, sqlite3Ruby, ctx); REQUIRE_OPEN_DB(ctx); return INT2NUM((long)sqlite3_total_changes(ctx->db)); }
Installs (or removes) a block that will be invoked for every SQL statement
executed. The block receives one parameter: the SQL statement executed. If
the block is nil
, any existing tracer will be uninstalled.
static VALUE trace(int argc, VALUE *argv, VALUE self) { sqlite3RubyPtr ctx; VALUE block; Data_Get_Struct(self, sqlite3Ruby, ctx); REQUIRE_OPEN_DB(ctx); rb_scan_args(argc, argv, "01", &block); if(NIL_P(block) && rb_block_given_p()) block = rb_block_proc(); rb_iv_set(self, "@tracefunc", block); sqlite3_trace(ctx->db, NIL_P(block) ? NULL : tracefunc, (void *)self); return self; }
Returns true
if there is a transaction active, and
false
otherwise.
static VALUE transaction_active_p(VALUE self) { sqlite3RubyPtr ctx; Data_Get_Struct(self, sqlite3Ruby, ctx); REQUIRE_OPEN_DB(ctx); return sqlite3_get_autocommit(ctx->db) ? Qfalse : Qtrue; }