class SQLite3::Backup

Public Class Methods

SQLite3::Backup.new(dstdb, dstname, srcdb, srcname)

Source

static VALUE
initialize(VALUE self, VALUE dstdb, VALUE dstname, VALUE srcdb, VALUE srcname)
{
    sqlite3BackupRubyPtr ctx;
    sqlite3RubyPtr ddb_ctx, sdb_ctx;
    sqlite3_backup *pBackup;

    TypedData_Get_Struct(self, sqlite3BackupRuby, &backup_type, ctx);
    ddb_ctx = sqlite3_database_unwrap(dstdb);
    sdb_ctx = sqlite3_database_unwrap(srcdb);

    if (!sdb_ctx->db) {
        rb_raise(rb_eArgError, "cannot backup from a closed database");
    }
    if (!ddb_ctx->db) {
        rb_raise(rb_eArgError, "cannot backup to a closed database");
    }

    pBackup = sqlite3_backup_init(ddb_ctx->db, StringValuePtr(dstname),
                                  sdb_ctx->db, StringValuePtr(srcname));
    if (pBackup) {
        ctx->p = pBackup;
    } else {
        CHECK(ddb_ctx->db, sqlite3_errcode(ddb_ctx->db));
    }

    return self;
}

Initialize backup the backup.

dstdb:

the destination SQLite3::Database object.

dstname:

the destination's database name.

srcdb:

the source SQLite3::Database object.

srcname:

the source's database name.

The database name is “main”, “temp”, or the name specified in an ATTACH statement.

This feature requires SQLite 3.6.11 or later.

require 'sqlite3'
sdb = SQLite3::Database.new('src.sqlite3')

ddb = SQLite3::Database.new(':memory:')
b = SQLite3::Backup.new(ddb, 'main', sdb, 'main')
p [b.remaining, b.pagecount] # invalid value; for example [0, 0]
begin
  p b.step(1) #=> OK or DONE
  p [b.remaining, b.pagecount]
end while b.remaining > 0
b.finish

ddb = SQLite3::Database.new(':memory:')
b = SQLite3::Backup.new(ddb, 'main', sdb, 'main')
b.step(-1) #=> DONE
b.finish

Public Instance Methods

SQLite3::Backup#finish

Source

static VALUE
finish(VALUE self)
{
    sqlite3BackupRubyPtr ctx;

    TypedData_Get_Struct(self, sqlite3BackupRuby, &backup_type, ctx);
    REQUIRE_OPEN_BACKUP(ctx);
    (void)sqlite3_backup_finish(ctx->p);
    ctx->p = NULL;
    return Qnil;
}

Destroy the backup object.

SQLite3::Backup#pagecount

Source

static VALUE
pagecount(VALUE self)
{
    sqlite3BackupRubyPtr ctx;

    TypedData_Get_Struct(self, sqlite3BackupRuby, &backup_type, ctx);
    REQUIRE_OPEN_BACKUP(ctx);
    return INT2NUM(sqlite3_backup_pagecount(ctx->p));
}

Returns the total number of pages in the source database file.

Note that the value is only updated after step() is called, so before calling step() returned value is invalid.

SQLite3::Backup#remaining

Source

static VALUE
remaining(VALUE self)
{
    sqlite3BackupRubyPtr ctx;

    TypedData_Get_Struct(self, sqlite3BackupRuby, &backup_type, ctx);
    REQUIRE_OPEN_BACKUP(ctx);
    return INT2NUM(sqlite3_backup_remaining(ctx->p));
}

Returns the number of pages still to be backed up.

Note that the value is only updated after step() is called, so before calling step() returned value is invalid.

SQLite3::Backup#step(nPage)

Source

static VALUE
step(VALUE self, VALUE nPage)
{
    sqlite3BackupRubyPtr ctx;
    int status;

    TypedData_Get_Struct(self, sqlite3BackupRuby, &backup_type, ctx);
    REQUIRE_OPEN_BACKUP(ctx);
    status = sqlite3_backup_step(ctx->p, NUM2INT(nPage));
    return INT2NUM(status);
}

Copy database pages up to nPage. If negative, copy all remaining source pages.

If all pages are copied, it returns SQLite3::Constants::ErrorCode::DONE. When coping is not done, it returns SQLite3::Constants::ErrorCode::OK. When some errors occur, it returns the error code.