1//===----------------------------------------------------------------------===//
2// DuckDB
3//
4// duckdb/main/config.hpp
5//
6//
7//===----------------------------------------------------------------------===//
8
9#pragma once
10
11#include "duckdb/common/enums/access_mode.hpp"
12#include "duckdb/common/allocator.hpp"
13#include "duckdb/common/case_insensitive_map.hpp"
14#include "duckdb/common/common.hpp"
15#include "duckdb/common/enums/compression_type.hpp"
16#include "duckdb/common/enums/optimizer_type.hpp"
17#include "duckdb/common/enums/order_type.hpp"
18#include "duckdb/common/enums/set_scope.hpp"
19#include "duckdb/common/enums/window_aggregation_mode.hpp"
20#include "duckdb/common/file_system.hpp"
21#include "duckdb/common/set.hpp"
22#include "duckdb/common/types/value.hpp"
23#include "duckdb/common/vector.hpp"
24#include "duckdb/common/winapi.hpp"
25#include "duckdb/storage/compression/bitpacking.hpp"
26#include "duckdb/function/cast/default_casts.hpp"
27#include "duckdb/function/replacement_scan.hpp"
28#include "duckdb/optimizer/optimizer_extension.hpp"
29#include "duckdb/parser/parser_extension.hpp"
30#include "duckdb/planner/operator_extension.hpp"
31#include "duckdb/common/arrow/arrow_options.hpp"
32
33namespace duckdb {
34class BufferPool;
35class CastFunctionSet;
36class ClientContext;
37class ErrorManager;
38class CompressionFunction;
39class TableFunctionRef;
40class OperatorExtension;
41class StorageExtension;
42
43struct CompressionFunctionSet;
44struct DBConfig;
45
46enum class CheckpointAbort : uint8_t {
47 NO_ABORT = 0,
48 DEBUG_ABORT_BEFORE_TRUNCATE = 1,
49 DEBUG_ABORT_BEFORE_HEADER = 2,
50 DEBUG_ABORT_AFTER_FREE_LIST_WRITE = 3
51};
52
53typedef void (*set_global_function_t)(DatabaseInstance *db, DBConfig &config, const Value &parameter);
54typedef void (*set_local_function_t)(ClientContext &context, const Value &parameter);
55typedef void (*reset_global_function_t)(DatabaseInstance *db, DBConfig &config);
56typedef void (*reset_local_function_t)(ClientContext &context);
57typedef Value (*get_setting_function_t)(ClientContext &context);
58
59struct ConfigurationOption {
60 const char *name;
61 const char *description;
62 LogicalTypeId parameter_type;
63 set_global_function_t set_global;
64 set_local_function_t set_local;
65 reset_global_function_t reset_global;
66 reset_local_function_t reset_local;
67 get_setting_function_t get_setting;
68};
69
70typedef void (*set_option_callback_t)(ClientContext &context, SetScope scope, Value &parameter);
71
72struct ExtensionOption {
73 ExtensionOption(string description_p, LogicalType type_p, set_option_callback_t set_function_p,
74 Value default_value_p)
75 : description(std::move(description_p)), type(std::move(type_p)), set_function(set_function_p),
76 default_value(std::move(default_value_p)) {
77 }
78
79 string description;
80 LogicalType type;
81 set_option_callback_t set_function;
82 Value default_value;
83};
84
85struct DBConfigOptions {
86 //! Database file path. May be empty for in-memory mode
87 string database_path;
88 //! Database type. If empty, automatically extracted from `database_path`, where a `type:path` syntax is expected
89 string database_type;
90 //! Access mode of the database (AUTOMATIC, READ_ONLY or READ_WRITE)
91 AccessMode access_mode = AccessMode::AUTOMATIC;
92 //! Checkpoint when WAL reaches this size (default: 16MB)
93 idx_t checkpoint_wal_size = 1 << 24;
94 //! Whether or not to use Direct IO, bypassing operating system buffers
95 bool use_direct_io = false;
96 //! Whether extensions should be loaded on start-up
97 bool load_extensions = true;
98 //! The maximum memory used by the database system (in bytes). Default: 80% of System available memory
99 idx_t maximum_memory = (idx_t)-1;
100 //! The maximum amount of CPU threads used by the database system. Default: all available.
101 idx_t maximum_threads = (idx_t)-1;
102 //! The number of external threads that work on DuckDB tasks. Default: none.
103 idx_t external_threads = 0;
104 //! Whether or not to create and use a temporary directory to store intermediates that do not fit in memory
105 bool use_temporary_directory = true;
106 //! Directory to store temporary structures that do not fit in memory
107 string temporary_directory;
108 //! The collation type of the database
109 string collation = string();
110 //! The order type used when none is specified (default: ASC)
111 OrderType default_order_type = OrderType::ASCENDING;
112 //! Null ordering used when none is specified (default: NULLS LAST)
113 DefaultOrderByNullType default_null_order = DefaultOrderByNullType::NULLS_LAST;
114 //! enable COPY and related commands
115 bool enable_external_access = true;
116 //! Whether or not object cache is used
117 bool object_cache_enable = false;
118 //! Whether or not the global http metadata cache is used
119 bool http_metadata_cache_enable = false;
120 //! Force checkpoint when CHECKPOINT is called or on shutdown, even if no changes have been made
121 bool force_checkpoint = false;
122 //! Run a checkpoint on successful shutdown and delete the WAL, to leave only a single database file behind
123 bool checkpoint_on_shutdown = true;
124 //! Debug flag that decides when a checkpoing should be aborted. Only used for testing purposes.
125 CheckpointAbort checkpoint_abort = CheckpointAbort::NO_ABORT;
126 //! Initialize the database with the standard set of DuckDB functions
127 //! You should probably not touch this unless you know what you are doing
128 bool initialize_default_database = true;
129 //! The set of disabled optimizers (default empty)
130 set<OptimizerType> disabled_optimizers;
131 //! Force a specific compression method to be used when checkpointing (if available)
132 CompressionType force_compression = CompressionType::COMPRESSION_AUTO;
133 //! Force a specific bitpacking mode to be used when using the bitpacking compression method
134 BitpackingMode force_bitpacking_mode = BitpackingMode::AUTO;
135 //! Debug setting for window aggregation mode: (window, combine, separate)
136 WindowAggregationMode window_mode = WindowAggregationMode::WINDOW;
137 //! Whether or not preserving insertion order should be preserved
138 bool preserve_insertion_order = true;
139 //! Whether Arrow Arrays use Large or Regular buffers
140 ArrowOffsetSize arrow_offset_size = ArrowOffsetSize::REGULAR;
141 //! Database configuration variables as controlled by SET
142 case_insensitive_map_t<Value> set_variables;
143 //! Database configuration variable default values;
144 case_insensitive_map_t<Value> set_variable_defaults;
145 //! Directory to store extension binaries in
146 string extension_directory;
147 //! Whether unsigned extensions should be loaded
148 bool allow_unsigned_extensions = false;
149 //! Enable emitting FSST Vectors
150 bool enable_fsst_vectors = false;
151 //! Start transactions immediately in all attached databases - instead of lazily when a database is referenced
152 bool immediate_transaction_mode = false;
153 //! Debug setting - how to initialize blocks in the storage layer when allocating
154 DebugInitialize debug_initialize = DebugInitialize::NO_INITIALIZE;
155 //! The set of unrecognized (other) options
156 unordered_map<string, Value> unrecognized_options;
157 //! Whether or not the configuration settings can be altered
158 bool lock_configuration = false;
159 //! Whether to print bindings when printing the plan (debug mode only)
160 static bool debug_print_bindings;
161
162 bool operator==(const DBConfigOptions &other) const;
163};
164
165struct DBConfig {
166 friend class DatabaseInstance;
167 friend class StorageManager;
168
169public:
170 DUCKDB_API DBConfig();
171 DUCKDB_API DBConfig(std::unordered_map<string, string> &config_dict, bool read_only);
172 DUCKDB_API ~DBConfig();
173
174 mutex config_lock;
175 //! Replacement table scans are automatically attempted when a table name cannot be found in the schema
176 vector<ReplacementScan> replacement_scans;
177
178 //! Extra parameters that can be SET for loaded extensions
179 case_insensitive_map_t<ExtensionOption> extension_parameters;
180 //! The FileSystem to use, can be overwritten to allow for injecting custom file systems for testing purposes (e.g.
181 //! RamFS or something similar)
182 unique_ptr<FileSystem> file_system;
183 //! The allocator used by the system
184 unique_ptr<Allocator> allocator;
185 //! Database configuration options
186 DBConfigOptions options;
187 //! Extensions made to the parser
188 vector<ParserExtension> parser_extensions;
189 //! Extensions made to the optimizer
190 vector<OptimizerExtension> optimizer_extensions;
191 //! Error manager
192 unique_ptr<ErrorManager> error_manager;
193 //! A reference to the (shared) default allocator (Allocator::DefaultAllocator)
194 shared_ptr<Allocator> default_allocator;
195 //! Extensions made to binder
196 vector<unique_ptr<OperatorExtension>> operator_extensions;
197 //! Extensions made to storage
198 case_insensitive_map_t<duckdb::unique_ptr<StorageExtension>> storage_extensions;
199 //! A buffer pool can be shared across multiple databases (if desired).
200 shared_ptr<BufferPool> buffer_pool;
201
202public:
203 DUCKDB_API static DBConfig &GetConfig(ClientContext &context);
204 DUCKDB_API static DBConfig &GetConfig(DatabaseInstance &db);
205 DUCKDB_API static DBConfig &Get(AttachedDatabase &db);
206 DUCKDB_API static const DBConfig &GetConfig(const ClientContext &context);
207 DUCKDB_API static const DBConfig &GetConfig(const DatabaseInstance &db);
208 DUCKDB_API static vector<ConfigurationOption> GetOptions();
209 DUCKDB_API static idx_t GetOptionCount();
210 DUCKDB_API static vector<string> GetOptionNames();
211
212 DUCKDB_API void AddExtensionOption(const string &name, string description, LogicalType parameter,
213 const Value &default_value = Value(), set_option_callback_t function = nullptr);
214 //! Fetch an option by index. Returns a pointer to the option, or nullptr if out of range
215 DUCKDB_API static ConfigurationOption *GetOptionByIndex(idx_t index);
216 //! Fetch an option by name. Returns a pointer to the option, or nullptr if none exists.
217 DUCKDB_API static ConfigurationOption *GetOptionByName(const string &name);
218
219 DUCKDB_API void SetOption(const ConfigurationOption &option, const Value &value);
220 DUCKDB_API void SetOption(DatabaseInstance *db, const ConfigurationOption &option, const Value &value);
221 DUCKDB_API void SetOptionByName(const string &name, const Value &value);
222 DUCKDB_API void ResetOption(DatabaseInstance *db, const ConfigurationOption &option);
223 DUCKDB_API void SetOption(const string &name, Value value);
224 DUCKDB_API void ResetOption(const string &name);
225
226 DUCKDB_API static idx_t ParseMemoryLimit(const string &arg);
227
228 //! Return the list of possible compression functions for the specific physical type
229 DUCKDB_API vector<reference<CompressionFunction>> GetCompressionFunctions(PhysicalType data_type);
230 //! Return the compression function for the specified compression type/physical type combo
231 DUCKDB_API optional_ptr<CompressionFunction> GetCompressionFunction(CompressionType type, PhysicalType data_type);
232
233 bool operator==(const DBConfig &other);
234 bool operator!=(const DBConfig &other);
235
236 DUCKDB_API CastFunctionSet &GetCastFunctions();
237 void SetDefaultMaxThreads();
238 void SetDefaultMaxMemory();
239
240 OrderType ResolveOrder(OrderType order_type) const;
241 OrderByNullType ResolveNullOrder(OrderType order_type, OrderByNullType null_type) const;
242
243private:
244 unique_ptr<CompressionFunctionSet> compression_functions;
245 unique_ptr<CastFunctionSet> cast_functions;
246};
247
248} // namespace duckdb
249