diff --git a/HISTORY.md b/HISTORY.md index ede253dbb..5326ba0e0 100644 --- a/HISTORY.md +++ b/HISTORY.md @@ -1,4 +1,8 @@ # Rocksdb Change Log +## Unreleased +### Public API Change +* Delete deprecated classes for creating backups (BackupableDB) and restoring from backups (RestoreBackupableDB). Now, BackupEngine should be used for creating backups, and BackupEngineReadOnly should be used for restorations. For more details, see https://github.com/facebook/rocksdb/wiki/How-to-backup-RocksDB%3F + ## 4.7.0 (4/8/2016) ### Public API Change * rename options compaction_measure_io_stats to report_bg_io_stats and include flush too. diff --git a/include/rocksdb/utilities/backupable_db.h b/include/rocksdb/utilities/backupable_db.h index f77de6749..6ae211476 100644 --- a/include/rocksdb/utilities/backupable_db.h +++ b/include/rocksdb/utilities/backupable_db.h @@ -183,6 +183,8 @@ class BackupStatistics { uint32_t number_fail_backup; }; +// A backup engine for accessing information about backups and restoring from +// them. class BackupEngineReadOnly { public: virtual ~BackupEngineReadOnly() {} @@ -190,9 +192,12 @@ class BackupEngineReadOnly { static Status Open(Env* db_env, const BackupableDBOptions& options, BackupEngineReadOnly** backup_engine_ptr); + // Returns info about backups in backup_info // You can GetBackupInfo safely, even with other BackupEngine performing // backups on the same directory virtual void GetBackupInfo(std::vector* backup_info) = 0; + + // Returns info about corrupt backups in corrupt_backups virtual void GetCorruptedBackups( std::vector* corrupt_backup_ids) = 0; @@ -200,9 +205,12 @@ class BackupEngineReadOnly { // running that might call DeleteBackup() or PurgeOldBackups(). It is caller's // responsibility to synchronize the operation, i.e. don't delete the backup // when you're restoring from it + // See also the corresponding doc in BackupEngine virtual Status RestoreDBFromBackup( BackupID backup_id, const std::string& db_dir, const std::string& wal_dir, const RestoreOptions& restore_options = RestoreOptions()) = 0; + + // See the corresponding doc in BackupEngine virtual Status RestoreDBFromLatestBackup( const std::string& db_dir, const std::string& wal_dir, const RestoreOptions& restore_options = RestoreOptions()) = 0; @@ -213,70 +221,37 @@ class BackupEngineReadOnly { virtual Status VerifyBackup(BackupID backup_id) = 0; }; -// Please see the documentation in BackupableDB and RestoreBackupableDB +// A backup engine for creating new backups. class BackupEngine { public: virtual ~BackupEngine() {} + // BackupableDBOptions have to be the same as the ones used in previous + // BackupEngines for the same backup directory. static Status Open(Env* db_env, const BackupableDBOptions& options, BackupEngine** backup_engine_ptr); - /// same as CreateNewBackup, but stores extra application metadata + // same as CreateNewBackup, but stores extra application metadata virtual Status CreateNewBackupWithMetadata( DB* db, const std::string& app_metadata, bool flush_before_backup = false, std::function progress_callback = []() {}) = 0; + // Captures the state of the database in the latest backup + // NOT a thread safe call virtual Status CreateNewBackup(DB* db, bool flush_before_backup = false, std::function progress_callback = []() {}) { return CreateNewBackupWithMetadata(db, "", flush_before_backup, progress_callback); } - virtual Status PurgeOldBackups(uint32_t num_backups_to_keep) = 0; - virtual Status DeleteBackup(BackupID backup_id) = 0; - virtual void StopBackup() = 0; - - virtual void GetBackupInfo(std::vector* backup_info) = 0; - virtual void GetCorruptedBackups( - std::vector* corrupt_backup_ids) = 0; - virtual Status RestoreDBFromBackup( - BackupID backup_id, const std::string& db_dir, const std::string& wal_dir, - const RestoreOptions& restore_options = RestoreOptions()) = 0; - virtual Status RestoreDBFromLatestBackup( - const std::string& db_dir, const std::string& wal_dir, - const RestoreOptions& restore_options = RestoreOptions()) = 0; - // checks that each file exists and that the size of the file matches our - // expectations. it does not check file checksum. - // Returns Status::OK() if all checks are good - virtual Status VerifyBackup(BackupID backup_id) = 0; - - virtual Status GarbageCollect() = 0; -}; - -// Stack your DB with BackupableDB to be able to backup the DB -class BackupableDB : public StackableDB { - public: - // BackupableDBOptions have to be the same as the ones used in a previous - // incarnation of the DB - // - // BackupableDB ownes the pointer `DB* db` now. You should not delete it or - // use it after the invocation of BackupableDB - BackupableDB(DB* db, const BackupableDBOptions& options); - virtual ~BackupableDB(); - - // Captures the state of the database in the latest backup - // NOT a thread safe call - Status CreateNewBackup(bool flush_before_backup = false); - // Returns info about backups in backup_info - void GetBackupInfo(std::vector* backup_info); - // Returns info about corrupt backups in corrupt_backups - void GetCorruptedBackups(std::vector* corrupt_backup_ids); // deletes old backups, keeping latest num_backups_to_keep alive - Status PurgeOldBackups(uint32_t num_backups_to_keep); + virtual Status PurgeOldBackups(uint32_t num_backups_to_keep) = 0; + // deletes a specific backup - Status DeleteBackup(BackupID backup_id); + virtual Status DeleteBackup(BackupID backup_id) = 0; + // Call this from another thread if you want to stop the backup // that is currently happening. It will return immediatelly, will // not wait for the backup to stop. @@ -284,62 +259,44 @@ class BackupableDB : public StackableDB { // return Status::Incomplete(). It will not clean up after itself, but // the state will remain consistent. The state will be cleaned up // next time you create BackupableDB or RestoreBackupableDB. - void StopBackup(); - - // 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. - Status GarbageCollect(); - - private: - BackupEngine* backup_engine_; - Status status_; -}; - -// Use this class to access information about backups and restore from them -class RestoreBackupableDB { - public: - RestoreBackupableDB(Env* db_env, const BackupableDBOptions& options); - ~RestoreBackupableDB(); + virtual void StopBackup() = 0; // Returns info about backups in backup_info - void GetBackupInfo(std::vector* backup_info); + virtual void GetBackupInfo(std::vector* backup_info) = 0; + // Returns info about corrupt backups in corrupt_backups - void GetCorruptedBackups(std::vector* corrupt_backup_ids); + virtual void GetCorruptedBackups( + std::vector* corrupt_backup_ids) = 0; // restore from backup with backup_id - // IMPORTANT -- if options_.share_table_files == true and you restore DB - // from some backup that is not the latest, and you start creating new - // backups from the new DB, they will probably fail + // IMPORTANT -- if options_.share_table_files == true, + // options_.share_files_with_checksum == false, you restore 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. - Status RestoreDBFromBackup(BackupID backup_id, const std::string& db_dir, - const std::string& wal_dir, - const RestoreOptions& restore_options = - RestoreOptions()); + virtual Status RestoreDBFromBackup( + BackupID backup_id, const std::string& db_dir, const std::string& wal_dir, + const RestoreOptions& restore_options = RestoreOptions()) = 0; // restore from the latest backup - Status RestoreDBFromLatestBackup(const std::string& db_dir, - const std::string& wal_dir, - const RestoreOptions& restore_options = - RestoreOptions()); - // deletes old backups, keeping latest num_backups_to_keep alive - Status PurgeOldBackups(uint32_t num_backups_to_keep); - // deletes a specific backup - Status DeleteBackup(BackupID backup_id); + virtual Status RestoreDBFromLatestBackup( + const std::string& db_dir, const std::string& wal_dir, + const RestoreOptions& restore_options = RestoreOptions()) = 0; + + // checks that each file exists and that the size of the file matches our + // expectations. it does not check file checksum. + // Returns Status::OK() if all checks are good + virtual Status VerifyBackup(BackupID backup_id) = 0; // 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. - Status GarbageCollect(); - - private: - BackupEngine* backup_engine_; - Status status_; + virtual Status GarbageCollect() = 0; }; } // namespace rocksdb diff --git a/utilities/backupable/backupable_db.cc b/utilities/backupable/backupable_db.cc index 36d033d9f..3b98b2786 100644 --- a/utilities/backupable/backupable_db.cc +++ b/utilities/backupable/backupable_db.cc @@ -1804,136 +1804,6 @@ Status BackupEngineReadOnly::Open(Env* env, const BackupableDBOptions& options, return Status::OK(); } -// --- BackupableDB methods -------- - -BackupableDB::BackupableDB(DB* db, const BackupableDBOptions& options) - : StackableDB(db) { - auto backup_engine_impl = new BackupEngineImpl(db->GetEnv(), options); - status_ = backup_engine_impl->Initialize(); - backup_engine_ = backup_engine_impl; -} - -BackupableDB::~BackupableDB() { - delete backup_engine_; -} - -Status BackupableDB::CreateNewBackup(bool flush_before_backup) { - if (!status_.ok()) { - return status_; - } - return backup_engine_->CreateNewBackup(this, flush_before_backup); -} - -void BackupableDB::GetBackupInfo(std::vector* backup_info) { - if (!status_.ok()) { - return; - } - backup_engine_->GetBackupInfo(backup_info); -} - -void -BackupableDB::GetCorruptedBackups(std::vector* corrupt_backup_ids) { - if (!status_.ok()) { - return; - } - backup_engine_->GetCorruptedBackups(corrupt_backup_ids); -} - -Status BackupableDB::PurgeOldBackups(uint32_t num_backups_to_keep) { - if (!status_.ok()) { - return status_; - } - return backup_engine_->PurgeOldBackups(num_backups_to_keep); -} - -Status BackupableDB::DeleteBackup(BackupID backup_id) { - if (!status_.ok()) { - return status_; - } - return backup_engine_->DeleteBackup(backup_id); -} - -void BackupableDB::StopBackup() { - backup_engine_->StopBackup(); -} - -Status BackupableDB::GarbageCollect() { - if (!status_.ok()) { - return status_; - } - return backup_engine_->GarbageCollect(); -} - -// --- RestoreBackupableDB methods ------ - -RestoreBackupableDB::RestoreBackupableDB(Env* db_env, - const BackupableDBOptions& options) { - auto backup_engine_impl = new BackupEngineImpl(db_env, options); - status_ = backup_engine_impl->Initialize(); - backup_engine_ = backup_engine_impl; -} - -RestoreBackupableDB::~RestoreBackupableDB() { - delete backup_engine_; -} - -void -RestoreBackupableDB::GetBackupInfo(std::vector* backup_info) { - if (!status_.ok()) { - return; - } - backup_engine_->GetBackupInfo(backup_info); -} - -void RestoreBackupableDB::GetCorruptedBackups( - std::vector* corrupt_backup_ids) { - if (!status_.ok()) { - return; - } - backup_engine_->GetCorruptedBackups(corrupt_backup_ids); -} - -Status RestoreBackupableDB::RestoreDBFromBackup( - BackupID backup_id, const std::string& db_dir, const std::string& wal_dir, - const RestoreOptions& restore_options) { - if (!status_.ok()) { - return status_; - } - return backup_engine_->RestoreDBFromBackup(backup_id, db_dir, wal_dir, - restore_options); -} - -Status RestoreBackupableDB::RestoreDBFromLatestBackup( - const std::string& db_dir, const std::string& wal_dir, - const RestoreOptions& restore_options) { - if (!status_.ok()) { - return status_; - } - return backup_engine_->RestoreDBFromLatestBackup(db_dir, wal_dir, - restore_options); -} - -Status RestoreBackupableDB::PurgeOldBackups(uint32_t num_backups_to_keep) { - if (!status_.ok()) { - return status_; - } - return backup_engine_->PurgeOldBackups(num_backups_to_keep); -} - -Status RestoreBackupableDB::DeleteBackup(BackupID backup_id) { - if (!status_.ok()) { - return status_; - } - return backup_engine_->DeleteBackup(backup_id); -} - -Status RestoreBackupableDB::GarbageCollect() { - if (!status_.ok()) { - return status_; - } - return backup_engine_->GarbageCollect(); -} - } // namespace rocksdb #endif // ROCKSDB_LITE