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_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);
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);
const char *duckdb_library_version();

duckdb_open

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 instantiated database should 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, or nullptr or :memory: to open an in-memory database.
• out_database: The result database object.

Return Value

DuckDBSuccess on success or DuckDBError on failure.

duckdb_open_ext

Extended version of duckdb_open. Creates a new database or opens an existing database file stored at the given path. The instantiated database should 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, or nullptr or :memory: to open an in-memory database.
• out_database: The result database object.
• config: (Optional) configuration used to start up the database system.
• out_error: If set and the function returns DuckDBError, this will contain the reason why the start-up failed. Note that the error must be freed using duckdb_free.

Return Value

DuckDBSuccess on success or DuckDBError on failure.

duckdb_close

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_connect

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.

Return Value

DuckDBSuccess on success or DuckDBError on failure.

duckdb_interrupt

Interrupt running query

Syntax

void duckdb_interrupt(
  duckdb_connection connection
);

Parameters

• connection: The connection to interrupt

duckdb_query_progress

Get progress of the running query

Syntax

duckdb_query_progress_type duckdb_query_progress(
  duckdb_connection connection
);

Parameters

• connection: The working connection

Return Value

-1 if no progress or a percentage of the progress

duckdb_disconnect

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_library_version

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(
  
);