1 // Copyright (c) 2011-present, Facebook, Inc. All rights reserved. 2 // This source code is licensed under both the GPLv2 (found in the 3 // COPYING file in the root directory) and Apache 2.0 License 4 // (found in the LICENSE.Apache file in the root directory). 5 6 // This file contains utility functions for RocksDB Options. 7 #pragma once 8 9 #ifndef ROCKSDB_LITE 10 11 #include <string> 12 #include <vector> 13 14 #include "rocksdb/db.h" 15 #include "rocksdb/env.h" 16 #include "rocksdb/options.h" 17 #include "rocksdb/status.h" 18 19 namespace ROCKSDB_NAMESPACE { 20 // Constructs the DBOptions and ColumnFamilyDescriptors by loading the 21 // latest RocksDB options file stored in the specified rocksdb database. 22 // 23 // Note that the all the pointer options (except table_factory, which will 24 // be described in more details below) will be initialized with the default 25 // values. Developers can further initialize them after this function call. 26 // Below is an example list of pointer options which will be initialized 27 // 28 // * env 29 // * memtable_factory 30 // * compaction_filter_factory 31 // * prefix_extractor 32 // * comparator 33 // * merge_operator 34 // * compaction_filter 35 // 36 // User can also choose to load customized comparator, env, and/or 37 // merge_operator through object registry: 38 // * comparator needs to be registered through Registrar<const Comparator> 39 // * env needs to be registered through Registrar<Env> 40 // * merge operator needs to be registered through 41 // Registrar<std::shared_ptr<MergeOperator>>. 42 // 43 // For table_factory, this function further supports deserializing 44 // BlockBasedTableFactory and its BlockBasedTableOptions except the 45 // pointer options of BlockBasedTableOptions (flush_block_policy_factory, 46 // block_cache, and block_cache_compressed), which will be initialized with 47 // default values. Developers can further specify these three options by 48 // casting the return value of TableFactoroy::GetOptions() to 49 // BlockBasedTableOptions and making necessary changes. 50 // 51 // ignore_unknown_options can be set to true if you want to ignore options 52 // that are from a newer version of the db, esentially for forward 53 // compatibility. 54 // 55 // examples/options_file_example.cc demonstrates how to use this function 56 // to open a RocksDB instance. 57 // 58 // @return the function returns an OK status when it went successfully. If 59 // the specified "dbpath" does not contain any option file, then a 60 // Status::NotFound will be returned. A return value other than 61 // Status::OK or Status::NotFound indicates there're some error related 62 // to the options file itself. 63 // 64 // @see LoadOptionsFromFile 65 Status LoadLatestOptions(const std::string& dbpath, Env* env, 66 DBOptions* db_options, 67 std::vector<ColumnFamilyDescriptor>* cf_descs, 68 bool ignore_unknown_options = false, 69 std::shared_ptr<Cache>* cache = {}); 70 71 // Similar to LoadLatestOptions, this function constructs the DBOptions 72 // and ColumnFamilyDescriptors based on the specified RocksDB Options file. 73 // 74 // @see LoadLatestOptions 75 Status LoadOptionsFromFile(const std::string& options_file_name, Env* env, 76 DBOptions* db_options, 77 std::vector<ColumnFamilyDescriptor>* cf_descs, 78 bool ignore_unknown_options = false, 79 std::shared_ptr<Cache>* cache = {}); 80 81 // Returns the latest options file name under the specified db path. 82 Status GetLatestOptionsFileName(const std::string& dbpath, Env* env, 83 std::string* options_file_name); 84 85 // Returns Status::OK if the input DBOptions and ColumnFamilyDescriptors 86 // are compatible with the latest options stored in the specified DB path. 87 // 88 // If the return status is non-ok, it means the specified RocksDB instance 89 // might not be correctly opened with the input set of options. Currently, 90 // changing one of the following options will fail the compatibility check: 91 // 92 // * comparator 93 // * prefix_extractor 94 // * table_factory 95 // * merge_operator 96 Status CheckOptionsCompatibility( 97 const std::string& dbpath, Env* env, const DBOptions& db_options, 98 const std::vector<ColumnFamilyDescriptor>& cf_descs, 99 bool ignore_unknown_options = false); 100 101 } // namespace ROCKSDB_NAMESPACE 102 #endif // !ROCKSDB_LITE 103