class SQLite3::Database

Public Class Methods

SQLite3::Database.new(file, options = {}) click to toggle source

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

set_authorizer = auth click to toggle source

Set the authorizer for this database. auth must respond to call, and call must take 5 arguments.

Installs (or removes) a block that will be invoked for every access to the database. If the block returns 0 (or true), the statement is allowed to proceed. Returning 1 or false causes an authorization error to occur, and returning 2 or nil causes the access to be silently denied.

static VALUE set_authorizer(VALUE self, VALUE authorizer)
{
  sqlite3RubyPtr ctx;
  int status;

  Data_Get_Struct(self, sqlite3Ruby, ctx);
  REQUIRE_OPEN_DB(ctx);

  status = sqlite3_set_authorizer(
      ctx->db, NIL_P(authorizer) ? NULL : rb_sqlite3_auth, (void *)self
  );

  CHECK(ctx->db, status);

  rb_iv_set(self, "@authorizer", authorizer);

  return self;
}
busy_handler { |count| ... } click to toggle source
busy_handler(Class.new { def call count; end }.new)

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;
}
busy_timeout = ms click to toggle source

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;
}
changes click to toggle source

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));
}
close click to toggle source

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;
}
closed? click to toggle source

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;
}
collation(name, comparator) click to toggle source

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;
}
complete?(sql) click to toggle source

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_aggregator(name, aggregator) click to toggle source

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_function(name) { |args,...| } click to toggle source

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_load_extension(onoff) click to toggle source

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;
}
encoding click to toggle source

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");
}
errcode click to toggle source

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));
}
errmsg click to toggle source

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));
}
interrupt click to toggle source

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;
}
last_insert_row_id click to toggle source

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));
}
load_extension(file) click to toggle source

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;
}
total_changes click to toggle source

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));
}
trace { |sql| ... } click to toggle source
trace(Class.new { def call sql; end }.new)

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;
}
transaction_active? click to toggle source

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;
}