Startup & Shutdown

To use DuckDB, you must first initialize a duckdb_database handle using duckdb_open(). duckdb_open() takes as parameter the database file to read and write from. The special value NULL (nullptr) can be used to create an in-memory database. Note that for an in-memory database no data is persisted to disk (i.e., all data is lost when you exit the process).

With the duckdb_database handle, you can create one or many duckdb_connection using duckdb_connect(). While individual connections are thread-safe, they will be locked during querying. It is therefore recommended that each thread uses its own connection to allow for the best parallel performance.

All duckdb_connections have to explicitly be disconnected with duckdb_disconnect() and the duckdb_database has to be explicitly closed with duckdb_close() to avoid memory and file handle leaking.

Example

duckdb_database db;
duckdb_connection con;

if (duckdb_open(NULL, &db) == DuckDBError) {
    // handle error
}
if (duckdb_connect(db, &con) == DuckDBError) {
    // handle error
}

// run queries...

// cleanup
duckdb_disconnect(&con);
duckdb_close(&db);

API Reference Overview

duckdb_instance_cache duckdb_create_instance_cache(void);
duckdb_state duckdb_get_or_create_from_cache(duckdb_instance_cache instance_cache, const char *path, duckdb_database *out_database, duckdb_config config, char **out_error);
void duckdb_destroy_instance_cache(duckdb_instance_cache *instance_cache);
duckdb_state duckdb_open(const char *path, duckdb_database *out_database);
duckdb_state duckdb_open_ext(const char *path, duckdb_database *out_database, duckdb_config config, char **out_error);
void duckdb_close(duckdb_database *database);
const char *duckdb_library_version(void);
duckdb_state duckdb_create_config(duckdb_config *out_config);
size_t duckdb_config_count(void);
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_instance_cache

Stable since 1.5.6.

Creates a new database instance cache. The instance cache is necessary if a client/program (re)opens multiple databases to the same file within the same process. Must be destroyed with 'duckdb_destroy_instance_cache'.

Syntax

duckdb_instance_cache duckdb_create_instance_cache(void);

Return Value

The database instance cache.

duckdb_get_or_create_from_cache

Stable since 1.5.6.

Creates a new database instance in the instance cache, or retrieves an existing database instance. Must be closed with 'duckdb_close'.

Syntax

duckdb_state duckdb_get_or_create_from_cache(
  duckdb_instance_cache instance_cache,
  const char *path,
  duckdb_database *out_database,
  duckdb_config config,
  char **out_error
);

Parameters

• instance_cache: The instance cache in which to create the database, or from which to take the database.
• path: Path to the database file on disk. Both nullptr and :memory: open or retrieve an in-memory database.
• out_database: The resulting cached database. (out)
• config: (Optional) configuration used to create the database.
• out_error: If set and the function returns DuckDBError, this contains the error message. Note that the error message must be freed using duckdb_free. (out)

Return Value

DuckDBSuccess on success or DuckDBError on failure.

duckdb_destroy_instance_cache

Stable since 1.5.6.

Destroys an existing database instance cache and de-allocates its memory.

Syntax

void duckdb_destroy_instance_cache(
  duckdb_instance_cache *instance_cache
);

Parameters

• instance_cache: The instance cache to destroy.

duckdb_open

Stable since 0.1.0.

Creates a new database or opens an existing database file stored at the given path. If no path is given a new in-memory database is created instead. The database must be closed with 'duckdb_close'.

Syntax

duckdb_state duckdb_open(
  const char *path,
  duckdb_database *out_database
);

Parameters

• path: Path to the database file on disk. Both nullptr and :memory: open an in-memory database.
• out_database: The result database object. (out)

Return Value

DuckDBSuccess on success or DuckDBError on failure.

duckdb_open_ext

Stable since 0.2.8.

Extended version of duckdb_open. Creates a new database or opens an existing database file stored at the given path. The database must be closed with 'duckdb_close'.

Syntax

duckdb_state duckdb_open_ext(
  const char *path,
  duckdb_database *out_database,
  duckdb_config config,
  char **out_error
);

Parameters

• path: Path to the database file on disk. Both nullptr and :memory: open an in-memory database.
• out_database: The result database object. (out)
• config: (Optional) configuration used to start up the database.
• out_error: If set and the function returns DuckDBError, this contains the error message. Note that the error message must be freed using duckdb_free. (out)

Return Value

DuckDBSuccess on success or DuckDBError on failure.

duckdb_close

Stable since 0.1.0.

Closes the specified database and de-allocates all memory allocated for that database. This should be called after you are done with any database allocated through duckdb_open or duckdb_open_ext. Note that failing to call duckdb_close (in case of e.g. a program crash) will not cause data corruption. Still, it is recommended to always correctly close a database object after you are done with it.

Syntax

void duckdb_close(
  duckdb_database *database
);

Parameters

• database: The database object to shut down.

duckdb_library_version

Stable since 0.6.0.

Returns the version of the linked DuckDB, with a version postfix for dev versions

Usually used for developing C extensions that must return this for a compatibility check.

Syntax

const char *duckdb_library_version(void);

Return Value

const char *

duckdb_create_config

Stable since 0.2.8.

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. (out)

Return Value

DuckDBSuccess on success or DuckDBError on failure.

duckdb_config_count

Stable since 0.2.8.

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.

Syntax

size_t duckdb_config_count(void);

Return Value

The amount of config options available.

duckdb_get_config_flag

Stable since 0.2.8.

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)
• out_description: A description of the configuration flag. (out)

Return Value

DuckDBSuccess on success or DuckDBError on failure.

duckdb_set_config

Stable since 0.2.8.

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

Stable since 0.2.8.

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.

Connection

duckdb_state duckdb_connect(duckdb_database database, duckdb_connection *out_connection);
void duckdb_interrupt(duckdb_connection connection);
duckdb_query_progress_type duckdb_query_progress(duckdb_connection connection);
void duckdb_disconnect(duckdb_connection *connection);
void duckdb_connection_get_client_context(duckdb_connection connection, duckdb_client_context *out_context);
void duckdb_connection_get_arrow_options(duckdb_connection connection, duckdb_arrow_options *out_arrow_options);
idx_t duckdb_client_context_get_connection_id(duckdb_client_context context);
void duckdb_destroy_client_context(duckdb_client_context *context);
void duckdb_destroy_arrow_options(duckdb_arrow_options *arrow_options);
duckdb_value duckdb_get_table_names(duckdb_connection connection, const char *query, bool qualified);

duckdb_connect

Stable since 0.1.0.

Opens a connection to a database. Connections are required to query the database, and store transactional state associated with the connection. The instantiated connection should be closed using 'duckdb_disconnect'.

Syntax

duckdb_state duckdb_connect(
  duckdb_database database,
  duckdb_connection *out_connection
);

Parameters

• database: The database file to connect to.
• out_connection: The result connection object. (out)

Return Value

DuckDBSuccess on success or DuckDBError on failure.

duckdb_interrupt

Stable since 0.9.0.

Interrupt running query

Syntax

void duckdb_interrupt(
  duckdb_connection connection
);

Parameters

• connection: The connection to interrupt

duckdb_query_progress

Stable since 0.10.0.

Get the progress of the running query.

Syntax

duckdb_query_progress_type duckdb_query_progress(
  duckdb_connection connection
);

Parameters

• connection: The connection running the query.

Return Value

The query progress type containing progress information.

duckdb_disconnect

Stable since 0.1.0.

Closes the specified connection and de-allocates all memory allocated for that connection.

Syntax

void duckdb_disconnect(
  duckdb_connection *connection
);

Parameters

• connection: The connection to close.

duckdb_connection_get_client_context

Stable since 1.5.6.

Retrieves the client context of the connection.

Syntax

void duckdb_connection_get_client_context(
  duckdb_connection connection,
  duckdb_client_context *out_context
);

Parameters

• connection: The connection.
• out_context: The client context of the connection. Must be destroyed with duckdb_destroy_client_context. (out)

duckdb_connection_get_arrow_options

Stable since 1.5.6.

Retrieves the arrow options of the connection.

Syntax

void duckdb_connection_get_arrow_options(
  duckdb_connection connection,
  duckdb_arrow_options *out_arrow_options
);

Parameters

• connection: The connection.
• out_arrow_options: (out)

duckdb_client_context_get_connection_id

Stable since 1.5.6.

Returns the connection id of the client context.

Syntax

idx_t duckdb_client_context_get_connection_id(
  duckdb_client_context context
);

Parameters

• context: The client context.

Return Value

The connection id of the client context.

duckdb_destroy_client_context

Stable since 1.5.6.

Destroys the client context and deallocates its memory.

Syntax

void duckdb_destroy_client_context(
  duckdb_client_context *context
);

Parameters

• context: The client context to destroy.

duckdb_destroy_arrow_options

Stable since 1.5.6.

Destroys the arrow options and deallocates its memory.

Syntax

void duckdb_destroy_arrow_options(
  duckdb_arrow_options *arrow_options
);

Parameters

• arrow_options: The arrow options to destroy.

duckdb_get_table_names

Stable since 1.5.6.

Get the list of (fully qualified) table names of the query.

Syntax

duckdb_value duckdb_get_table_names(
  duckdb_connection connection,
  const char *query,
  bool qualified
);

Parameters

• connection: The connection for which to get the table names.
• query: The query for which to get the table names.
• qualified: Returns fully qualified table names (catalog.schema.table), if set to true, else only the (not escaped) table names.

Return Value

A duckdb_value of type VARCHAR[] containing the (fully qualified) table names of the query. Must be destroyed with duckdb_destroy_value.