Class: SQLite3::Backup

Relationships & Source Files
Inherits:	Object
Defined in:	ext/sqlite3/backup.c

Class Method Summary

.new(dstdb, dstname, srcdb, srcname) constructor

Initialize backup the backup.

Instance Method Summary

#finish

Destroy the backup object.
#pagecount

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

Returns the number of pages still to be backed up.
#step(nPage)

Copy database pages up to nPage.

Constructor Details

.new(dstdb, dstname, srcdb, srcname)

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

[ GitHub ]

# File 'ext/sqlite3/backup.c', line 74


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

Instance Method Details

#finish

Destroy the backup object.

[ GitHub ]

# File 'ext/sqlite3/backup.c', line 128


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

#pagecount

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.

[ GitHub ]

# File 'ext/sqlite3/backup.c', line 164


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

#remaining

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.

[ GitHub ]

# File 'ext/sqlite3/backup.c', line 147


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

#step(nPage)

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

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

[ GitHub ]

# File 'ext/sqlite3/backup.c', line 112


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