Class BackupEngine

Namespace

RocksDbNet

Assembly

RocksDb.Net.dll

Manages backups of a RocksDb database. Maps to rocksdb_backup_engine_t.

public sealed class BackupEngine : RocksDbHandle, IDisposable

Inheritance

object

RocksDbHandle

BackupEngine

Implements

IDisposable

Inherited Members

RocksDbHandle.Handle

RocksDbHandle.Owned

RocksDbHandle.IsDisposed

RocksDbHandle.ThrowIfDisposed()

RocksDbHandle.Dispose()

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Methods

AsEnumerable()

Returns metadata for all available backups (newest first).

public IReadOnlyList<BackupInfo> AsEnumerable()

Returns

IReadOnlyList<BackupInfo>

Remarks

Read in full before returning, rather than streamed. This used to be a lazy iterator holding the native info object open across the caller's loop body, which leaked it outright if the enumerator was abandoned without being disposed: the object was a bare pointer in a local with no owner, so no finalizer would ever release it.

Reading eagerly costs nothing worth counting, since a backup directory holds tens of entries carrying a few numbers each, and it means the native snapshot lives only for the duration of this call instead of for as long as the caller takes to iterate.

CreateNewBackup(RocksDb, CreateBackupOptions)

Creates a new backup using options, and returns the identifier RocksDb assigned to it.

public uint CreateNewBackup(RocksDb db, CreateBackupOptions options)

Parameters

db RocksDb

options CreateBackupOptions

Returns

uint

CreateNewBackup(RocksDb, CreateBackupOptions, ReadOnlySpan<byte>)

Creates a new backup with application metadata attached, and returns the identifier RocksDb assigned to it.

public uint CreateNewBackup(RocksDb db, CreateBackupOptions options, ReadOnlySpan<byte> appMetadata)

Parameters

db RocksDb

The database to back up.

options CreateBackupOptions

Settings for this backup.

appMetadata ReadOnlySpan<byte>

Opaque bytes stored alongside the backup and returned in AppMetadata. RocksDb copies them, and treats them as binary, so they need not be text.

Returns

uint

CreateNewBackup(RocksDb, bool)

Creates a new backup of the database.

public void CreateNewBackup(RocksDb db, bool flushBeforeBackup = false)

Parameters

db RocksDb

flushBeforeBackup bool

DisposeHandle()

Releases the native handle. Called during disposal.

protected override void DisposeHandle()

Remarks

Protected rather than public: it destroys the native object without marking this instance disposed or clearing the handle, so calling it from outside and then disposing normally would free the same pointer twice. It was the most Dispose-looking member on the type. Callers want Dispose().

DisposeUnmanagedResources()

Releases unmanaged resources used by the current instance.

protected override void DisposeUnmanagedResources()

Remarks

Protected for the same reason as DisposeHandle().

Open(BackupEngineOptions, Env?)

Opens a backup engine configured by options, which carries the backup directory along with the sharing, rate limiting and schema settings.

public static BackupEngine Open(BackupEngineOptions options, Env? env = null)

Parameters

options BackupEngineOptions

Engine configuration. Read here and not retained.

env Env

The environment the engine reads the database through, or null for the default one. Not the backup destination, which comes from options.

Returns

BackupEngine

Remarks

The environment is required by the C API, which dereferences it without a null check, so a default one is created here when the caller passes null.

It is kept for the life of the engine, not just for this call: RocksDb hands it straight to BackupEngine::Open, which holds the pointer. A caller-supplied environment therefore has to outlive the engine, and the engine registers a hold on it so that disposing it early defers rather than freeing something RocksDb still points at. This page used to say the opposite, which for an in-memory environment was a use after free waiting to happen.

Open(DbOptions, string)

Opens a backup engine at the given path.

public static BackupEngine Open(DbOptions options, string backupPath)

Parameters

options DbOptions

backupPath string

Returns

BackupEngine

PurgeOldBackups(uint)

Removes all but the numBackupsToKeep most recent backups.

public void PurgeOldBackups(uint numBackupsToKeep)

Parameters

numBackupsToKeep uint

RestoreDbFromBackup(string, string, uint, RestoreOptions?)

Restores a specific backup to dbDir.

public void RestoreDbFromBackup(string dbDir, string walDir, uint backupId, RestoreOptions? options = null)

Parameters

dbDir string

walDir string

backupId uint

options RestoreOptions

RestoreDbFromLatestBackup(string, string)

Restores the latest backup to dbDir.

public void RestoreDbFromLatestBackup(string dbDir, string walDir)

Parameters

dbDir string

walDir string

RestoreDbFromLatestBackup(string, string, RestoreOptions)

Restores the latest backup to dbDir using explicit options.

public void RestoreDbFromLatestBackup(string dbDir, string walDir, RestoreOptions options)

Parameters

dbDir string

walDir string

options RestoreOptions

StopBackup()

Asks a backup running on another thread to stop early. The CreateNewBackup(RocksDb, CreateBackupOptions) call it interrupts fails with an error rather than returning a partial backup. This retires the engine permanently.

public void StopBackup()

Remarks

One-way, and this is the part worth knowing before calling it: every later CreateNewBackup on this engine also fails, not just the one being interrupted. To take backups again, dispose this engine and open a new one against the same directory.

Returns immediately without waiting for the backup to wind down. The interrupted backup leaves its partial state behind, which stays consistent and is cleaned up by the next CreateNewBackup or garbage collection on a new engine for that directory.

VerifyBackup(uint)

Checks that the files making up backupId are present and the expected size.

public void VerifyBackup(uint backupId)

Parameters

backupId uint

Exceptions

RocksDbException

The backup is missing files or damaged.