Package 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 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 Details

    • BackupEngine

      protected BackupEngine(long nativeHandle)

  • Method Details

    • open

      public static BackupEngine open(Env env, BackupEngineOptions 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