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

include/rocksdb/options.h

@@ -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;
 

include/rocksdb/utilities/backupable_db.h

@@ -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 =
                                      []() {}) {

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

@@ -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.

java/src/main/java/org/rocksdb/RocksIteratorInterface.java

@@ -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

java/src/main/java/org/rocksdb/WriteOptions.java

@@ -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.
    */