public class BackupEngine extends RocksObject implements java.lang.AutoCloseable
Be aware, that `new BackupEngine` takes time proportional to the amount of backups. So if you have a slow filesystem to backup 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.
nativeHandle_
owningHandle_
Modifier | Constructor and Description |
---|---|
protected |
BackupEngine(long nativeHandle) |
Modifier and Type | Method and Description |
---|---|
void |
createNewBackup(RocksDB db)
Captures the state of the database in the latest backup
|
void |
createNewBackup(RocksDB db,
boolean flushBeforeBackup)
Captures the state of the database in the latest backup
|
void |
createNewBackupWithMetadata(RocksDB db,
java.lang.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.
|
java.util.List<BackupInfo> |
getBackupInfo()
Gets information about the available
backups
|
int[] |
getCorruptedBackups()
Returns a list of corrupted backup ids.
|
static BackupEngine |
open(Env env,
BackupEngineOptions options)
Opens a new Backup Engine
|
void |
purgeOldBackups(int numBackupsToKeep)
Deletes old backups, keeping just the latest numBackupsToKeep
|
void |
restoreDbFromBackup(int backupId,
java.lang.String dbDir,
java.lang.String walDir,
RestoreOptions restoreOptions)
Restore the database from a backup
|
void |
restoreDbFromLatestBackup(java.lang.String dbDir,
java.lang.String walDir,
RestoreOptions restoreOptions)
Restore the database from the latest backup
|
disposeInternal, getNativeHandle
close, disOwnNativeHandle, isOwningHandle
public static BackupEngine open(Env env, BackupEngineOptions options) throws RocksDBException
env
- The environment that the backup engine should operate withinoptions
- Any options for the backup engineRocksDBException
- thrown if the backup engine could not be openedpublic void createNewBackup(RocksDB db) throws RocksDBException
Just a convenience for createNewBackup(RocksDB, boolean)
with
the flushBeforeBackup parameter set to false
db
- The database to backup
Note - This method is not thread safe
RocksDBException
- thrown if a new backup could not be createdpublic void createNewBackup(RocksDB db, boolean flushBeforeBackup) throws RocksDBException
db
- The database to backupflushBeforeBackup
- 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
RocksDBException
- thrown if a new backup could not be createdpublic void createNewBackupWithMetadata(RocksDB db, java.lang.String metadata, boolean flushBeforeBackup) throws RocksDBException
db
- The database to backupmetadata
- Application metadataflushBeforeBackup
- 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
RocksDBException
- thrown if a new backup could not be createdpublic java.util.List<BackupInfo> getBackupInfo()
public int[] getCorruptedBackups()
Returns a list of corrupted backup ids. If there is no corrupted backup the method will return an empty list.
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.
RocksDBException
- thrown if error happens in underlying
native library.public void purgeOldBackups(int numBackupsToKeep) throws RocksDBException
numBackupsToKeep
- The latest n backups to keepRocksDBException
- thrown if the old backups could not be deletedpublic void deleteBackup(int backupId) throws RocksDBException
backupId
- The id of the backup to deleteRocksDBException
- thrown if the backup could not be deletedpublic void restoreDbFromBackup(int backupId, java.lang.String dbDir, java.lang.String walDir, RestoreOptions restoreOptions) throws RocksDBException
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.
backupId
- The id of the backup to restoredbDir
- The directory to restore the backup to, i.e. where your
database iswalDir
- The location of the log files for your database,
often the same as dbDirrestoreOptions
- Options for controlling the restoreRocksDBException
- thrown if the database could not be restoredpublic void restoreDbFromLatestBackup(java.lang.String dbDir, java.lang.String walDir, RestoreOptions restoreOptions) throws RocksDBException
dbDir
- The directory to restore the backup to, i.e. where your
database iswalDir
- The location of the log files for your database, often the
same as dbDirrestoreOptions
- Options for controlling the restoreRocksDBException
- thrown if the database could not be restoredprotected final void disposeInternal(long handle)
disposeInternal
in class RocksObject