RocksDB supports shared access to a database directory in a primary-secondary mode. The primary instance is a regular RocksDB instance capable of read, write, flush and compaction. (Or just compaction since flush can be viewed as a special type of compaction of L0 files). The secondary instance is similar to read-only instance, since it supports read but not write, flush or compaction. However, the secondary instance is able to dynamically tail the MANIFEST and write-ahead-logs (WALs) of the primary and apply the related changes if applicable. User has to call DB::TryCatchUpWithPrimary() explicitly at chosen times.

    Example usage

    1. const std::string kDbPath = "/tmp/rocksdbtest";
    2. ...
    3. // Assume we have already opened a regular RocksDB instance db_primary
    4. // whose database directory is kDbPath.
    5. assert(db_primary);
    6. Options options;
    7. options.max_open_files = -1;
    8. // Secondary instance needs its own directory to store info logs (LOG)
    9. const std::string kSecondaryPath = "/tmp/rocksdb_secondary/";
    10. DB* db_secondary = nullptr;
    11. Status s = DB::OpenAsSecondary(options, kDbPath, kSecondaryPath, &db_secondary);
    12. assert(!s.ok() || db_secondary);
    13. // Let secondary **try** to catch up with primary
    14. s = db_secondary->TryCatchUpWithPrimary();
    15. assert(s.ok());
    16. // Read operations
    17. std::string value;
    18. s = db_secondary->Get(ReadOptions(), "foo", &value);
    19. ...

    More detailed example can be found in examples/

    Current Limitations and Caveats

    • The secondary instance must be opened with max_open_files = -1, indicating the secondary has to keep all file descriptors open in order to prevent them from becoming inaccessible after the primary unlinks them, which does not work on some non-POSIX file systems. We have a plan to relax this limitation in the future.
    • RocksDB relies heavily on compaction to improve read performance. If a secondary instance tails and applies the log files of the primary right before a compaction, then it is possible to observe worse read performance on the secondary instance than on the primary until the secondary tails the logs again and advances to the state after compaction.