启动与关闭 – DuckDB - DuckDB 数据库

搜索快捷键 cmd + k | ctrl + k

文档 / 客户端API / C

启动与关闭

要使用 DuckDB，必须首先使用 duckdb_open() 初始化一个 duckdb_database 句柄。duckdb_open() 接受要读写的数据库文件作为参数。可以使用特殊值 NULL (nullptr) 来创建内存数据库。请注意，对于内存数据库，数据不会持久化到磁盘（即：当您退出进程时，所有数据都会丢失）。

有了 duckdb_database 句柄，您可以使用 duckdb_connect() 创建一个或多个 duckdb_connection。虽然单个连接是线程安全的，但它们在查询期间会被锁定。因此，建议每个线程使用自己的连接，以实现最佳的并行性能。

所有 duckdb_connection 必须显式地使用 duckdb_disconnect() 断开连接，并且 duckdb_database 必须显式地使用 duckdb_close() 关闭，以避免内存和文件句柄泄漏。

示例

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参考概览

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`

创建一个新的数据库实例缓存。如果客户端/程序在同一个进程内多次（重新）打开同一个文件的数据库，则必须使用实例缓存。必须使用 'duckdb_destroy_instance_cache' 进行销毁。

返回值

数据库实例缓存。

语法

duckdb_instance_cache duckdb_create_instance_cache(
  
);

`duckdb_get_or_create_from_cache`

在实例缓存中创建一个新的数据库实例，或检索现有的数据库实例。必须使用 'duckdb_close' 关闭。

语法

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

参数

instance_cache：要在其中创建数据库或从中获取数据库的实例缓存。
path：磁盘上数据库文件的路径。nullptr 和 :memory: 均可打开或检索内存数据库。
out_database：生成的缓存数据库。
config：（可选）用于创建数据库的配置。
out_error：如果设置该参数且函数返回 DuckDBError，则此项包含错误消息。注意，必须使用 duckdb_free 释放该错误消息。

返回值

成功时返回 DuckDBSuccess，失败时返回 DuckDBError。

`duckdb_destroy_instance_cache`

销毁现有的数据库实例缓存并释放其内存。

语法

void duckdb_destroy_instance_cache(
  duckdb_instance_cache *instance_cache
);

参数

instance_cache：要销毁的实例缓存。

`duckdb_open`

创建一个新数据库或打开位于给定路径的现有数据库文件。如果没有给出路径，则创建一个新的内存数据库。必须使用 'duckdb_close' 关闭数据库。

语法

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

参数

path：磁盘上数据库文件的路径。nullptr 和 :memory: 均打开一个内存数据库。
out_database：结果数据库对象。

返回值

成功时返回 DuckDBSuccess，失败时返回 DuckDBError。

`duckdb_open_ext`

duckdb_open 的扩展版本。创建一个新数据库或打开位于给定路径的现有数据库文件。必须使用 'duckdb_close' 关闭数据库。

语法

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

参数

path：磁盘上数据库文件的路径。nullptr 和 :memory: 均打开一个内存数据库。
out_database：结果数据库对象。
config：（可选）用于启动数据库的配置。
out_error：如果设置该参数且函数返回 DuckDBError，则此项包含错误消息。注意，必须使用 duckdb_free 释放该错误消息。

void duckdb_close(
  duckdb_database *database
);

参数

database：要关闭的数据库对象。

`duckdb_connect`

打开与数据库的连接。查询数据库及存储与连接相关的事务状态需要连接。实例化的连接应使用 'duckdb_disconnect' 关闭。

语法

duckdb_state duckdb_connect(
  duckdb_database database,
  duckdb_connection *out_connection
);

参数

database：要连接的数据库文件。
out_connection：结果连接对象。

void duckdb_interrupt(
  duckdb_connection connection
);

参数

connection：要中断的连接

`duckdb_query_progress`

获取正在运行的查询的进度

语法

duckdb_query_progress_type duckdb_query_progress(
  duckdb_connection connection
);

参数

connection：工作连接

void duckdb_disconnect(
  duckdb_connection *connection
);

参数

connection：要关闭的连接。

`duckdb_connection_get_client_context`

检索连接的客户端上下文。

语法

void duckdb_connection_get_client_context(
  duckdb_connection connection,
  duckdb_client_context *out_context
);

参数

connection：连接。
out_context：连接的客户端上下文。必须使用 duckdb_destroy_client_context 进行销毁。

`duckdb_connection_get_arrow_options`

检索连接的 Arrow 选项。

语法

void duckdb_connection_get_arrow_options(
  duckdb_connection connection,
  duckdb_arrow_options *out_arrow_options
);

参数

connection：连接。

`duckdb_client_context_get_connection_id`

返回客户端上下文的连接 ID。

语法

idx_t duckdb_client_context_get_connection_id(
  duckdb_client_context context
);

参数

context：客户端上下文。

void duckdb_destroy_client_context(
  duckdb_client_context *context
);

参数

context：要销毁的客户端上下文。

`duckdb_destroy_arrow_options`

销毁 Arrow 选项并释放其内存。

语法

void duckdb_destroy_arrow_options(
  duckdb_arrow_options *arrow_options
);

参数

arrow_options：要销毁的 Arrow 选项。

`duckdb_library_version`

返回所链接的 DuckDB 的版本，开发版本带有版本后缀

通常用于开发 C 扩展，必须返回此版本以进行兼容性检查。

语法

const char *duckdb_library_version(
  
);

`duckdb_get_table_names`

获取查询中（完全限定的）表名列表。

语法

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

参数

connection：要获取表名的连接。
query：要获取表名的查询。
qualified：如果设置为 true，则返回完全限定的表名（catalog.schema.table），否则仅返回（未转义的）表名。

返回值

一个类型为 VARCHAR[] 的 duckdb_value，包含查询的（完全限定的）表名。必须使用 duckdb_destroy_value 进行销毁。

关于此页面

行为准则商标使用指南

关于此页面

本文中