ceph/src/rocksdb/include/rocksdb/utilities/options_util.h

   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 {
  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 and/or merge_operator
  37 // through object registry:
  38 // * comparator needs to be registered through Registrar<const Comparator>
  39 // * merge operator needs to be registered through
  40 //     Registrar<std::shared_ptr<MergeOperator>>.
  41 //
  42 // For table_factory, this function further supports deserializing
  43 // BlockBasedTableFactory and its BlockBasedTableOptions except the
  44 // pointer options of BlockBasedTableOptions (flush_block_policy_factory,
  45 // block_cache, and block_cache_compressed), which will be initialized with
  46 // default values.  Developers can further specify these three options by
  47 // casting the return value of TableFactoroy::GetOptions() to
  48 // BlockBasedTableOptions and making necessary changes.
  49 //
  50 // ignore_unknown_options can be set to true if you want to ignore options
  51 // that are from a newer version of the db, esentially for forward
  52 // compatibility.
  53 //
  54 // examples/options_file_example.cc demonstrates how to use this function
  55 // to open a RocksDB instance.
  56 //
  57 // @return the function returns an OK status when it went successfully.  If
  58 //     the specified "dbpath" does not contain any option file, then a
  59 //     Status::NotFound will be returned.  A return value other than
  60 //     Status::OK or Status::NotFound indicates there're some error related
  61 //     to the options file itself.
  62 //
  63 // @see LoadOptionsFromFile
  64 Status LoadLatestOptions(const std::string& dbpath, Env* env,
  65                          DBOptions* db_options,
  66                          std::vector<ColumnFamilyDescriptor>* cf_descs,
  67                          bool ignore_unknown_options = false,
  68                          std::shared_ptr<Cache>* cache = {});
  69
  70 // Similar to LoadLatestOptions, this function constructs the DBOptions
  71 // and ColumnFamilyDescriptors based on the specified RocksDB Options file.
  72 //
  73 // @see LoadLatestOptions
  74 Status LoadOptionsFromFile(const std::string& options_file_name, Env* env,
  75                            DBOptions* db_options,
  76                            std::vector<ColumnFamilyDescriptor>* cf_descs,
  77                            bool ignore_unknown_options = false,
  78                            std::shared_ptr<Cache>* cache = {});
  79
  80 // Returns the latest options file name under the specified db path.
  81 Status GetLatestOptionsFileName(const std::string& dbpath, Env* env,
  82                                 std::string* options_file_name);
  83
  84 // Returns Status::OK if the input DBOptions and ColumnFamilyDescriptors
  85 // are compatible with the latest options stored in the specified DB path.
  86 //
  87 // If the return status is non-ok, it means the specified RocksDB instance
  88 // might not be correctly opened with the input set of options.  Currently,
  89 // changing one of the following options will fail the compatibility check:
  90 //
  91 // * comparator
  92 // * prefix_extractor
  93 // * table_factory
  94 // * merge_operator
  95 Status CheckOptionsCompatibility(
  96     const std::string& dbpath, Env* env, const DBOptions& db_options,
  97     const std::vector<ColumnFamilyDescriptor>& cf_descs,
  98     bool ignore_unknown_options = false);
  99
 100 }  // namespace rocksdb
 101 #endif  // !ROCKSDB_LITE