org.rocksdb

Class BackupEngine

java.lang.Object

org.rocksdb.AbstractNativeReference

org.rocksdb.AbstractImmutableNativeReference

org.rocksdb.RocksObject

org.rocksdb.BackupEngine

All Implemented Interfaces:

AutoCloseable

public class BackupEngine
extends RocksObject
implements AutoCloseable

BackupEngine allows you to backup and restore the database Be aware, that `new BackupEngine` takes time proportional to the amount of backups. So if you have a slow filesystem to backup (like HDFS) and you have a lot of backups then restoring can take some time. That's why we recommend to limit the number of backups. Also we recommend to keep BackupEngine alive and not to recreate it every time you need to do a backup.

Field Summary

Fields inherited from class org.rocksdb.RocksObject

nativeHandle_

Fields inherited from class org.rocksdb.AbstractImmutableNativeReference

owningHandle_

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	BackupEngine(long nativeHandle)

Method Summary

Modifier and Type	Method and Description
void	createNewBackup(RocksDB db) Captures the state of the database in the latest backup Just a convenience for createNewBackup(RocksDB, boolean) with the flushBeforeBackup parameter set to false
void	createNewBackup(RocksDB db, boolean flushBeforeBackup) Captures the state of the database in the latest backup
void	createNewBackupWithMetadata(RocksDB db, String metadata, boolean flushBeforeBackup) Captures the state of the database in the latest backup along with application specific metadata.
void	deleteBackup(int backupId) Deletes a backup
protected void	disposeInternal(long handle)
void	garbageCollect() Will delete all the files we don't need anymore.
List<BackupInfo>	getBackupInfo() Gets information about the available backups
int[]	getCorruptedBackups() Returns a list of corrupted backup ids.
static BackupEngine	open(Env env, BackupableDBOptions options) Opens a new Backup Engine
void	purgeOldBackups(int numBackupsToKeep) Deletes old backups, keeping just the latest numBackupsToKeep
void	restoreDbFromBackup(int backupId, String dbDir, String walDir, RestoreOptions restoreOptions) Restore the database from a backup IMPORTANT: if options.share_table_files == true and you restore the DB from some backup that is not the latest, and you start creating new backups from the new DB, they will probably fail!
void	restoreDbFromLatestBackup(String dbDir, String walDir, RestoreOptions restoreOptions) Restore the database from the latest backup

Methods inherited from class org.rocksdb.RocksObject

disposeInternal, getNativeHandle

Methods inherited from class org.rocksdb.AbstractImmutableNativeReference

close, disOwnNativeHandle, isOwningHandle

Methods inherited from class org.rocksdb.AbstractNativeReference

dispose, finalize

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface java.lang.AutoCloseable

close

Constructor Detail

BackupEngine

protected BackupEngine(long nativeHandle)

Method Detail

open

public static BackupEngine open(Env env,
                                BackupableDBOptions options)
                         throws RocksDBException

Opens a new Backup Engine

Parameters:

env - The environment that the backup engine should operate within

options - Any options for the backup engine

Returns:

A new BackupEngine instance

Throws:

RocksDBException - thrown if the backup engine could not be opened

createNewBackup

public void createNewBackup(RocksDB db)
                     throws RocksDBException

Captures the state of the database in the latest backup Just a convenience for createNewBackup(RocksDB, boolean) with the flushBeforeBackup parameter set to false

Parameters:

db - The database to backup Note - This method is not thread safe

Throws:

RocksDBException - thrown if a new backup could not be created

createNewBackup

public void createNewBackup(RocksDB db,
                            boolean flushBeforeBackup)
                     throws RocksDBException

Captures the state of the database in the latest backup

Parameters:

db - The database to backup

flushBeforeBackup - When true, the Backup Engine will first issue a memtable flush and only then copy the DB files to the backup directory. Doing so will prevent log files from being copied to the backup directory (since flush will delete them). When false, the Backup Engine will not issue a flush before starting the backup. In that case, the backup will also include log files corresponding to live memtables. If writes have been performed with the write ahead log disabled, set flushBeforeBackup to true to prevent those writes from being lost. Otherwise, the backup will always be consistent with the current state of the database regardless of the flushBeforeBackup parameter. Note - This method is not thread safe

Throws:

RocksDBException - thrown if a new backup could not be created

createNewBackupWithMetadata

public void createNewBackupWithMetadata(RocksDB db,
                                        String metadata,
                                        boolean flushBeforeBackup)
                                 throws RocksDBException

Captures the state of the database in the latest backup along with application specific metadata.

Parameters:

db - The database to backup

metadata - Application metadata

flushBeforeBackup - When true, the Backup Engine will first issue a memtable flush and only then copy the DB files to the backup directory. Doing so will prevent log files from being copied to the backup directory (since flush will delete them). When false, the Backup Engine will not issue a flush before starting the backup. In that case, the backup will also include log files corresponding to live memtables. If writes have been performed with the write ahead log disabled, set flushBeforeBackup to true to prevent those writes from being lost. Otherwise, the backup will always be consistent with the current state of the database regardless of the flushBeforeBackup parameter. Note - This method is not thread safe

Throws:

RocksDBException - thrown if a new backup could not be created

getBackupInfo

public List<BackupInfo> getBackupInfo()

Gets information about the available backups

Returns:

A list of information about each available backup

getCorruptedBackups

public int[] getCorruptedBackups()

Returns a list of corrupted backup ids. If there is no corrupted backup the method will return an empty list.

Returns:

array of backup ids as int ids.

garbageCollect

public void garbageCollect()
                    throws RocksDBException

Will delete all the files we don't need anymore. It will do the full scan of the files/ directory and delete all the files that are not referenced.

Throws:

RocksDBException - thrown if error happens in underlying native library.

purgeOldBackups

public void purgeOldBackups(int numBackupsToKeep)
                     throws RocksDBException

Deletes old backups, keeping just the latest numBackupsToKeep

Parameters:

numBackupsToKeep - The latest n backups to keep

Throws:

RocksDBException - thrown if the old backups could not be deleted

deleteBackup

public void deleteBackup(int backupId)
                  throws RocksDBException

Deletes a backup

Parameters:

backupId - The id of the backup to delete

Throws:

RocksDBException - thrown if the backup could not be deleted

restoreDbFromBackup

public void restoreDbFromBackup(int backupId,
                                String dbDir,
                                String walDir,
                                RestoreOptions restoreOptions)
                         throws RocksDBException

Restore the database from a backup IMPORTANT: if options.share_table_files == true and you restore the DB from some backup that is not the latest, and you start creating new backups from the new DB, they will probably fail! Example: Let's say you have backups 1, 2, 3, 4, 5 and you restore 3. If you add new data to the DB and try creating a new backup now, the database will diverge from backups 4 and 5 and the new backup will fail. If you want to create new backup, you will first have to delete backups 4 and 5.

Parameters:

backupId - The id of the backup to restore

dbDir - The directory to restore the backup to, i.e. where your database is

walDir - The location of the log files for your database, often the same as dbDir

restoreOptions - Options for controlling the restore

Throws:

RocksDBException - thrown if the database could not be restored

restoreDbFromLatestBackup

public void restoreDbFromLatestBackup(String dbDir,
                                      String walDir,
                                      RestoreOptions restoreOptions)
                               throws RocksDBException

Restore the database from the latest backup

Parameters:

dbDir - The directory to restore the backup to, i.e. where your database is

walDir - The location of the log files for your database, often the same as dbDir

restoreOptions - Options for controlling the restore

Throws:

RocksDBException - thrown if the database could not be restored

disposeInternal

protected final void disposeInternal(long handle)

Specified by:

disposeInternal in class RocksObject