class SQLite3::Database - RDoc Documentation

Source

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

    TypedData_Get_Struct(self, sqlite3Ruby, &database_type, 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;
}

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.

busy_handler { |count| ... }

busy_handler(Class.new { def call count; end }.new)

Source

static VALUE
busy_handler(int argc, VALUE *argv, VALUE self)
{
    sqlite3RubyPtr ctx;
    VALUE block;
    int status;

    TypedData_Get_Struct(self, sqlite3Ruby, &database_type, 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_OBJ_WRITE(self, &ctx->busy_handler, block);

    status = sqlite3_busy_handler(
                 ctx->db,
                 NIL_P(block) ? NULL : rb_sqlite3_busy_handler,
                 (void *)ctx
             );

    CHECK(ctx->db, status);

    return self;
}

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.

busy_timeout = ms

Source

static VALUE
set_busy_timeout(VALUE self, VALUE timeout)
{
    sqlite3RubyPtr ctx;
    TypedData_Get_Struct(self, sqlite3Ruby, &database_type, ctx);
    REQUIRE_OPEN_DB(ctx);

    CHECK(ctx->db, sqlite3_busy_timeout(ctx->db, (int)NUM2INT(timeout)));

    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.

changes

Source

static VALUE
changes(VALUE self)
{
    sqlite3RubyPtr ctx;
    TypedData_Get_Struct(self, sqlite3Ruby, &database_type, ctx);
    REQUIRE_OPEN_DB(ctx);

    return INT2NUM(sqlite3_changes(ctx->db));
}

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.

close ()

Source

static VALUE
sqlite3_rb_close(VALUE self)
{
    sqlite3RubyPtr ctx;
    TypedData_Get_Struct(self, sqlite3Ruby, &database_type, ctx);

    close_or_discard_db(ctx);

    rb_iv_set(self, "-aggregators", Qnil);

    return self;
}

Close the database and release all associated resources.

⚠ Writable connections that are carried across a fork() are not completely closed. Sqlite does not support forking, and fully closing a writable connection that has been carried across a fork may corrupt the database. Since it is an incomplete close, not all memory resources are freed, but this is safer than risking data loss.

See adr/2024-09-fork-safety.md for more information on fork safety.

closed?

Source

static VALUE
closed_p(VALUE self)
{
    sqlite3RubyPtr ctx;
    TypedData_Get_Struct(self, sqlite3Ruby, &database_type, ctx);

    if (!ctx->db) { return Qtrue; }

    return Qfalse;
}

Returns true if this database instance has been closed (see close).

collation(name, comparator)

Source

static VALUE
collation(VALUE self, VALUE name, VALUE comparator)
{
    sqlite3RubyPtr ctx;
    TypedData_Get_Struct(self, sqlite3Ruby, &database_type, 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;
}

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.

complete?(sql)

Source

static VALUE
complete_p(VALUE UNUSED(self), VALUE sql)
{
    if (sqlite3_complete(StringValuePtr(sql))) {
        return Qtrue;
    }

    return Qfalse;
}

Return true if the string is a valid (ie, parsable) SQL statement, and false otherwise.

define_function(name) { |args,...| }

Source

static VALUE
define_function(VALUE self, VALUE name)
{
    return define_function_with_flags(self, name, INT2FIX(SQLITE_UTF8));
}

Define a function named name with args. The arity of the block will be used as the arity for the function defined.

define_function_with_flags(name, flags) { |args,...| }

Source

static VALUE
define_function_with_flags(VALUE self, VALUE name, VALUE flags)
{
    sqlite3RubyPtr ctx;
    VALUE block;
    int status;

    TypedData_Get_Struct(self, sqlite3Ruby, &database_type, ctx);
    REQUIRE_OPEN_DB(ctx);

    block = rb_block_proc();

    status = sqlite3_create_function(
                 ctx->db,
                 StringValuePtr(name),
                 rb_proc_arity(block),
                 NUM2INT(flags),
                 (void *)block,
                 rb_sqlite3_func,
                 NULL,
                 NULL
             );

    CHECK(ctx->db, status);

    rb_hash_aset(rb_iv_get(self, "@functions"), name, block);

    return self;
}

Define a function named name with args using TextRep bitflags flags. The arity of the block will be used as the arity for the function defined.

enable_load_extension(onoff)

Source

static VALUE
enable_load_extension(VALUE self, VALUE onoff)
{
    sqlite3RubyPtr ctx;
    int onoffparam;
    TypedData_Get_Struct(self, sqlite3Ruby, &database_type, 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;
}

Enable or disable extension loading.

errcode

Source

static VALUE
errcode_(VALUE self)
{
    sqlite3RubyPtr ctx;
    TypedData_Get_Struct(self, sqlite3Ruby, &database_type, ctx);
    REQUIRE_OPEN_DB(ctx);

    return INT2NUM(sqlite3_errcode(ctx->db));
}

Return an integer representing the last error to have occurred with this database.

errmsg

Source

static VALUE
errmsg(VALUE self)
{
    sqlite3RubyPtr ctx;
    TypedData_Get_Struct(self, sqlite3Ruby, &database_type, ctx);
    REQUIRE_OPEN_DB(ctx);

    return rb_str_new2(sqlite3_errmsg(ctx->db));
}

Return a string describing the last error to have occurred with this database.

extended_result_codes = true

Source

static VALUE
set_extended_result_codes(VALUE self, VALUE enable)
{
    sqlite3RubyPtr ctx;
    TypedData_Get_Struct(self, sqlite3Ruby, &database_type, ctx);
    REQUIRE_OPEN_DB(ctx);

    CHECK(ctx->db, sqlite3_extended_result_codes(ctx->db, RTEST(enable) ? 1 : 0));

    return self;
}

Enable extended result codes in SQLite. These result codes allow for more detailed exception reporting, such a which type of constraint is violated.

interrupt

Source

static VALUE
interrupt(VALUE self)
{
    sqlite3RubyPtr ctx;
    TypedData_Get_Struct(self, sqlite3Ruby, &database_type, ctx);
    REQUIRE_OPEN_DB(ctx);

    sqlite3_interrupt(ctx->db);

    return self;
}

Interrupts the currently executing operation, causing it to abort.

last_insert_row_id

Source

static VALUE
last_insert_row_id(VALUE self)
{
    sqlite3RubyPtr ctx;
    TypedData_Get_Struct(self, sqlite3Ruby, &database_type, ctx);
    REQUIRE_OPEN_DB(ctx);

    return LL2NUM(sqlite3_last_insert_rowid(ctx->db));
}

Obtains the unique row ID of the last row to be inserted by this Database instance.

statement_timeout = ms

Source

static VALUE
set_statement_timeout(VALUE self, VALUE milliseconds)
{
    sqlite3RubyPtr ctx;
    TypedData_Get_Struct(self, sqlite3Ruby, &database_type, ctx);

    ctx->stmt_timeout = NUM2INT(milliseconds);
    int n = NUM2INT(milliseconds) == 0 ? -1 : 1000;

    sqlite3_progress_handler(ctx->db, n, rb_sqlite3_statement_timeout, (void *)ctx);

    return self;
}

Indicates that if a query lasts longer than the indicated number of milliseconds, SQLite should interrupt that query and return an error. By default, SQLite does not interrupt queries. To restore the default behavior, send 0 as the ms parameter.

total_changes

Source

static VALUE
total_changes(VALUE self)
{
    sqlite3RubyPtr ctx;
    TypedData_Get_Struct(self, sqlite3Ruby, &database_type, ctx);
    REQUIRE_OPEN_DB(ctx);

    return INT2NUM(sqlite3_total_changes(ctx->db));
}

Returns the total number of changes made to this database instance since it was opened.

trace { |sql| ... }

trace(Class.new { def call sql; end }.new)

Source

static VALUE
trace(int argc, VALUE *argv, VALUE self)
{
    sqlite3RubyPtr ctx;
    VALUE block;

    TypedData_Get_Struct(self, sqlite3Ruby, &database_type, 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;
}

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.

transaction_active?

Source

static VALUE
transaction_active_p(VALUE self)
{
    sqlite3RubyPtr ctx;
    TypedData_Get_Struct(self, sqlite3Ruby, &database_type, ctx);
    REQUIRE_OPEN_DB(ctx);

    return sqlite3_get_autocommit(ctx->db) ? Qfalse : Qtrue;
}

Returns true if there is a transaction active, and false otherwise.