ceph/src/rocksdb/java/src/main/java/org/rocksdb/BackupEngine.java

   1 // Copyright (c) 2011-present, Facebook, Inc.  All rights reserved.
   2 //  This source code is licensed under both the GPLv2 (found in the
   3 //  COPYING file in the root directory) and Apache 2.0 License
   4 //  (found in the LICENSE.Apache file in the root directory).
   5 package org.rocksdb;
   6
   7 import java.util.List;
   8
   9 /**
  10  * BackupEngine allows you to backup
  11  * and restore the database
  12  *
  13  * Be aware, that `new BackupEngine` takes time proportional to the amount
  14  * of backups. So if you have a slow filesystem to backup (like HDFS)
  15  * and you have a lot of backups then restoring can take some time.
  16  * That's why we recommend to limit the number of backups.
  17  * Also we recommend to keep BackupEngine alive and not to recreate it every
  18  * time you need to do a backup.
  19  */
  20 public class BackupEngine extends RocksObject implements AutoCloseable {
  21
  22   protected BackupEngine(final long nativeHandle) {
  23     super(nativeHandle);
  24   }
  25
  26   /**
  27    * Opens a new Backup Engine
  28    *
  29    * @param env The environment that the backup engine should operate within
  30    * @param options Any options for the backup engine
  31    *
  32    * @return A new BackupEngine instance
  33    * @throws RocksDBException thrown if the backup engine could not be opened
  34    */
  35   public static BackupEngine open(final Env env,
  36       final BackupableDBOptions options) throws RocksDBException {
  37     return new BackupEngine(open(env.nativeHandle_, options.nativeHandle_));
  38   }
  39
  40   /**
  41    * Captures the state of the database in the latest backup
  42    *
  43    * Just a convenience for {@link #createNewBackup(RocksDB, boolean)} with
  44    * the flushBeforeBackup parameter set to false
  45    *
  46    * @param db The database to backup
  47    *
  48    * Note - This method is not thread safe
  49    *
  50    * @throws RocksDBException thrown if a new backup could not be created
  51    */
  52   public void createNewBackup(final RocksDB db) throws RocksDBException {
  53     createNewBackup(db, false);
  54   }
  55
  56   /**
  57    * Captures the state of the database in the latest backup
  58    *
  59    * @param db The database to backup
  60    * @param flushBeforeBackup When true, the Backup Engine will first issue a
  61    *                          memtable flush and only then copy the DB files to
  62    *                          the backup directory. Doing so will prevent log
  63    *                          files from being copied to the backup directory
  64    *                          (since flush will delete them).
  65    *                          When false, the Backup Engine will not issue a
  66    *                          flush before starting the backup. In that case,
  67    *                          the backup will also include log files
  68    *                          corresponding to live memtables. The backup will
  69    *                          always be consistent with the current state of the
  70    *                          database regardless of the flushBeforeBackup
  71    *                          parameter.
  72    *
  73    * Note - This method is not thread safe
  74    *
  75    * @throws RocksDBException thrown if a new backup could not be created
  76    */
  77   public void createNewBackup(
  78       final RocksDB db, final boolean flushBeforeBackup)
  79       throws RocksDBException {
  80     assert (isOwningHandle());
  81     createNewBackup(nativeHandle_, db.nativeHandle_, flushBeforeBackup);
  82   }
  83
  84   /**
  85    * Captures the state of the database in the latest backup along with
  86    * application specific metadata.
  87    *
  88    * @param db The database to backup
  89    * @param metadata Application metadata
  90    * @param flushBeforeBackup When true, the Backup Engine will first issue a
  91    *                          memtable flush and only then copy the DB files to
  92    *                          the backup directory. Doing so will prevent log
  93    *                          files from being copied to the backup directory
  94    *                          (since flush will delete them).
  95    *                          When false, the Backup Engine will not issue a
  96    *                          flush before starting the backup. In that case,
  97    *                          the backup will also include log files
  98    *                          corresponding to live memtables. The backup will
  99    *                          always be consistent with the current state of the
 100    *                          database regardless of the flushBeforeBackup
 101    *                          parameter.
 102    *
 103    * Note - This method is not thread safe
 104    *
 105    * @throws RocksDBException thrown if a new backup could not be created
 106    */
 107   public void createNewBackupWithMetadata(final RocksDB db, final String metadata,
 108       final boolean flushBeforeBackup) throws RocksDBException {
 109     assert (isOwningHandle());
 110     createNewBackupWithMetadata(nativeHandle_, db.nativeHandle_, metadata, flushBeforeBackup);
 111   }
 112
 113   /**
 114    * Gets information about the available
 115    * backups
 116    *
 117    * @return A list of information about each available backup
 118    */
 119   public List<BackupInfo> getBackupInfo() {
 120     assert (isOwningHandle());
 121     return getBackupInfo(nativeHandle_);
 122   }
 123
 124   /**
 125    * <p>Returns a list of corrupted backup ids. If there
 126    * is no corrupted backup the method will return an
 127    * empty list.</p>
 128    *
 129    * @return array of backup ids as int ids.
 130    */
 131   public int[] getCorruptedBackups() {
 132     assert(isOwningHandle());
 133     return getCorruptedBackups(nativeHandle_);
 134   }
 135
 136   /**
 137    * <p>Will delete all the files we don't need anymore. It will
 138    * do the full scan of the files/ directory and delete all the
 139    * files that are not referenced.</p>
 140    *
 141    * @throws RocksDBException thrown if error happens in underlying
 142    *    native library.
 143    */
 144   public void garbageCollect() throws RocksDBException {
 145     assert(isOwningHandle());
 146     garbageCollect(nativeHandle_);
 147   }
 148
 149   /**
 150    * Deletes old backups, keeping just the latest numBackupsToKeep
 151    *
 152    * @param numBackupsToKeep The latest n backups to keep
 153    *
 154    * @throws RocksDBException thrown if the old backups could not be deleted
 155    */
 156   public void purgeOldBackups(
 157       final int numBackupsToKeep) throws RocksDBException {
 158     assert (isOwningHandle());
 159     purgeOldBackups(nativeHandle_, numBackupsToKeep);
 160   }
 161
 162   /**
 163    * Deletes a backup
 164    *
 165    * @param backupId The id of the backup to delete
 166    *
 167    * @throws RocksDBException thrown if the backup could not be deleted
 168    */
 169   public void deleteBackup(final int backupId) throws RocksDBException {
 170     assert (isOwningHandle());
 171     deleteBackup(nativeHandle_, backupId);
 172   }
 173
 174   /**
 175    * Restore the database from a backup
 176    *
 177    * IMPORTANT: if options.share_table_files == true and you restore the DB
 178    * from some backup that is not the latest, and you start creating new
 179    * backups from the new DB, they will probably fail!
 180    *
 181    * Example: Let's say you have backups 1, 2, 3, 4, 5 and you restore 3.
 182    * If you add new data to the DB and try creating a new backup now, the
 183    * database will diverge from backups 4 and 5 and the new backup will fail.
 184    * If you want to create new backup, you will first have to delete backups 4
 185    * and 5.
 186    *
 187    * @param backupId The id of the backup to restore
 188    * @param dbDir The directory to restore the backup to, i.e. where your
 189    *              database is
 190    * @param walDir The location of the log files for your database,
 191    *               often the same as dbDir
 192    * @param restoreOptions Options for controlling the restore
 193    *
 194    * @throws RocksDBException thrown if the database could not be restored
 195    */
 196   public void restoreDbFromBackup(
 197       final int backupId, final String dbDir, final String walDir,
 198       final RestoreOptions restoreOptions) throws RocksDBException {
 199     assert (isOwningHandle());
 200     restoreDbFromBackup(nativeHandle_, backupId, dbDir, walDir,
 201         restoreOptions.nativeHandle_);
 202   }
 203
 204   /**
 205    * Restore the database from the latest backup
 206    *
 207    * @param dbDir The directory to restore the backup to, i.e. where your
 208    *              database is
 209    * @param walDir The location of the log files for your database, often the
 210    *               same as dbDir
 211    * @param restoreOptions Options for controlling the restore
 212    *
 213    * @throws RocksDBException thrown if the database could not be restored
 214    */
 215   public void restoreDbFromLatestBackup(
 216       final String dbDir, final String walDir,
 217       final RestoreOptions restoreOptions) throws RocksDBException {
 218     assert (isOwningHandle());
 219     restoreDbFromLatestBackup(nativeHandle_, dbDir, walDir,
 220         restoreOptions.nativeHandle_);
 221   }
 222
 223   private native static long open(final long env,
 224       final long backupableDbOptions) throws RocksDBException;
 225
 226   private native void createNewBackup(final long handle, final long dbHandle,
 227       final boolean flushBeforeBackup) throws RocksDBException;
 228
 229   private native void createNewBackupWithMetadata(final long handle, final long dbHandle,
 230       final String metadata, final boolean flushBeforeBackup) throws RocksDBException;
 231
 232   private native List<BackupInfo> getBackupInfo(final long handle);
 233
 234   private native int[] getCorruptedBackups(final long handle);
 235
 236   private native void garbageCollect(final long handle) throws RocksDBException;
 237
 238   private native void purgeOldBackups(final long handle,
 239       final int numBackupsToKeep) throws RocksDBException;
 240
 241   private native void deleteBackup(final long handle, final int backupId)
 242       throws RocksDBException;
 243
 244   private native void restoreDbFromBackup(final long handle, final int backupId,
 245       final String dbDir, final String walDir, final long restoreOptionsHandle)
 246       throws RocksDBException;
 247
 248   private native void restoreDbFromLatestBackup(final long handle,
 249       final String dbDir, final String walDir, final long restoreOptionsHandle)
 250       throws RocksDBException;
 251
 252   @Override protected final native void disposeInternal(final long handle);
 253 }