@nxtedition/rocksdb 13.5.8 → 13.5.9

package/deps/rocksdb/rocksdb/include/rocksdb/perf_context.h

@@ -20,6 +20,12 @@ namespace ROCKSDB_NAMESPACE {
  * add/remove fields to this structure, builds would fail. The way to fix the
  * builds would be to add the appropriate fields to the
  * DEF_PERF_CONTEXT_LEVEL_METRICS() macro in the perf_context.cc file.
+ *
+ * If you plan to add new metrics, please read documentation in perf_level.h and
+ * try to come up with a metric name that follows the naming conventions
+ * mentioned there. It helps to indicate the metric's starting enabling P
+ * erfLevel. Document this starting PerfLevel if the metric name cannot meet the
+ * naming conventions.
  */
 
 // Break down performance counters by level and store per-level perf context in
@@ -189,6 +195,7 @@ struct PerfContextBase {
   // total nanos spent on writing to WAL
   uint64_t write_wal_time;
   // total nanos spent on writing to mem tables
+  // This metric gets collected starting from PerfLevel::kEnableWait
   uint64_t write_memtable_time;
   // total nanos spent on delaying or throttling write
   uint64_t write_delay_time;
@@ -230,6 +237,8 @@ struct PerfContextBase {
   uint64_t bloom_sst_miss_count;
 
   // Time spent waiting on key locks in transaction lock manager.
+  // This metric gets collected starting from
+  // PerfLevel::kEnableTimeExceptForMutex
   uint64_t key_lock_wait_time;
   // number of times acquiring a lock was blocked by another transaction.
   uint64_t key_lock_wait_count;
@@ -275,6 +284,12 @@ struct PerfContextBase {
   uint64_t decrypt_data_nanos;
 
   uint64_t number_async_seek;
+
+  // Metrics for file ingestion
+  // Time spent end to end in an IngestExternalFile call.
+  uint64_t file_ingestion_nanos;
+  // Time IngestExternalFile blocked live writes.
+  uint64_t file_ingestion_blocking_live_writes_nanos;
 };
 
 struct PerfContext : public PerfContextBase {

package/deps/rocksdb/rocksdb/include/rocksdb/perf_level.h

@@ -14,19 +14,39 @@
 namespace ROCKSDB_NAMESPACE {
 
 // How much perf stats to collect. Affects perf_context and iostats_context.
+// These levels are incremental, which means a new set of metrics will get
+// collected when PerfLevel is upgraded from level n to level n + 1.
+// Each level's documentation specifies the incremental set of metrics it
+// enables. As an example, kEnableWait will also enable collecting all the
+// metrics that kEnableCount enables, and its documentation only specifies which
+// extra metrics it also enables.
+//
+// These metrics are identified with some naming conventions, but not all
+// metrics follow exactly this convention. The metrics' own documentation should
+// be source of truth if they diverge.
 enum PerfLevel : unsigned char {
-  kUninitialized = 0,             // unknown setting
-  kDisable = 1,                   // disable perf stats
-  kEnableCount = 2,               // enable only count stats
-  kEnableWait = 3,                // measure time spent by user threads
-                                  // blocked in RocksDB, and not external
-                                  // resources such as mutexes and IO
-  kEnableTimeExceptForMutex = 4,  // Other than count stats, also enable time
-                                  // stats except for mutexes
-  // Other than time, also measure CPU time counters. Still don't measure
-  // time (neither wall time nor CPU time) for mutexes.
+  // Unknown setting
+  kUninitialized = 0,
+  // Disable perf stats
+  kDisable = 1,
+  // Starts enabling count metrics. These metrics usually don't have time
+  // related keywords, and are likely to have keywords like "count" or "byte".
+  kEnableCount = 2,
+  // Starts enabling metrics that measure time spent by user threads blocked in
+  // RocksDB waiting for RocksDB to take actions, as opposed to waiting for
+  // external resources such as mutexes and IO.
+  // These metrics usually have this pattern: "_[wait|delay]_*_[time|nanos]".
+  kEnableWait = 3,
+  // Starts enabling metrics that measure the end to end time of an operation.
+  // These metrics' names have keywords "time" or "nanos". Check other time
+  // measuring metrics with similar but more specific naming conventions.
+  kEnableTimeExceptForMutex = 4,
+  // Starts enabling metrics that measure the cpu time of an operation. These
+  // metrics' name usually this pattern "_cpu_*_[time|nanos]".
   kEnableTimeAndCPUTimeExceptForMutex = 5,
-  kEnableTime = 6,  // enable count and time stats
+  // Starts enabling metrics that measure time for mutex. These metrics' name
+  // usually have this pattern: "_[mutex|condition]_*_[time|nanos]".
+  kEnableTime = 6,
   kOutOfBounds = 7  // N.B. Must always be the last value!
 };
 

package/deps/rocksdb/rocksdb/include/rocksdb/slice.h

@@ -20,6 +20,7 @@
 
 #include <cassert>
 #include <cstddef>
+#include <cstdint>
 #include <cstdio>
 #include <cstring>
 #include <string>
@@ -129,6 +130,46 @@ class Slice {
   // Intentionally copyable
 };
 
+// A likely more efficient alternative to std::optional<Slice>. For example,
+// an empty key might be distinct from "not specified" (and Slice* as an
+// optional is more troublesome to deal with).
+class OptSlice {
+ public:
+  OptSlice() : slice_(nullptr, SIZE_MAX) {}
+  /*implicit*/ OptSlice(const Slice& s) : slice_(s) {}
+  /*implicit*/ OptSlice(const std::string& s) : slice_(s) {}
+  /*implicit*/ OptSlice(const std::string_view& sv) : slice_(sv) {}
+  /*implicit*/ OptSlice(const char* c_str) : slice_(c_str) {}
+  // For easier migrating from APIs uing Slice* as an optional type.
+  // CAUTION: OptSlice{nullptr} is "no value" while Slice{nullptr} is "empty"
+  /*implicit*/ OptSlice(std::nullptr_t) : OptSlice() {}
+
+  bool has_value() const noexcept { return slice_.size() != SIZE_MAX; }
+  explicit operator bool() const noexcept { return has_value(); }
+
+  const Slice& value() const noexcept {
+    assert(has_value());
+    return slice_;
+  }
+  const Slice& operator*() const noexcept { return value(); }
+  const Slice* operator->() const noexcept { return &value(); }
+
+  const Slice* AsPtr() const noexcept {
+    return has_value() ? &slice_ : nullptr;
+  }
+  // Populate from an optional pointer. This is a very explicit conversion
+  // to minimize risk of bugs as in
+  //   Slice start, limit;
+  //   RangeOpt rng = {&start, &limit};
+  //   start = ...;  // BUG: would not affect rng
+  static OptSlice CopyFromPtr(const Slice* ptr) {
+    return ptr ? OptSlice{*ptr} : OptSlice{};
+  }
+
+ protected:
+  Slice slice_;
+};
+
 /**
  * A Slice that can be pinned with some cleanup tasks, which will be run upon
  * ::Reset() or object destruction, whichever is invoked first. This can be used

package/deps/rocksdb/rocksdb/include/rocksdb/slice_transform.h

@@ -34,7 +34,7 @@ struct ConfigOptions;
 // including data loss, unreported corruption, deadlocks, and more.
 class SliceTransform : public Customizable {
  public:
-  virtual ~SliceTransform(){}
+  virtual ~SliceTransform() {}
 
   // Return the name of this transformation.
   const char* Name() const override = 0;

package/deps/rocksdb/rocksdb/include/rocksdb/sst_dump_tool.h

@@ -14,4 +14,3 @@ class SSTDumpTool {
 };
 
 }  // namespace ROCKSDB_NAMESPACE
-

package/deps/rocksdb/rocksdb/include/rocksdb/sst_file_reader.h

@@ -5,7 +5,6 @@
 
 #pragma once
 
-
 #include "rocksdb/iterator.h"
 #include "rocksdb/options.h"
 #include "rocksdb/slice.h"
@@ -31,6 +30,11 @@ class SstFileReader {
   // If "snapshot" is nullptr, the iterator returns only the latest keys.
   Iterator* NewIterator(const ReadOptions& options);
 
+  // MultiGet to fetch a set of keys from the SST
+  std::vector<Status> MultiGet(const ReadOptions& options,
+                               const std::vector<Slice>& keys,
+                               std::vector<std::string>* values);
+
   // Returns a new iterator over the table contents as a raw table iterator,
   // a.k.a a `TableIterator`that iterates all point data entries in the table
   // including logically invisible entries like delete entries.

package/deps/rocksdb/rocksdb/include/rocksdb/sst_file_writer.h

@@ -5,7 +5,6 @@
 
 #pragma once
 
-
 #include <memory>
 #include <string>
 

package/deps/rocksdb/rocksdb/include/rocksdb/statistics.h

@@ -516,14 +516,16 @@ enum Tickers : uint32_t {
   // Number of FIFO compactions that drop files based on different reasons
   FIFO_MAX_SIZE_COMPACTIONS,
   FIFO_TTL_COMPACTIONS,
+  FIFO_CHANGE_TEMPERATURE_COMPACTIONS,
 
   // Number of bytes prefetched during user initiated scan
   PREFETCH_BYTES,
 
-  // Number of prefetched bytes that were actually useful
+  // Number of prefetched bytes that were actually useful during user initiated
+  // scan
   PREFETCH_BYTES_USEFUL,
 
-  // Number of FS reads avoided due to scan prefetching
+  // Number of FS reads avoided due to prefetching during user initiated scan
   PREFETCH_HITS,
 
   // Footer corruption detected when opening an SST file for reading
@@ -534,6 +536,12 @@ enum Tickers : uint32_t {
   FILE_READ_CORRUPTION_RETRY_COUNT,
   FILE_READ_CORRUPTION_RETRY_SUCCESS_COUNT,
 
+  // Counter for the number of times a WBWI is ingested into the DB. This
+  // happens when IngestWriteBatchWithIndex() is used and when large
+  // transaction optimization is enabled through
+  // TransactionOptions::large_txn_commit_optimize_threshold.
+  NUMBER_WBWI_INGEST,
+
   TICKER_ENUM_MAX
 };
 
@@ -657,16 +665,23 @@ enum Histograms : uint32_t {
   ASYNC_READ_BYTES,
   POLL_WAIT_MICROS,
 
+  // Number of bytes for RocksDB's prefetching (as opposed to file
+  // system's prefetch) on SST file during compaction read
+  COMPACTION_PREFETCH_BYTES,
+
   // Number of prefetched bytes discarded by RocksDB.
   PREFETCHED_BYTES_DISCARDED,
 
   // Wait time for aborting async read in FilePrefetchBuffer destructor
   ASYNC_PREFETCH_ABORT_MICROS,
 
-  // Number of bytes read for RocksDB's prefetching contents (as opposed to file
+  // Number of bytes for RocksDB's prefetching contents (as opposed to file
   // system's prefetch) from the end of SST table during block based table open
   TABLE_OPEN_PREFETCH_TAIL_READ_BYTES,
 
+  // Number of operations per transaction.
+  NUM_OP_PER_TRANSACTION,
+
   HISTOGRAM_ENUM_MAX
 };
 

package/deps/rocksdb/rocksdb/include/rocksdb/status.h

@@ -316,6 +316,8 @@ class Status {
     return Status(kInvalidArgument, kTxnNotPrepared, msg, msg2);
   }
 
+  static Status LockLimit() { return Status(kAborted, kLockLimit); }
+
   // Returns true iff the status indicates success.
   bool ok() const {
     MarkChecked();

package/deps/rocksdb/rocksdb/include/rocksdb/table.h

@@ -126,7 +126,15 @@ struct CacheUsageOptions {
 };
 
 // Configures how SST files using the block-based table format (standard)
-// are written and read.
+// are written and read. With few exceptions, each option only affects either
+// (a) how new SST files are written, or (b) how SST files are read. If an
+// option seems to affect how the SST file is constructed, e.g. format_version,
+// that option *ONLY* has an effect at construction time. Contrast this with
+// options like the various `cache` and `pin` options, that only affect
+// in-memory and IO behavior at read time. In general, any version of RocksDB
+// able to read the full key-value and indexing data in the SST file will read
+// it as written regardless of current options for writing new files. See
+// filter_policy regarding filters.
 //
 // Except as specifically noted, all options here are "mutable" using
 // SetOptions(), with the caveat that only new table builders and new table
@@ -480,6 +488,10 @@ struct BlockBasedTableOptions {
   // If non-nullptr, use the specified filter policy to reduce disk reads.
   // Many applications will benefit from passing the result of
   // NewBloomFilterPolicy() here.
+  //
+  // Because filters only impact performance and are not data-critical, an
+  // SST file can be opened and used without filters if (a) the filter
+  // policy name or schema is unrecognized, or (b) filter_policy is nullptr.
   std::shared_ptr<const FilterPolicy> filter_policy = nullptr;
 
   // If true, place whole keys in the filter (not just prefixes).
@@ -524,13 +536,9 @@ struct BlockBasedTableOptions {
   // Default: 0 (disabled)
   uint32_t read_amp_bytes_per_bit = 0;
 
-  // We currently have these versions:
-  // 0 -- This version can be read by really old RocksDB's. Doesn't support
-  // changing checksum type (default is CRC32).
-  // 1 -- Can be read by RocksDB's versions since 3.0. Supports non-default
-  // checksum, like xxHash. It is written by RocksDB when
-  // BlockBasedTableOptions::checksum is something other than kCRC32c. (version
-  // 0 is silently upconverted)
+  // We currently have these format versions:
+  // 0 - 1 -- Unsupported for writing new files and quietly sanitized to 2.
+  // Read support is deprecated and could be removed in the future.
   // 2 -- Can be read by RocksDB's versions since 3.10. Changes the way we
   // encode compressed blocks with LZ4, BZip2 and Zlib compression. If you
   // don't plan to run RocksDB before version 3.10, you should probably use
@@ -553,6 +561,10 @@ struct BlockBasedTableOptions {
   // misplaced within or between files is as likely to fail checksum
   // verification as random corruption. Also checksum-protects SST footer.
   // Can be read by RocksDB versions >= 8.6.0.
+  // 7 -- Support for custom compression algorithms with a CompressionManager
+  // using a non-built-in CompatibilityName(). See `compression_manager` in
+  // ColumnFamilyOptions. Also changes the format of TableProperties field
+  // `compression_name`. Can be read by RocksDB versions >= 10.4.0.
   //
   // Using the default setting of format_version is strongly recommended, so
   // that available enhancements are adopted eventually and automatically. The

package/deps/rocksdb/rocksdb/include/rocksdb/table_properties.h

@@ -109,6 +109,10 @@ class TablePropertiesCollector {
   // table.
   // @params key    the user key that is inserted into the table.
   // @params value  the value that is inserted into the table.
+  // @params file_size the current file size. For BlockBasedTable, this
+  //         includes all the data blocks written so far, upto but not including
+  //         the current block being built. With parallel compression, data
+  //         blocks are written async so it depends on the compression progress.
   virtual Status AddUserKey(const Slice& key, const Slice& value,
                             EntryType /*type*/, SequenceNumber /*seq*/,
                             uint64_t /*file_size*/) {
@@ -143,7 +147,7 @@ class TablePropertiesCollector {
   // The name of the properties collector can be used for debugging purpose.
   virtual const char* Name() const = 0;
 
-  // EXPERIMENTAL Return whether the output file should be further compacted
+  // Return whether the output file should be further compacted
   virtual bool NeedCompact() const { return false; }
 
   // For internal use only.
@@ -344,7 +348,20 @@ struct TableProperties {
   // {collector_name[1]},{collector_name[2]},{collector_name[3]} ..
   std::string property_collectors_names;
 
-  // The compression algo used to compress the SST files.
+  // Identifies the compression algorithm or schema used in the file.
+  // Specifically:
+  // * For format_version < 7, it is one of several names for built-in
+  // compression types. Because of how some previous versions of RocksDB
+  // behave, this must be set to "ZSTD" if any blocks are compressed
+  // with zstd and must NOT be set to "NoCompression" if any blocks are
+  // compressed.
+  // * For format_version >= 7, the format is
+  //   <compatibility_name>;<hex-coded compression types>;<future use>
+  // where <compatibility_name> is the CompatibilityName() of the
+  // CompressionManager used for the file, or empty if compression was
+  // disabled; <hex-coded compression types> represents a sorted set of
+  // CompressionType values used in the file other than kNoCompression, each
+  // as 2-digit hex, e.g. 04 for LZ$, 07 for ZSTD, etc.
   std::string compression_name;
 
   // Compression options used to compress the SST files.

package/deps/rocksdb/rocksdb/include/rocksdb/thread_status.h

@@ -64,7 +64,7 @@ struct ThreadStatus {
     OP_VERIFY_FILE_CHECKSUMS,
     OP_GETENTITY,
     OP_MULTIGETENTITY,
-    OP_READ_MANIFEST,
+    OP_GET_FILE_CHECKSUMS_FROM_CURRENT_MANIFEST,
     NUM_OP_TYPES
   };
 

package/deps/rocksdb/rocksdb/include/rocksdb/tool_hooks.h

@@ -0,0 +1,124 @@
+//  Copyright (c) Meta Platforms, Inc. and affiliates.  All rights reserved.
+//  This source code is licensed under both the GPLv2 (found in the
+//  COPYING file in the root directory) and Apache 2.0 License
+//  (found in the LICENSE.Apache file in the root directory).
+
+#pragma once
+
+#include "rocksdb/db.h"
+
+namespace ROCKSDB_NAMESPACE {
+
+struct TransactionDBOptions;
+class TransactionDB;
+class OptimisticTransactionDB;
+
+namespace blob_db {
+struct BlobDBOptions;
+class BlobDB;
+}  // namespace blob_db
+
+/*
+ * ToolHooks is currently a WORK IN PROGRESS, API is subject to change.
+ * ToolHooks is a class that allows users to override the default behavior of
+ * the various OpenDB calls used by db_bench_tool.  This allows users to easily
+ * extend the functionality of db_bench_tool to support their own open
+ * implementations.
+ */
+class ToolHooks {
+ public:
+  ToolHooks() = default;
+  virtual ~ToolHooks() = default;
+  virtual Status Open(const Options& db_options, const std::string& name,
+                      DB** dbptr) = 0;
+  virtual Status Open(
+      const DBOptions& db_options, const std::string& name,
+      const std::vector<ColumnFamilyDescriptor>& column_families,
+      std::vector<ColumnFamilyHandle*>* handles, DB** dbptr) = 0;
+  virtual Status OpenForReadOnly(const Options& options,
+                                 const std::string& name, DB** dbptr,
+                                 bool error_if_wal_file_exists) = 0;
+  virtual Status OpenForReadOnly(
+      const Options& options, const std::string& name,
+      const std::vector<ColumnFamilyDescriptor>& column_families,
+      std::vector<ColumnFamilyHandle*>* handles, DB** dbptr) = 0;
+  virtual Status OpenTransactionDB(const Options& db_options,
+                                   const TransactionDBOptions& txn_db_options,
+                                   const std::string& dbname,
+                                   TransactionDB** dbptr) = 0;
+  virtual Status OpenTransactionDB(
+      const DBOptions& db_options, const TransactionDBOptions& txn_db_options,
+      const std::string& dbname,
+      const std::vector<ColumnFamilyDescriptor>& column_families,
+      std::vector<ColumnFamilyHandle*>* handles, TransactionDB** dbptr) = 0;
+  virtual Status OpenOptimisticTransactionDB(
+      const Options& options, const std::string& dbname,
+      OptimisticTransactionDB** dbptr) = 0;
+  virtual Status OpenOptimisticTransactionDB(
+      const DBOptions& db_options, const std::string& dbname,
+      const std::vector<ColumnFamilyDescriptor>& column_families,
+      std::vector<ColumnFamilyHandle*>* handles,
+      OptimisticTransactionDB** dbptr) = 0;
+  virtual Status OpenAsSecondary(const Options& options,
+                                 const std::string& name,
+                                 const std::string& secondary_path,
+                                 DB** dbptr) = 0;
+  virtual Status OpenAsFollower(const Options& options, const std::string& name,
+                                const std::string& leader_path,
+                                std::unique_ptr<DB>* dbptr) = 0;
+  virtual Status Open(const Options& options,
+                      const blob_db::BlobDBOptions& bdb_options,
+                      const std::string& dbname, blob_db::BlobDB** blob_db) = 0;
+};
+
+class DefaultHooks : public ToolHooks {
+ public:
+  DefaultHooks() = default;
+  ~DefaultHooks() override = default;
+  virtual Status Open(const Options& db_options, const std::string& name,
+                      DB** dbptr) override;
+  virtual Status Open(
+      const DBOptions& db_options, const std::string& name,
+      const std::vector<ColumnFamilyDescriptor>& column_families,
+      std::vector<ColumnFamilyHandle*>* handles, DB** dbptr) override;
+  virtual Status OpenForReadOnly(const Options& options,
+                                 const std::string& name, DB** dbptr,
+                                 bool error_if_wal_file_exists) override;
+  virtual Status OpenForReadOnly(
+      const Options& options, const std::string& name,
+      const std::vector<ColumnFamilyDescriptor>& column_families,
+      std::vector<ColumnFamilyHandle*>* handles, DB** dbptr) override;
+  virtual Status OpenTransactionDB(const Options& db_options,
+                                   const TransactionDBOptions& txn_db_options,
+                                   const std::string& dbname,
+                                   TransactionDB** dbptr) override;
+  virtual Status OpenTransactionDB(
+      const DBOptions& db_options, const TransactionDBOptions& txn_db_options,
+      const std::string& dbname,
+      const std::vector<ColumnFamilyDescriptor>& column_families,
+      std::vector<ColumnFamilyHandle*>* handles,
+      TransactionDB** dbptr) override;
+  virtual Status OpenOptimisticTransactionDB(
+      const Options& options, const std::string& dbname,
+      OptimisticTransactionDB** dbptr) override;
+  virtual Status OpenOptimisticTransactionDB(
+      const DBOptions& db_options, const std::string& dbname,
+      const std::vector<ColumnFamilyDescriptor>& column_families,
+      std::vector<ColumnFamilyHandle*>* handles,
+      OptimisticTransactionDB** dbptr) override;
+  virtual Status OpenAsSecondary(const Options& options,
+                                 const std::string& name,
+                                 const std::string& secondary_path,
+                                 DB** dbptr) override;
+  virtual Status OpenAsFollower(const Options& options, const std::string& name,
+                                const std::string& leader_path,
+                                std::unique_ptr<DB>* dbptr) override;
+  virtual Status Open(const Options& options,
+                      const blob_db::BlobDBOptions& bdb_options,
+                      const std::string& dbname,
+                      blob_db::BlobDB** blob_db) override;
+};
+
+extern DefaultHooks defaultHooks;
+
+}  // namespace ROCKSDB_NAMESPACE

package/deps/rocksdb/rocksdb/include/rocksdb/trace_record.h

@@ -5,6 +5,7 @@
 
 #pragma once
 
+#include <cstdint>
 #include <memory>
 #include <string>
 #include <vector>

package/deps/rocksdb/rocksdb/include/rocksdb/universal_compaction.h

@@ -111,6 +111,26 @@ class CompactionOptionsUniversal {
   // Default: false
   bool incremental;
 
+  // EXPERIMENTAL
+  //
+  // If true, auto universal compaction picking will adjust to minimize locking
+  // of input files when bottom priority compactions are waiting to run. This
+  // can increase the likelihood of existing L0s being selected for compaction,
+  // thereby improving write stall and reducing read regression. It may increase
+  // the overrall write amplification and compaction load on low priority
+  // threads.
+  //
+  // Default: false (disabled)
+  //
+  // This options does not apply to manual compactions.
+  //
+  // This option is temporary in case turning on this feature causes problems
+  // and users need to undo it quickly. This option is planned for removal in
+  // the near future with default value set to true.
+  //
+  // Dynamically changeable through the SetOptions() API.
+  bool reduce_file_locking;
+
   // Default set of parameters
   CompactionOptionsUniversal()
       : size_ratio(1),
@@ -121,7 +141,12 @@ class CompactionOptionsUniversal {
         max_read_amp(-1),
         stop_style(kCompactionStopStyleTotalSize),
         allow_trivial_move(false),
-        incremental(false) {}
+        incremental(false),
+        reduce_file_locking(false) {}
+
+#if __cplusplus >= 202002L
+  bool operator==(const CompactionOptionsUniversal& rhs) const = default;
+#endif
 };
 
 }  // namespace ROCKSDB_NAMESPACE

package/deps/rocksdb/rocksdb/include/rocksdb/utilities/backup_engine.h

@@ -77,6 +77,15 @@ struct BackupEngineOptions {
   // Default: true
   bool backup_log_files;
 
+  // Size of the buffer in bytes used for reading files.
+  // Enables optimally configuring the IO size based on the storage backend.
+  // If specified, takes precendence over the rate limiter burst size (if
+  // specified) as well as kDefaultCopyFileBufferSize.
+  // If 0, the rate limiter burst size (if specified) or
+  // kDefaultCopyFileBufferSize will be used.
+  // Default: 0
+  uint64_t io_buffer_size;
+
   // Max bytes that can be transferred in a second during backup.
   // If 0, go as fast as you can
   // This limit only applies to writes. To also limit reads,
@@ -117,8 +126,8 @@ struct BackupEngineOptions {
   // Default: true
   bool share_files_with_checksum;
 
-  // Up to this many background threads will copy files for CreateNewBackup()
-  // and RestoreDBFromBackup()
+  // Up to this many background threads will be used to copy files & compute
+  // checksums for CreateNewBackup() and RestoreDBFromBackup().
   // Default: 1
   int max_background_operations;
 
@@ -228,8 +237,9 @@ struct BackupEngineOptions {
       const std::string& _backup_dir, Env* _backup_env = nullptr,
       bool _share_table_files = true, Logger* _info_log = nullptr,
       bool _sync = true, bool _destroy_old_data = false,
-      bool _backup_log_files = true, uint64_t _backup_rate_limit = 0,
-      uint64_t _restore_rate_limit = 0, int _max_background_operations = 1,
+      bool _backup_log_files = true, uint64_t _io_buffer_size = 0,
+      uint64_t _backup_rate_limit = 0, uint64_t _restore_rate_limit = 0,
+      int _max_background_operations = 1,
       uint64_t _callback_trigger_interval_size = 4 * 1024 * 1024,
       int _max_valid_backups_to_open = INT_MAX,
       ShareFilesNaming _share_files_with_checksum_naming =
@@ -241,6 +251,7 @@ struct BackupEngineOptions {
         sync(_sync),
         destroy_old_data(_destroy_old_data),
         backup_log_files(_backup_log_files),
+        io_buffer_size(_io_buffer_size),
         backup_rate_limit(_backup_rate_limit),
         restore_rate_limit(_restore_rate_limit),
         share_files_with_checksum(true),
@@ -338,6 +349,39 @@ struct CreateBackupOptions {
 };
 
 struct RestoreOptions {
+  // Enum reflecting tiered approach to restores.
+  //
+  // Options `kKeepLatestDbSessionIdFiles`, `kVerifyChecksum` introduce
+  // incremental restore capability and are intended to be used separately.
+  enum Mode : uint32_t {
+    // Most efficient way to restore a healthy / non-corrupted DB from
+    // the backup(s). This mode can almost always successfully recover from
+    // incomplete / missing files, as in an incomplete copy of a DB.
+    // This mode is also integrated with `exclude_files_callback` feature
+    // and will opportunistically try to find excluded files in existing db
+    // filesystem if missing in all supplied backup directories.
+    //
+    // Effective on data files following modern share files naming schemes.
+    kKeepLatestDbSessionIdFiles = 1U,
+
+    // Recommended when db is suspected to be unhealthy, ex. we want to retain
+    // most of the files (therefore saving on write I/O) with an exception of
+    // a few corrupted ones.
+    //
+    // When opted-in, restore engine will scan the db file, compute the
+    // checksum and compare it against the checksum hardened in the backup file
+    // metadata. If checksums match, existing file will be retained as-is.
+    // Otherwise, it will be deleted and replaced it with its' restored backup
+    // counterpart. If backup file doesn't have a checksum hardened in the
+    // metadata, we'll schedule an async task to compute it.
+    kVerifyChecksum = 2U,
+
+    // Zero trust. Least efficient.
+    //
+    // Purge all the destination files and restores all files from the backup.
+    kPurgeAllFiles = 0xffffU,
+  };
+
   // If true, restore won't overwrite the existing log files in wal_dir. It will
   // also move all log files from archive directory to wal_dir. Use this option
   // in combination with BackupEngineOptions::backup_log_files = false for
@@ -350,8 +394,13 @@ struct RestoreOptions {
   // directories known to contain the required files.
   std::forward_list<BackupEngineReadOnlyBase*> alternate_dirs;
 
-  explicit RestoreOptions(bool _keep_log_files = false)
-      : keep_log_files(_keep_log_files) {}
+  // Specifies the level of incremental restore. 'kPurgeAllFiles' by default.
+  Mode mode;
+
+  // FIXME(https://github.com/facebook/rocksdb/issues/13293)
+  explicit RestoreOptions(bool _keep_log_files = false,
+                          Mode _mode = Mode::kPurgeAllFiles)
+      : keep_log_files(_keep_log_files), mode(_mode) {}
 };
 
 using BackupID = uint32_t;