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_state duckdb_create_config(duckdb_config *out_config);
size_t duckdb_config_count();
duckdb_state duckdb_get_config_flag(size_t index, const char **out_name, const char **out_description);
duckdb_state duckdb_set_config(duckdb_config config, const char *name, const char *option);
void duckdb_destroy_config(duckdb_config *config);

duckdb_create_config

Initializes an empty configuration object that can be used to provide start-up options for the DuckDB instance through duckdb_open_ext. The duckdb_config must be destroyed using 'duckdb_destroy_config'

This will always succeed unless there is a malloc failure.

Note that duckdb_destroy_config should always be called on the resulting config, even if the function returns DuckDBError.

Syntax

duckdb_state duckdb_create_config(
  duckdb_config *out_config
);

Parameters

• out_config: The result configuration object.

Return Value

DuckDBSuccess on success or DuckDBError on failure.

duckdb_config_count

This returns the total amount of configuration options available for usage with duckdb_get_config_flag.

This should not be called in a loop as it internally loops over all the options.

Return Value

The amount of config options available.

Syntax

size_t duckdb_config_count(
  
);

duckdb_get_config_flag

Obtains a human-readable name and description of a specific configuration option. This can be used to e.g. display configuration options. This will succeed unless index is out of range (i.e., >= duckdb_config_count).

The result name or description MUST NOT be freed.

Syntax

duckdb_state duckdb_get_config_flag(
  size_t index,
  const char **out_name,
  const char **out_description
);

Parameters

• index: The index of the configuration option (between 0 and duckdb_config_count)
• out_name: A name of the configuration flag.
• out_description: A description of the configuration flag.

Return Value

DuckDBSuccess on success or DuckDBError on failure.

duckdb_set_config

Sets the specified option for the specified configuration. The configuration option is indicated by name. To obtain a list of config options, see duckdb_get_config_flag.

In the source code, configuration options are defined in config.cpp.

This can fail if either the name is invalid, or if the value provided for the option is invalid.

Syntax

duckdb_state duckdb_set_config(
  duckdb_config config,
  const char *name,
  const char *option
);

Parameters

• config: The configuration object to set the option on.
• name: The name of the configuration flag to set.
• option: The value to set the configuration flag to.

Return Value

DuckDBSuccess on success or DuckDBError on failure.

duckdb_destroy_config

Destroys the specified configuration object and de-allocates all memory allocated for the object.

Syntax

void duckdb_destroy_config(
  duckdb_config *config
);

Parameters

• config: The configuration object to destroy.