Start & Beenden

Um DuckDB zu verwenden, müssen Sie zuerst ein duckdb_database-Handle mit duckdb_open() initialisieren. duckdb_open() nimmt als Parameter die Datenbankdatei entgegen, aus der gelesen und in die geschrieben wird. Der spezielle Wert NULL (nullptr) kann verwendet werden, um eine In-Memory-Datenbank zu erzeugen. Beachten Sie, dass bei einer In-Memory-Datenbank keine Daten auf die Festplatte persistiert werden (d. h. alle Daten gehen verloren, wenn Sie den Prozess beenden).

Mit dem duckdb_database-Handle können Sie eine oder mehrere duckdb_connections mit duckdb_connect() erzeugen. Einzelne Verbindungen sind zwar thread-sicher, werden aber während einer Abfrage gesperrt. Es wird daher empfohlen, dass jeder Thread seine eigene Verbindung verwendet, um die beste parallele Leistung zu erzielen.

Alle duckdb_connections müssen explizit mit duckdb_disconnect() getrennt werden, und die duckdb_database muss explizit mit duckdb_close() geschlossen werden, um Speicher- und Datei-Handle-Leaks zu vermeiden.

Beispiel

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-Referenz im Überblick

duckdb_instance_cache duckdb_create_instance_cache();
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);
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);
const char *duckdb_library_version();
duckdb_value duckdb_get_table_names(duckdb_connection connection, const char *query, bool qualified);

`duckdb_create_instance_cache`

Erzeugt einen neuen Datenbank-Instanzcache. Der Instanzcache ist notwendig, wenn ein Client/Programm innerhalb desselben Prozesses mehrere Datenbanken zur selben Datei (wieder)öffnet. Muss mit ‘duckdb_destroy_instance_cache’ zerstört werden.

Rückgabewert

Der Datenbank-Instanzcache.

Syntax

duckdb_instance_cache duckdb_create_instance_cache(
  
);

`duckdb_get_or_create_from_cache`

Erzeugt eine neue Datenbankinstanz im Instanzcache oder holt eine vorhandene Datenbankinstanz. Muss mit ‘duckdb_close’ geschlossen werden.

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

Parameter

instance_cache: Der Instanzcache, in dem die Datenbank erzeugt oder aus dem sie geholt wird.
path: Pfad zur Datenbankdatei auf der Festplatte. Sowohl nullptr als auch :memory: öffnen oder holen eine In-Memory-Datenbank.
out_database: Die resultierende gecachte Datenbank.
config: (Optional) Konfiguration, die zum Erzeugen der Datenbank verwendet wird.
out_error: Falls gesetzt und die Funktion DuckDBError zurückgibt, enthält dies die Fehlermeldung. Beachten Sie, dass die Fehlermeldung mit duckdb_free freigegeben werden muss.

Rückgabewert

DuckDBSuccess bei Erfolg oder DuckDBError bei Fehler.

`duckdb_destroy_instance_cache`

Zerstört einen vorhandenen Datenbank-Instanzcache und gibt seinen Speicher frei.

Syntax

void duckdb_destroy_instance_cache(
  duckdb_instance_cache *instance_cache
);

Parameter

instance_cache: Der zu zerstörende Instanzcache.

`duckdb_open`

Erzeugt eine neue Datenbank oder öffnet eine vorhandene Datenbankdatei am angegebenen Pfad. Wird kein Pfad angegeben, wird stattdessen eine neue In-Memory-Datenbank erzeugt. Die Datenbank muss mit ‘duckdb_close’ geschlossen werden.

Syntax

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

Parameter

path: Pfad zur Datenbankdatei auf der Festplatte. Sowohl nullptr als auch :memory: öffnen eine In-Memory-Datenbank.
out_database: Das resultierende Datenbankobjekt.

Rückgabewert

DuckDBSuccess bei Erfolg oder DuckDBError bei Fehler.

`duckdb_open_ext`

Erweiterte Version von duckdb_open. Erzeugt eine neue Datenbank oder öffnet eine vorhandene Datenbankdatei am angegebenen Pfad. Die Datenbank muss mit ‘duckdb_close’ geschlossen werden.

Syntax

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

Parameter

path: Pfad zur Datenbankdatei auf der Festplatte. Sowohl nullptr als auch :memory: öffnen eine In-Memory-Datenbank.
out_database: Das resultierende Datenbankobjekt.
config: (Optional) Konfiguration, die zum Starten der Datenbank verwendet wird.
out_error: Falls gesetzt und die Funktion DuckDBError zurückgibt, enthält dies die Fehlermeldung. Beachten Sie, dass die Fehlermeldung mit duckdb_free freigegeben werden muss.

Rückgabewert

DuckDBSuccess bei Erfolg oder DuckDBError bei Fehler.

`duckdb_close`

Schließt die angegebene Datenbank und gibt den gesamten für diese Datenbank allokierten Speicher frei. Dies sollte aufgerufen werden, nachdem Sie mit einer über duckdb_open oder duckdb_open_ext allokierten Datenbank fertig sind. Beachten Sie, dass das Versäumnis, duckdb_close aufzurufen (z. B. bei einem Programmabsturz), keine Datenkorruption verursacht. Trotzdem wird empfohlen, ein Datenbankobjekt immer korrekt zu schließen, wenn Sie damit fertig sind.

Syntax

void duckdb_close(
  duckdb_database *database
);

Parameter

database: Das herunterzufahrende Datenbankobjekt.

`duckdb_connect`

Öffnet eine Verbindung zu einer Datenbank. Verbindungen werden benötigt, um die Datenbank abzufragen und den mit der Verbindung verbundenen Transaktionszustand zu speichern. Die instanziierte Verbindung sollte mit ‘duckdb_disconnect’ geschlossen werden.

Syntax

duckdb_state duckdb_connect(
  duckdb_database database,
  duckdb_connection *out_connection
);

Parameter

database: Die Datenbankdatei, mit der verbunden wird.
out_connection: Das resultierende Verbindungsobjekt.

Rückgabewert

DuckDBSuccess bei Erfolg oder DuckDBError bei Fehler.

`duckdb_interrupt`

Unterbricht eine laufende Abfrage

Syntax

void duckdb_interrupt(
  duckdb_connection connection
);

Parameter

connection: Die zu unterbrechende Verbindung

`duckdb_query_progress`

Ermittelt den Fortschritt der laufenden Abfrage

Syntax

duckdb_query_progress_type duckdb_query_progress(
  duckdb_connection connection
);

Parameter

connection: Die aktive Verbindung

Rückgabewert

-1, wenn kein Fortschritt vorliegt, oder ein Prozentsatz des Fortschritts

`duckdb_disconnect`

Schließt die angegebene Verbindung und gibt den gesamten für diese Verbindung allokierten Speicher frei.

Syntax

void duckdb_disconnect(
  duckdb_connection *connection
);

Parameter

connection: Die zu schließende Verbindung.

`duckdb_connection_get_client_context`

Ermittelt den Client-Kontext der Verbindung.

Syntax

void duckdb_connection_get_client_context(
  duckdb_connection connection,
  duckdb_client_context *out_context
);

Parameter

connection: Die Verbindung.
out_context: Der Client-Kontext der Verbindung. Muss mit duckdb_destroy_client_context zerstört werden.

`duckdb_connection_get_arrow_options`

Ermittelt die Arrow-Optionen der Verbindung.

Syntax

void duckdb_connection_get_arrow_options(
  duckdb_connection connection,
  duckdb_arrow_options *out_arrow_options
);

Parameter

connection: Die Verbindung.

`duckdb_client_context_get_connection_id`

Gibt die Verbindungs-ID des Client-Kontexts zurück.

Syntax

idx_t duckdb_client_context_get_connection_id(
  duckdb_client_context context
);

Parameter

context: Der Client-Kontext.

Rückgabewert

Die Verbindungs-ID des Client-Kontexts.

`duckdb_destroy_client_context`

Zerstört den Client-Kontext und gibt seinen Speicher frei.

Syntax

void duckdb_destroy_client_context(
  duckdb_client_context *context
);

Parameter

context: Der zu zerstörende Client-Kontext.

`duckdb_destroy_arrow_options`

Zerstört die Arrow-Optionen und gibt ihren Speicher frei.

Syntax

void duckdb_destroy_arrow_options(
  duckdb_arrow_options *arrow_options
);

Parameter

arrow_options: Die zu zerstörenden Arrow-Optionen.

`duckdb_library_version`

Gibt die Version der gelinkten DuckDB zurück, mit einem Versions-Postfix für Dev-Versionen

Üblicherweise verwendet für die Entwicklung von C-Erweiterungen, die dies für eine Kompatibilitätsprüfung zurückgeben müssen.

Syntax

const char *duckdb_library_version(
  
);

`duckdb_get_table_names`

Ermittelt die Liste der (vollständig qualifizierten) Tabellennamen der Abfrage.

Syntax

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

Parameter

connection: Die Verbindung, für die die Tabellennamen ermittelt werden.
query: Die Abfrage, für die die Tabellennamen ermittelt werden.
qualified: Gibt vollständig qualifizierte Tabellennamen (catalog.schema.table) zurück, wenn auf true gesetzt, andernfalls nur die (nicht escapeten) Tabellennamen.

Rückgabewert

Ein duckdb_value vom Typ VARCHAR[] mit den (vollständig qualifizierten) Tabellennamen der Abfrage. Muss mit duckdb_destroy_value zerstört werden.