Configuration

Configuration options can be provided to change different settings of the database system. Note that many of these settings can be changed later on using PRAGMA statements as well. The configuration object should be created, filled with values, and passed to duckdb_open_ext.

Example

duckdb_database db;
duckdb_config config;

// create the configuration object
if (duckdb_create_config(&config) == DuckDBError) {
    // handle error
}
// set some configuration options
duckdb_set_config(config, "access_mode", "READ_WRITE"); // or READ_ONLY
duckdb_set_config(config, "threads", "8");
duckdb_set_config(config, "max_memory", "8GB");
duckdb_set_config(config, "default_order", "DESC");

// open the database using the configuration
if (duckdb_open_ext(NULL, &db, config, NULL) == DuckDBError) {
    // handle error
}
// cleanup the configuration object
duckdb_destroy_config(&config);

// run queries...

// cleanup
duckdb_close(&db);

API Reference Overview

duckdb_config_option duckdb_create_config_option(void);
void duckdb_destroy_config_option(duckdb_config_option *option);
void duckdb_config_option_set_name(duckdb_config_option option, const char *name);
void duckdb_config_option_set_type(duckdb_config_option option, duckdb_logical_type type);
void duckdb_config_option_set_default_value(duckdb_config_option option, duckdb_value default_value);
void duckdb_config_option_set_default_scope(duckdb_config_option option, duckdb_config_option_scope default_scope);
void duckdb_config_option_set_description(duckdb_config_option option, const char *description);
duckdb_state duckdb_register_config_option(duckdb_connection connection, duckdb_config_option option);
duckdb_value duckdb_client_context_get_config_option(duckdb_client_context context, const char *name, duckdb_config_option_scope *out_scope);
duckdb_profiling_info duckdb_get_profiling_info(duckdb_connection connection);
duckdb_value duckdb_profiling_info_get_value(duckdb_profiling_info info, const char *key);
duckdb_value duckdb_profiling_info_get_metrics(duckdb_profiling_info info);
idx_t duckdb_profiling_info_get_child_count(duckdb_profiling_info info);
duckdb_profiling_info duckdb_profiling_info_get_child(duckdb_profiling_info info, idx_t index);

duckdb_create_config_option

Stable since 1.5.6.

Creates a configuration option instance.

Syntax

duckdb_config_option duckdb_create_config_option(void);

Return Value

The resulting configuration option instance. Must be destroyed with duckdb_destroy_config_option.

duckdb_destroy_config_option

Stable since 1.5.6.

Destroys the given configuration option instance.

Syntax

void duckdb_destroy_config_option(
  duckdb_config_option *option
);

Parameters

• option: The configuration option instance to destroy.

duckdb_config_option_set_name

Stable since 1.5.6.

Sets the name of the configuration option.

Syntax

void duckdb_config_option_set_name(
  duckdb_config_option option,
  const char *name
);

Parameters

• option: The configuration option instance.
• name: The name to set.

duckdb_config_option_set_type

Stable since 1.5.6.

Sets the type of the configuration option.

Syntax

void duckdb_config_option_set_type(
  duckdb_config_option option,
  duckdb_logical_type type
);

Parameters

• option: The configuration option instance.
• type: The type to set.

duckdb_config_option_set_default_value

Stable since 1.5.6.

Sets the default value of the configuration option. If the type of this option has already been set with duckdb_config_option_set_type, the value is cast to the type. Otherwise, the type is inferred from the value.

Syntax

void duckdb_config_option_set_default_value(
  duckdb_config_option option,
  duckdb_value default_value
);

Parameters

• option: The configuration option instance.
• default_value: The default value to set.

duckdb_config_option_set_default_scope

Stable since 1.5.6.

Sets the default scope of the configuration option. If not set, this defaults to DUCKDB_CONFIG_OPTION_SCOPE_SESSION.

Syntax

void duckdb_config_option_set_default_scope(
  duckdb_config_option option,
  duckdb_config_option_scope default_scope
);

Parameters

• option: The configuration option instance.
• default_scope: The default scope to set.

duckdb_config_option_set_description

Stable since 1.5.6.

Sets the description of the configuration option.

Syntax

void duckdb_config_option_set_description(
  duckdb_config_option option,
  const char *description
);

Parameters

• option: The configuration option instance.
• description: The description to set.

duckdb_register_config_option

Stable since 1.5.6.

Registers the given configuration option on the specified connection.

Syntax

duckdb_state duckdb_register_config_option(
  duckdb_connection connection,
  duckdb_config_option option
);

Parameters

• connection: The connection to register the option on.
• option: The configuration option instance to register.

Return Value

A duckdb_state indicating success or failure.

duckdb_client_context_get_config_option

Stable since 1.5.6.

Retrieves the value of a configuration option by name from the given client context.

Syntax

duckdb_value duckdb_client_context_get_config_option(
  duckdb_client_context context,
  const char *name,
  duckdb_config_option_scope *out_scope
);

Parameters

• context: The client context.
• name: The name of the configuration option to retrieve.
• out_scope: Output parameter to optionally store the scope that the configuration option was retrieved from. If this is nullptr, the scope is not returned. If the requested option does not exist the scope is set to DUCKDB_CONFIG_OPTION_SCOPE_INVALID. (out)

Return Value

The value of the configuration option. Returns nullptr if the option does not exist.

duckdb_get_profiling_info

Stable since 1.1.0.

Returns the root node of the profiling information. Returns nullptr, if profiling is not enabled.

Syntax

duckdb_profiling_info duckdb_get_profiling_info(
  duckdb_connection connection
);

Parameters

• connection: A connection object.

Return Value

A profiling information object.

duckdb_profiling_info_get_value

Stable since 1.1.0.

Returns the value of the metric of the current profiling info node. Returns nullptr, if the metric does not exist or is not enabled. Currently, the value holds a string, and you can retrieve the string by calling the corresponding function: char *duckdb_get_varchar(duckdb_value value).

Syntax

duckdb_value duckdb_profiling_info_get_value(
  duckdb_profiling_info info,
  const char *key
);

Parameters

• info: A profiling information object.
• key: The name of the requested metric.

Return Value

The value of the metric. Must be freed with duckdb_destroy_value

duckdb_profiling_info_get_metrics

Stable since 1.1.0.

Returns the key-value metric map of this profiling node as a MAP duckdb_value. The individual elements are accessible via the duckdb_value MAP functions.

Syntax

duckdb_value duckdb_profiling_info_get_metrics(
  duckdb_profiling_info info
);

Parameters

• info: A profiling information object.

Return Value

The key-value metric map as a MAP duckdb_value.

duckdb_profiling_info_get_child_count

Stable since 1.1.0.

Returns the number of children in the current profiling info node.

Syntax

idx_t duckdb_profiling_info_get_child_count(
  duckdb_profiling_info info
);

Parameters

• info: A profiling information object.

Return Value

The number of children in the current node.

duckdb_profiling_info_get_child

Stable since 1.1.0.

Returns the child node at the specified index.

Syntax

duckdb_profiling_info duckdb_profiling_info_get_child(
  duckdb_profiling_info info,
  idx_t index
);

Parameters

• info: A profiling information object.
• index: The index of the child node.

Return Value

The child node at the specified index.