pub struct ConfigOptionBuilder { /* private fields */ }Expand description
Builder for registering extension-defined configuration options.
After building, call register from your entry point to
register the setting with DuckDB.
Implementations§
Source§impl ConfigOptionBuilder
impl ConfigOptionBuilder
Sourcepub fn try_new(name: &str) -> Result<Self, ExtensionError>
pub fn try_new(name: &str) -> Result<Self, ExtensionError>
Creates a new config option builder with the given name.
§Errors
Returns ExtensionError if the name contains a null byte.
Sourcepub fn description(self, desc: &str) -> Result<Self, ExtensionError>
pub fn description(self, desc: &str) -> Result<Self, ExtensionError>
Sets the human-readable description for this option.
§Errors
Returns ExtensionError if desc contains a null byte.
Sourcepub const fn option_type(self, type_id: TypeId) -> Self
pub const fn option_type(self, type_id: TypeId) -> Self
Sets the value type for this option (e.g. TypeId::BigInt, TypeId::Varchar).
Sourcepub fn default_value(self, value: &str) -> Result<Self, ExtensionError>
pub fn default_value(self, value: &str) -> Result<Self, ExtensionError>
Sets the default value as a string representation.
The string is converted to the option’s type at
register time, with the same SQL cast SET uses;
a string that does not convert is an error there. Every option needs a
default — see register.
§Errors
Returns ExtensionError if value contains a null byte.
Sourcepub const fn scope(self, scope: ConfigOptionScope) -> Self
pub const fn scope(self, scope: ConfigOptionScope) -> Self
Sets the scope for this option.
Sourcepub unsafe fn register(
self,
con: duckdb_connection,
) -> Result<(), ExtensionError>
pub unsafe fn register( self, con: duckdb_connection, ) -> Result<(), ExtensionError>
Registers this config option with DuckDB.
§The default is converted by SQL, never inside the C API
duckdb_config_option_set_default_value converts a default whose type
differs from the option’s with Value::DefaultCastAs — a throwing
cast with no try/catch around it — so a string default that does
not convert would abort the process (“Rust cannot catch foreign
exceptions”). Worse, DefaultCastAs uses only the built-in casts while
SQL uses the connection’s, so a string one accepts can still make the
other throw: with ICU loaded, '2020-01-01 10:00:00 America/New_York'
is a valid TIMESTAMPTZ in SQL and an abort in DefaultCastAs.
register therefore converts the default itself, by running
SELECT TRY_CAST($1::VARCHAR AS <type>) on con with the default bound
as a parameter, and hands DuckDB a value that already has the
option’s type. duckdb_config_option_set_default_value stores such a
value as-is (it only casts when coption->type != cvalue->type(),
src/main/capi/config_options-c.cpp), so no cast can run inside the C
API. The stored default is exactly what TRY_CAST('<default>' AS <type>)
produces in SQL on con.
Option types whose values the C API cannot construct from a query
result (BIGNUM, GEOMETRY, VARIANT, …) are refused rather than
sent down the throwing path.
§Errors
Returns ExtensionError, before anything is registered, if:
- the option type was not set, or is a pseudo-type (
ANY,SQLNULL, the literal types) that no setting can have; - no default value was set.
DuckDBtreats an extension option without a default as unset:current_settingreports it as an “unrecognized configuration parameter” until someoneSETs it, andClientContext::config_optionon it takes the path a debug build ofDuckDBasserts on; - the name is already a setting — built-in (
threads), an alias of one (worker_threads), or another extension’s. Names are compared case-insensitively, asDuckDBresolves them.DuckDBitself only refuses a name another extension option has, and silently lets an extension option shadow a built-in one forcurrent_setting; - the default does not convert to the option type (or the conversion
query cannot run on
con), or the type cannot carry a default; duckdb_register_config_optionfails.
§Safety
con must be a valid, open duckdb_connection.