---
layout: docu
redirect_from:
- /docs/api/c/connect
- /docs/api/c/connect/
- /docs/clients/c/connect
title: Startup & Shutdown
---

<!-- markdownlint-disable MD001 -->

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_connection`s 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

```c
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

<!-- This section is generated by scripts/generate_c_api_docs.py -->

<div class="language-c highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nv">duckdb_instance_cache</span> <a href="#duckdb_create_instance_cache"><span class="nf">duckdb_create_instance_cache</span></a>();
<span class="kt">duckdb_state</span> <a href="#duckdb_get_or_create_from_cache"><span class="nf">duckdb_get_or_create_from_cache</span></a>(<span class="nv">duckdb_instance_cache</span> <span class="nv">instance_cache</span>, <span class="kt">const</span> <span class="kt">char</span> *<span class="nv">path</span>, <span class="kt">duckdb_database</span> *<span class="nv">out_database</span>, <span class="kt">duckdb_config</span> <span class="nv">config</span>, <span class="kt">char</span> **<span class="nv">out_error</span>);
<span class="kt">void</span> <a href="#duckdb_destroy_instance_cache"><span class="nf">duckdb_destroy_instance_cache</span></a>(<span class="nv">duckdb_instance_cache</span> *<span class="nv">instance_cache</span>);
<span class="kt">duckdb_state</span> <a href="#duckdb_open"><span class="nf">duckdb_open</span></a>(<span class="kt">const</span> <span class="kt">char</span> *<span class="nv">path</span>, <span class="kt">duckdb_database</span> *<span class="nv">out_database</span>);
<span class="kt">duckdb_state</span> <a href="#duckdb_open_ext"><span class="nf">duckdb_open_ext</span></a>(<span class="kt">const</span> <span class="kt">char</span> *<span class="nv">path</span>, <span class="kt">duckdb_database</span> *<span class="nv">out_database</span>, <span class="kt">duckdb_config</span> <span class="nv">config</span>, <span class="kt">char</span> **<span class="nv">out_error</span>);
<span class="kt">void</span> <a href="#duckdb_close"><span class="nf">duckdb_close</span></a>(<span class="kt">duckdb_database</span> *<span class="nv">database</span>);
<span class="kt">duckdb_state</span> <a href="#duckdb_connect"><span class="nf">duckdb_connect</span></a>(<span class="kt">duckdb_database</span> <span class="nv">database</span>, <span class="kt">duckdb_connection</span> *<span class="nv">out_connection</span>);
<span class="kt">void</span> <a href="#duckdb_interrupt"><span class="nf">duckdb_interrupt</span></a>(<span class="kt">duckdb_connection</span> <span class="nv">connection</span>);
<span class="kt">duckdb_query_progress_type</span> <a href="#duckdb_query_progress"><span class="nf">duckdb_query_progress</span></a>(<span class="kt">duckdb_connection</span> <span class="nv">connection</span>);
<span class="kt">void</span> <a href="#duckdb_disconnect"><span class="nf">duckdb_disconnect</span></a>(<span class="kt">duckdb_connection</span> *<span class="nv">connection</span>);
<span class="kt">const</span> <span class="kt">char</span> *<a href="#duckdb_library_version"><span class="nf">duckdb_library_version</span></a>();
</code></pre></div></div>

#### `duckdb_create_instance_cache`

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


##### Return Value

The database instance cache.

##### Syntax

<div class="language-c highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nv">duckdb_instance_cache</span> <span class="nv">duckdb_create_instance_cache</span>(<span class="nv">
</span>  <span class="nv">
</span>);
</code></pre></div></div>
<br>

#### `duckdb_get_or_create_from_cache`

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

##### Syntax

<div class="language-c highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kt">duckdb_state</span> <span class="nv">duckdb_get_or_create_from_cache</span>(<span class="nv">
</span>  <span class="nv">duckdb_instance_cache</span> <span class="nv">instance_cache</span>,<span class="nv">
</span>  <span class="kt">const</span> <span class="kt">char</span> *<span class="nv">path</span>,<span class="nv">
</span>  <span class="kt">duckdb_database</span> *<span class="nv">out_database</span>,<span class="nv">
</span>  <span class="kt">duckdb_config</span> <span class="nv">config</span>,<span class="nv">
</span>  <span class="kt">char</span> **<span class="nv">out_error
</span>);
</code></pre></div></div>

##### 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.
* `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`.

##### Return Value

`DuckDBSuccess` on success or `DuckDBError` on failure.

<br>

#### `duckdb_destroy_instance_cache`

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

##### Syntax

<div class="language-c highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kt">void</span> <span class="nv">duckdb_destroy_instance_cache</span>(<span class="nv">
</span>  <span class="nv">duckdb_instance_cache</span> *<span class="nv">instance_cache
</span>);
</code></pre></div></div>

##### Parameters

* `instance_cache`: The instance cache to destroy.

<br>

#### `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 database must be closed with 'duckdb_close'.

##### Syntax

<div class="language-c highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kt">duckdb_state</span> <span class="nv">duckdb_open</span>(<span class="nv">
</span>  <span class="kt">const</span> <span class="kt">char</span> *<span class="nv">path</span>,<span class="nv">
</span>  <span class="kt">duckdb_database</span> *<span class="nv">out_database
</span>);
</code></pre></div></div>

##### Parameters

* `path`: Path to the database file on disk. Both `nullptr` and `:memory:` open an in-memory database.
* `out_database`: The result database object.

##### Return Value

`DuckDBSuccess` on success or `DuckDBError` on failure.

<br>

#### `duckdb_open_ext`

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

<div class="language-c highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kt">duckdb_state</span> <span class="nv">duckdb_open_ext</span>(<span class="nv">
</span>  <span class="kt">const</span> <span class="kt">char</span> *<span class="nv">path</span>,<span class="nv">
</span>  <span class="kt">duckdb_database</span> *<span class="nv">out_database</span>,<span class="nv">
</span>  <span class="kt">duckdb_config</span> <span class="nv">config</span>,<span class="nv">
</span>  <span class="kt">char</span> **<span class="nv">out_error
</span>);
</code></pre></div></div>

##### Parameters

* `path`: Path to the database file on disk. Both `nullptr` and `:memory:` open an in-memory database.
* `out_database`: The result database object.
* `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`.

##### Return Value

`DuckDBSuccess` on success or `DuckDBError` on failure.

<br>

#### `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

<div class="language-c highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kt">void</span> <span class="nv">duckdb_close</span>(<span class="nv">
</span>  <span class="kt">duckdb_database</span> *<span class="nv">database
</span>);
</code></pre></div></div>

##### Parameters

* `database`: The database object to shut down.

<br>

#### `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

<div class="language-c highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kt">duckdb_state</span> <span class="nv">duckdb_connect</span>(<span class="nv">
</span>  <span class="kt">duckdb_database</span> <span class="nv">database</span>,<span class="nv">
</span>  <span class="kt">duckdb_connection</span> *<span class="nv">out_connection
</span>);
</code></pre></div></div>

##### Parameters

* `database`: The database file to connect to.
* `out_connection`: The result connection object.

##### Return Value

`DuckDBSuccess` on success or `DuckDBError` on failure.

<br>

#### `duckdb_interrupt`

Interrupt running query

##### Syntax

<div class="language-c highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kt">void</span> <span class="nv">duckdb_interrupt</span>(<span class="nv">
</span>  <span class="kt">duckdb_connection</span> <span class="nv">connection
</span>);
</code></pre></div></div>

##### Parameters

* `connection`: The connection to interrupt

<br>

#### `duckdb_query_progress`

Get progress of the running query

##### Syntax

<div class="language-c highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kt">duckdb_query_progress_type</span> <span class="nv">duckdb_query_progress</span>(<span class="nv">
</span>  <span class="kt">duckdb_connection</span> <span class="nv">connection
</span>);
</code></pre></div></div>

##### Parameters

* `connection`: The working connection

##### Return Value

-1 if no progress or a percentage of the progress

<br>

#### `duckdb_disconnect`

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

##### Syntax

<div class="language-c highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kt">void</span> <span class="nv">duckdb_disconnect</span>(<span class="nv">
</span>  <span class="kt">duckdb_connection</span> *<span class="nv">connection
</span>);
</code></pre></div></div>

##### Parameters

* `connection`: The connection to close.

<br>

#### `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

<div class="language-c highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kt">const</span> <span class="kt">char</span> *<span class="nv">duckdb_library_version</span>(<span class="nv">
</span>  <span class="nv">
</span>);
</code></pre></div></div>
<br>