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 the BSD-style license found in the
   3 // LICENSE file in the root directory of this source tree. An additional grant
   4 // of patent rights can be found in the PATENTS file in the same 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    * Gets information about the available
  86    * backups
  87    *
  88    * @return A list of information about each available backup
  89    */
  90   public List<BackupInfo> getBackupInfo() {
  91     assert (isOwningHandle());
  92     return getBackupInfo(nativeHandle_);
  93   }
  94
  95   /**
  96    * <p>Returns a list of corrupted backup ids. If there
  97    * is no corrupted backup the method will return an
  98    * empty list.</p>
  99    *
 100    * @return array of backup ids as int ids.
 101    */
 102   public int[] getCorruptedBackups() {
 103     assert(isOwningHandle());
 104     return getCorruptedBackups(nativeHandle_);
 105   }
 106
 107   /**
 108    * <p>Will delete all the files we don't need anymore. It will
 109    * do the full scan of the files/ directory and delete all the
 110    * files that are not referenced.</p>
 111    *
 112    * @throws RocksDBException thrown if error happens in underlying
 113    *    native library.
 114    */
 115   public void garbageCollect() throws RocksDBException {
 116     assert(isOwningHandle());
 117     garbageCollect(nativeHandle_);
 118   }
 119
 120   /**
 121    * Deletes old backups, keeping just the latest numBackupsToKeep
 122    *
 123    * @param numBackupsToKeep The latest n backups to keep
 124    *
 125    * @throws RocksDBException thrown if the old backups could not be deleted
 126    */
 127   public void purgeOldBackups(
 128       final int numBackupsToKeep) throws RocksDBException {
 129     assert (isOwningHandle());
 130     purgeOldBackups(nativeHandle_, numBackupsToKeep);
 131   }
 132
 133   /**
 134    * Deletes a backup
 135    *
 136    * @param backupId The id of the backup to delete
 137    *
 138    * @throws RocksDBException thrown if the backup could not be deleted
 139    */
 140   public void deleteBackup(final int backupId) throws RocksDBException {
 141     assert (isOwningHandle());
 142     deleteBackup(nativeHandle_, backupId);
 143   }
 144
 145   /**
 146    * Restore the database from a backup
 147    *
 148    * IMPORTANT: if options.share_table_files == true and you restore the DB
 149    * from some backup that is not the latest, and you start creating new
 150    * backups from the new DB, they will probably fail!
 151    *
 152    * Example: Let's say you have backups 1, 2, 3, 4, 5 and you restore 3.
 153    * If you add new data to the DB and try creating a new backup now, the
 154    * database will diverge from backups 4 and 5 and the new backup will fail.
 155    * If you want to create new backup, you will first have to delete backups 4
 156    * and 5.
 157    *
 158    * @param backupId The id of the backup to restore
 159    * @param dbDir The directory to restore the backup to, i.e. where your
 160    *              database is
 161    * @param walDir The location of the log files for your database,
 162    *               often the same as dbDir
 163    * @param restoreOptions Options for controlling the restore
 164    *
 165    * @throws RocksDBException thrown if the database could not be restored
 166    */
 167   public void restoreDbFromBackup(
 168       final int backupId, final String dbDir, final String walDir,
 169       final RestoreOptions restoreOptions) throws RocksDBException {
 170     assert (isOwningHandle());
 171     restoreDbFromBackup(nativeHandle_, backupId, dbDir, walDir,
 172         restoreOptions.nativeHandle_);
 173   }
 174
 175   /**
 176    * Restore the database from the latest backup
 177    *
 178    * @param dbDir The directory to restore the backup to, i.e. where your
 179    *              database is
 180    * @param walDir The location of the log files for your database, often the
 181    *               same as dbDir
 182    * @param restoreOptions Options for controlling the restore
 183    *
 184    * @throws RocksDBException thrown if the database could not be restored
 185    */
 186   public void restoreDbFromLatestBackup(
 187       final String dbDir, final String walDir,
 188       final RestoreOptions restoreOptions) throws RocksDBException {
 189     assert (isOwningHandle());
 190     restoreDbFromLatestBackup(nativeHandle_, dbDir, walDir,
 191         restoreOptions.nativeHandle_);
 192   }
 193
 194   private native static long open(final long env,
 195       final long backupableDbOptions) throws RocksDBException;
 196
 197   private native void createNewBackup(final long handle, final long dbHandle,
 198       final boolean flushBeforeBackup) throws RocksDBException;
 199
 200   private native List<BackupInfo> getBackupInfo(final long handle);
 201
 202   private native int[] getCorruptedBackups(final long handle);
 203
 204   private native void garbageCollect(final long handle) throws RocksDBException;
 205
 206   private native void purgeOldBackups(final long handle,
 207       final int numBackupsToKeep) throws RocksDBException;
 208
 209   private native void deleteBackup(final long handle, final int backupId)
 210       throws RocksDBException;
 211
 212   private native void restoreDbFromBackup(final long handle, final int backupId,
 213       final String dbDir, final String walDir, final long restoreOptionsHandle)
 214       throws RocksDBException;
 215
 216   private native void restoreDbFromLatestBackup(final long handle,
 217       final String dbDir, final String walDir, final long restoreOptionsHandle)
 218       throws RocksDBException;
 219
 220   @Override protected final native void disposeInternal(final long handle);
 221 }