Document the interaction between disableWAL and BackupEngine (#5071)

Summary:
BackupEngine relies on write-ahead logs to back up the memtable. Disabling write-ahead logs
can result in backups failing to preserve unflushed keys. This PR updates the documentation to specify this behavior, and suggest always flushing the memtable when write-ahead logs are disabled.
Pull Request resolved: https://github.com/facebook/rocksdb/pull/5071

Differential Revision: D14524124

Pulled By: miasantreble

fbshipit-source-id: 635f855f8a42ad60273b5efd226139b511e3e5d5
main
Andrew Audibert 6 years ago committed by Facebook Github Bot
parent 36c2a7cfb1
commit e50326f327
  1. 5
      include/rocksdb/options.h
  2. 4
      include/rocksdb/utilities/backupable_db.h
  3. 10
      java/src/main/java/org/rocksdb/BackupEngine.java
  4. 2
      java/src/main/java/org/rocksdb/RocksIteratorInterface.java
  5. 10
      java/src/main/java/org/rocksdb/WriteOptions.java

@ -1213,7 +1213,10 @@ struct WriteOptions {
bool sync;
// If true, writes will not first go to the write ahead log,
// and the write may got lost after a crash.
// and the write may get lost after a crash. The backup engine
// relies on write-ahead logs to back up the memtable, so if
// you disable write-ahead logs, you must create backups with
// flush_before_backup=true to avoid losing unflushed memtable data.
// Default: false
bool disableWAL;

@ -263,6 +263,8 @@ class BackupEngine {
// same as CreateNewBackup, but stores extra application metadata
// Flush will always trigger if 2PC is enabled.
// If write-ahead logs are disabled, set flush_before_backup=true to
// avoid losing unflushed key/value pairs from the memtable.
virtual Status CreateNewBackupWithMetadata(
DB* db, const std::string& app_metadata, bool flush_before_backup = false,
std::function<void()> progress_callback = []() {}) = 0;
@ -270,6 +272,8 @@ class BackupEngine {
// Captures the state of the database in the latest backup
// NOT a thread safe call
// Flush will always trigger if 2PC is enabled.
// If write-ahead logs are disabled, set flush_before_backup=true to
// avoid losing unflushed key/value pairs from the memtable.
virtual Status CreateNewBackup(DB* db, bool flush_before_backup = false,
std::function<void()> progress_callback =
[]() {}) {

@ -65,7 +65,10 @@ public class BackupEngine extends RocksObject implements AutoCloseable {
* 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. The backup will
* 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.
@ -95,7 +98,10 @@ public class BackupEngine extends RocksObject implements AutoCloseable {
* 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. The backup will
* 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.

@ -41,7 +41,7 @@ public interface RocksIteratorInterface {
void seekToLast();
/**
* <p>Position at the first entry in the source whose key is that or
* <p>Position at the first entry in the source whose key is at or
* past target.</p>
*
* <p>The iterator is valid after this call if the source contains

@ -90,7 +90,10 @@ public class WriteOptions extends RocksObject {
/**
* If true, writes will not first go to the write ahead log,
* and the write may got lost after a crash.
* and the write may got lost after a crash. The backup engine
* relies on write-ahead logs to back up the memtable, so if
* you disable write-ahead logs, you must create backups with
* flush_before_backup=true to avoid losing unflushed memtable data.
*
* @param flag a boolean flag to specify whether to disable
* write-ahead-log on writes.
@ -103,7 +106,10 @@ public class WriteOptions extends RocksObject {
/**
* If true, writes will not first go to the write ahead log,
* and the write may got lost after a crash.
* and the write may got lost after a crash. The backup engine
* relies on write-ahead logs to back up the memtable, so if
* you disable write-ahead logs, you must create backups with
* flush_before_backup=true to avoid losing unflushed memtable data.
*
* @return boolean value indicating if WAL is disabled.
*/

Loading…
Cancel
Save