DuckDB C API 설정

DuckDB C API 설정 (Configuration)

DuckDB를 C API로 쓸 때 데이터베이스의 동작 방식을 여러 설정 옵션으로 조절할 수 있어요. 다행히도 같은 설정을 나중에 PRAGMA 문으로도 바꿀 수 있으니, 기억해 두면 두 곳 어디서든 편하게 다룰 수 있답니다. 설정 객체(configulation object)를 만들어 값들을 채운 다음 duckdb_open_ext에 넘겨주는 방식으로 사용해요.

출처: 문서

본문

Example

duckdb_database db;
duckdb_config config;

// create the configuration object
if (duckdb_create_config(&config) == DuckDBError) {
    // handle error
}
// set some configuration options
duckdb_set_config(config, "access_mode", "READ_WRITE"); // or READ_ONLY
duckdb_set_config(config, "threads", "8");
duckdb_set_config(config, "max_memory", "8GB");
duckdb_set_config(config, "default_order", "DESC");

// open the database using the configuration
if (duckdb_open_ext(NULL, &db, config, NULL) == DuckDBError) {
    // handle error
}
// cleanup the configuration object
duckdb_destroy_config(&config);

// run queries...

// cleanup
duckdb_close(&db);

API Reference Overview

`duckdb_create_config`

duckdb_open_ext를 통해 DuckDB 인스턴스에 시작 옵션을 제공할 수 있는 빈 설정 객체를 초기화해요. 생성한 duckdb_config는 반드시 duckdb_destroy_config로 파괴해야 해요.

malloc 실패가 없는 한 이 호출은 항상 성공해요. 참고로 함수가 DuckDBError를 반환하더라도 결과 config에는 항상 duckdb_destroy_config를 호출해야 하니 꼭 기억해 두세요.

Syntax

duckdb_state duckdb_create_config(
  duckdb_config *out_config
);

Parameters

out_config: 결과 설정(configuration) 객체.

Return Value

성공 시 DuckDBSuccess, 실패 시 DuckDBError.

`duckdb_config_count`

duckdb_get_config_flag와 함께 사용할 수 있는 전체 설정 옵션의 개수를 반환해요.

내부적으로 모든 옵션을 순회하므로 루프 안에서 호출하지 않는 게 좋아요.

Return Value

사용 가능한 설정 옵션의 개수.

Syntax

size_t duckdb_config_count(
  
);

`duckdb_get_config_flag`

특정 설정 옵션의 사람이 읽을 수 있는 이름과 설명을 가져와요. 예를 들어 설정 옵션을 화면에 표시할 때 사용할 수 있죠. index가 범위를 벗어나면(>= duckdb_config_count) 실패해요.

결과로 받은 이름이나 설명은 절대 free하면 안 돼요.

Syntax

duckdb_state duckdb_get_config_flag(
  size_t index,
  const char **out_name,
  const char **out_description
);

Parameters

index: 설정 옵션의 인덱스 (0과 duckdb_config_count 사이).
out_name: 설정 플래그의 이름.
out_description: 설정 플래그의 설명.

Return Value

성공 시 DuckDBSuccess, 실패 시 DuckDBError.

`duckdb_set_config`

지정된 설정 객체에 옵션을 설정해요. 설정 옵션은 이름으로 지정되며, 옵션 목록을 얻으려면 duckdb_get_config_flag를 보면 돼요.

소스 코드에서 설정 옵션은 config.cpp에 정의되어 있어요.

이름이 유효하지 않거나 옵션에 제공한 값이 잘못되면 실패할 수 있어요.

Syntax

duckdb_state duckdb_set_config(
  duckdb_config config,
  const char *name,
  const char *option
);

Parameters

config: 옵션을 설정할 설정 객체.
name: 설정할 설정 플래그의 이름.
option: 설정 플래그에 지정할 값.

Return Value

성공 시 DuckDBSuccess, 실패 시 DuckDBError.

`duckdb_destroy_config`

지정된 설정 객체를 파괴하고 객체에 할당된 모든 메모리를 해제해요.

Syntax

void duckdb_destroy_config(
  duckdb_config *config
);

Parameters

config: 파괴할 설정 객체.

DuckDB C API 설정