Package org.rocksdb

Class BackupEngine

  • All Implemented Interfaces:
    java.lang.AutoCloseable
    public class BackupEngine
extends RocksObject
implements java.lang.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.

    • 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,
                                        java.lang.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 java.util.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,
                                java.lang.String dbDir,
                                java.lang.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​(java.lang.String dbDir,
                                      java.lang.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