C API - 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

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_disconnect(duckdb_connection *connection);

duckdb_open


Creates a new database or opens an existing database file stored at the the given path. If no path is given a new in-memory database is created instead.

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.

  • returns

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 the given path.

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.

  • returns

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. 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.

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.

  • returns

DuckDBSuccess on success or DuckDBError on failure.


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.