启动与关闭 – 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);
idx_t duckdb_client_context_get_connection_id(duckdb_client_context context);
void duckdb_destroy_client_context(duckdb_client_context *context);
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_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_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 销毁。

关于此页面

本文中