시작과 종료
시작과 종료 (Startup & Shutdown)
DuckDB를 사용하려면 먼저 duckdb_open()으로 duckdb_database 핸들을 초기화해야 해요. duckdb_open()은 읽고 쓸 데이터베이스 파일을 파라미터로 받아요. 특별한 값인 NULL(nullptr)을 넘기면 인메모리 데이터베이스를 만들 수 있어요. 다만 인메모리 데이터베이스는 디스크에 아무것도 저장되지 않으니(즉 프로세스가 종료되면 모든 데이터가 사라져요) 이 점을 꼭 기억해 두세요.
duckdb_database 핸들에서 duckdb_connect()를 사용해 하나 또는 여러 개의 duckdb_connection을 만들 수 있어요. 각각의 커넥션은 스레드 안전하지만, 쿼리 중에는 잠기는(locked) 상태가 돼요. 그래서 최상의 병렬 성능을 얻으려면 각 스레드가 자신만의 커넥션을 사용하는 게 좋아요.
모든 duckdb_connection은 duckdb_disconnect()로 명시적으로 끊어야 하고, duckdb_database는 duckdb_close()로 명시적으로 닫아야 메모리와 파일 핸들 누수(leak)를 피할 수 있어요.
출처: 문서
본문
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 Overview
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로 반드시 파괴해야 해요.
Return Value
데이터베이스 인스턴스 캐시.
Syntax
duckdb_instance_cache duckdb_create_instance_cache(
);
duckdb_get_or_create_from_cache
인스턴스 캐시에 새 데이터베이스 인스턴스를 만들거나, 기존 데이터베이스 인스턴스를 가져와요. duckdb_close로 반드시 닫아야 해요.
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
);
Parameters
instance_cache: 데이터베이스를 만들거나 가져올 인스턴스 캐시.path: 디스크에 있는 데이터베이스 파일 경로.nullptr과:memory:둘 다 인메모리 데이터베이스를 열거나 가져와요.out_database: 결과로 나온 캐시된 데이터베이스.config: (선택) 데이터베이스를 만드는 데 사용하는 설정.out_error: 설정되어 있고 함수가DuckDBError를 반환하면 오류 메시지를 담아요. 오류 메시지는duckdb_free로 해제해야 해요.
Return Value
성공 시 DuckDBSuccess, 실패 시 DuckDBError.
duckdb_destroy_instance_cache
기존 데이터베이스 인스턴스 캐시를 파괴하고 그 메모리를 해제해요.
Syntax
void duckdb_destroy_instance_cache(
duckdb_instance_cache *instance_cache
);
Parameters
instance_cache: 파괴할 인스턴스 캐시.
duckdb_open
주어진 경로에 저장된 새 데이터베이스를 만들거나 기존 데이터베이스 파일을 열어요. 경로가 없으면 대신 새 인메모리 데이터베이스를 만들어요. 데이터베이스는 duckdb_close로 닫아야 해요.
Syntax
duckdb_state duckdb_open(
const char *path,
duckdb_database *out_database
);
Parameters
path: 디스크에 있는 데이터베이스 파일 경로.nullptr과:memory:둘 다 인메모리 데이터베이스를 열어요.out_database: 결과 데이터베이스 객체.
Return Value
성공 시 DuckDBSuccess, 실패 시 DuckDBError.
duckdb_open_ext
duckdb_open의 확장 버전이에요. 주어진 경로에 저장된 새 데이터베이스를 만들거나 기존 데이터베이스 파일을 열어요. 데이터베이스는 duckdb_close로 닫아야 해요.
Syntax
duckdb_state duckdb_open_ext(
const char *path,
duckdb_database *out_database,
duckdb_config config,
char **out_error
);
Parameters
path: 디스크에 있는 데이터베이스 파일 경로.nullptr과:memory:둘 다 인메모리 데이터베이스를 열어요.out_database: 결과 데이터베이스 객체.config: (선택) 데이터베이스를 시작할 때 사용하는 설정.out_error: 설정되어 있고 함수가DuckDBError를 반환하면 오류 메시지를 담아요. 오류 메시지는duckdb_free로 해제해야 해요.
Return Value
성공 시 DuckDBSuccess, 실패 시 DuckDBError.
duckdb_close
지정된 데이터베이스를 닫고 그 데이터베이스에 할당된 모든 메모리를 해제해요. duckdb_open이나 duckdb_open_ext로 할당한 데이터베이스를 다 쓴 뒤 호출하면 돼요. 참고로 duckdb_close를 호출하지 않아도(예: 프로그램 크래시) 데이터 손상으로 이어지진 않아요. 그래도 데이터베이스 객체를 다 쓴 뒤에는 항상 제대로 닫는 걸 권장해요.
Syntax
void duckdb_close(
duckdb_database *database
);
Parameters
database: 종료할 데이터베이스 객체.
duckdb_connect
데이터베이스에 연결을 엽니다. 데이터베이스를 쿼리하고 커넥션과 연결된 트랜잭션 상태를 저장하려면 커넥션이 필요해요. 만들어진 커넥션은 duckdb_disconnect로 닫아야 해요.
Syntax
duckdb_state duckdb_connect(
duckdb_database database,
duckdb_connection *out_connection
);
Parameters
database: 연결할 데이터베이스 파일.out_connection: 결과 연결 객체.
Return Value
성공 시 DuckDBSuccess, 실패 시 DuckDBError.
duckdb_interrupt
실행 중인 쿼리를 중단해요.
Syntax
void duckdb_interrupt(
duckdb_connection connection
);
Parameters
connection: 중단할 커넥션.
duckdb_query_progress
실행 중인 쿼리의 진행 상황을 가져와요.
Syntax
duckdb_query_progress_type duckdb_query_progress(
duckdb_connection connection
);
Parameters
connection: 작업 중인 커넥션.
Return Value
진행 상황이 없으면 -1, 아니면 진행률의 백분율.
duckdb_disconnect
지정된 커넥션을 닫고 그 커넥션에 할당된 모든 메모리를 해제해요.
Syntax
void duckdb_disconnect(
duckdb_connection *connection
);
Parameters
connection: 닫을 커넥션.
duckdb_connection_get_client_context
커넥션의 클라이언트 컨텍스트를 가져와요.
Syntax
void duckdb_connection_get_client_context(
duckdb_connection connection,
duckdb_client_context *out_context
);
Parameters
connection: 커넥션.out_context: 커넥션의 클라이언트 컨텍스트.duckdb_destroy_client_context로 반드시 파괴해야 해요.
duckdb_connection_get_arrow_options
커넥션의 arrow 옵션을 가져와요.
Syntax
void duckdb_connection_get_arrow_options(
duckdb_connection connection,
duckdb_arrow_options *out_arrow_options
);
Parameters
connection: 커넥션.
duckdb_client_context_get_connection_id
클라이언트 컨텍스트의 커넥션 ID를 반환해요.
Syntax
idx_t duckdb_client_context_get_connection_id(
duckdb_client_context context
);
Parameters
context: 클라이언트 컨텍스트.
Return Value
클라이언트 컨텍스트의 커넥션 ID.
duckdb_destroy_client_context
클라이언트 컨텍스트를 파괴하고 그 메모리를 해제해요.
Syntax
void duckdb_destroy_client_context(
duckdb_client_context *context
);
Parameters
context: 파괴할 클라이언트 컨텍스트.
duckdb_destroy_arrow_options
arrow 옵션을 파괴하고 그 메모리를 해제해요.
Syntax
void duckdb_destroy_arrow_options(
duckdb_arrow_options *arrow_options
);
Parameters
arrow_options: 파괴할 arrow 옵션.
duckdb_library_version
연결된 DuckDB의 버전을 반환해요(dev 버전은 버전 접미사 포함). 보통 호환성 검사를 위해 이 값을 반환해야 하는 C 확장을 개발할 때 사용해요.
Syntax
const char *duckdb_library_version(
);
duckdb_get_table_names
쿼리의 (정규화된) 테이블 이름 목록을 가져와요.
Syntax
duckdb_value duckdb_get_table_names(
duckdb_connection connection,
const char *query,
bool qualified
);
Parameters
connection: 테이블 이름을 가져올 커넥션.query: 테이블 이름을 가져올 쿼리.qualified:true면 정규화된 테이블 이름(catalog.schema.table)을, 아니면 (이스케이프하지 않은) 테이블 이름만 반환해요.
Return Value
쿼리의 (정규화된) 테이블 이름을 담은 VARCHAR[] 타입의 duckdb_value. duckdb_destroy_value로 반드시 파괴해야 해요.