In RocksDB 4.3, we add a set of features that makes managing RocksDB options easier.

  • Each RocksDB database will now automatically persist its current set of options into a file on every successful call of DB::Open(), SetOptions(), and CreateColumnFamily() / DropColumnFamily().

  • LoadLatestOptions() / LoadOptionsFromFile(): A function that constructs RocksDB options object from an options file.

  • CheckOptionsCompatibility: A function that performs compatibility check on two sets of RocksDB options.

With the above options file support, developers no longer need to maintain the full set of options of a previously-created RocksDB instance. In addition, when changing options is needed, CheckOptionsCompatibility() can further make sure the resulting set of Options can successfully open the same RocksDB database without corrupting the underlying data.

Example

Here's a running example showing how the new features can make managing RocksDB options easier. A more complete example can be found in examples/options_file_example.cc.

Suppose we open a RocksDB database, create a new column family on-the-fly while the database is running, and then close the database:

  1. s = DB::Open(rocksdb_options, path_to_db, &db);
  2. ...
  3. // Create column family, and rocksdb will persist the options.
  4. ColumnFamilyHandle* cf;
  5. s = db->CreateColumnFamily(ColumnFamilyOptions(), "new_cf", &cf);
  6. ...
  7. // close DB
  8. delete cf;
  9. delete db;

Since in RocksDB 4.3 or later, each RocksDB instance will automatically store its latest set of options into a options file, we can use that file to construct the options next time when we want to open the DB. This is different from RocksDB 4.2 or older version where we need to remember all the options of each the column families in order to successfully open a DB. Now let's see how it works.

First, we call LoadLatestOptions() to load the latest set of options used by the target RocksDB database:

  1. DBOptions loaded_db_opt;
  2. std::vector<ColumnFamilyDescriptor> loaded_cf_descs;
  3. LoadLatestOptions(path_to_db, Env::Default(), &loaded_db_opt,
  4.                   &loaded_cf_descs);

Unsupported Options

Since C++ does not have reflection, the following user-defined functions and pointer-typed options will only be initialized with default values. Detailed information can be found in rocksdb/utilities/options_util.h:

  1. * env
  2. * memtable_factory
  3. * compaction_filter_factory
  4. * prefix_extractor
  5. * comparator
  6. * merge_operator
  7. * compaction_filter
  8. * cache in BlockBasedTableOptions
  9. * table_factory other than BlockBasedTableFactory

For those un-supported user-defined functions, developers will need to specify them manually. In this example, we initialize Cache in BlockBasedTableOptions and CompactionFilter:

  1. for (size_t i = 0; i < loaded_cf_descs.size(); ++i) {
  2.   auto* loaded_bbt_opt = reinterpret_cast<BlockBasedTableOptions*>(
  3.       loaded_cf_descs[0].options.table_factory->GetOptions());
  4.   loaded_bbt_opt->block_cache = cache;
  5. }
  7. loaded_cf_descs[0].options.compaction_filter = new MyCompactionFilter();

Now we perform sanity check to make sure the set of options is safe to open the target database:

  1. Status s = CheckOptionsCompatibility(
  2.     kDBPath, Env::Default(), db_options, loaded_cf_descs);

If the return value indicates OK status, we can proceed and use the loaded set of options to open the target RocksDB database:

  1. s = DB::Open(loaded_db_opt, kDBPath, loaded_cf_descs, &handles, &db);

Ignoring unknown options

In cases where an options file of a newer version is used with an older RocksDB version (say, when downgrading due to a bug), the older RocksDB version might not know about some newer options. ignore_unknown_options flag can be used to handle such cases. ignore_unknown_options has been added as an argument to LoadLatestOptions, LoadOptionsFromFile, CheckOptionsCompatibility, GetDBOptionsFromMap, GetColumnFamilyOptionsFromMap, GetBlockBasedTableOptionsFromMap and GetPlainTableOptionsFromMap. By default it is set to false.

RocksDB Options File Format

RocksDB options file is a text file that follows the INI file format. Each RocksDB options file has one version section, one DBOptions section, and one CFOptions and TableOptions section for each column family. Below is an example RocksDB options file. A complete example can be found in examples/rocksdb_option_file_example.ini:

  1. [Version]
  2.   rocksdb_version=4.3.0
  3.   options_file_version=1.1
  4. [DBOptions]
  5.   stats_dump_period_sec=600
  6.   max_manifest_file_size=18446744073709551615
  7.   bytes_per_sync=8388608
  8.   delayed_write_rate=2097152
  9.   WAL_ttl_seconds=0
  10.   ...
  11. [CFOptions "default"]
  12.   compaction_style=kCompactionStyleLevel
  13.   compaction_filter=nullptr
  14.   num_levels=6
  15.   table_factory=BlockBasedTable
  16.   comparator=leveldb.BytewiseComparator
  17.   compression_per_level=kNoCompression:kNoCompression:kNoCompression:kSnappyCompression:kSnappyCompression:kSnappyCompression
  18.   ...
  19. [TableOptions/BlockBasedTable "default"]
  20.   format_version=2
  21.   whole_key_filtering=true
  22.   skip_table_builder_flush=false
  23.   no_block_cache=false
  24.   checksum=kCRC32c
  25.   filter_policy=rocksdb.BuiltinBloomFilter
  26.   ....