Запуск и завершение работы

Для использования DuckDB необходимо сначала инициализировать обработчик duckdb_database с помощью duckdb_open(). duckdb_open() принимает в качестве параметра файл базы данных для чтения и записи. Специальное значение NULL (nullptr) может использоваться для создания базы данных в памяти. Обратите внимание, что для базы данных в памяти данные не сохраняются на диск (т.е. все данные теряются при выходе из процесса).

С помощью обработчика duckdb_database можно создать одну или несколько duckdb_connection с помощью duckdb_connect(). Хотя отдельные подключения защищены от одновременного доступа из нескольких потоков, они будут блокироваться во время запросов. Поэтому рекомендуется, чтобы каждый поток использовал собственное подключение для достижения наилучшей параллельной производительности.

Все 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_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);
const char *duckdb_library_version();

`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.

Значение возврата

DuckDBSuccess в случае успеха или DuckDBError в случае неудачи.

`duckdb_close`

Закрывает указанную базу данных и освобождает всю память, выделенную для этой базы данных. Это необходимо вызывать после завершения работы с любой базой данных, созданной с помощью duckdb_open или duckdb_open_ext. Обратите внимание, что отсутствие вызова duckdb_close (например, при аварийном завершении программы) не приведёт к повреждению данных. Тем не менее, рекомендуется всегда корректно закрывать объект базы данных после завершения работы с ним.

Синтаксис

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: Объект результирующего подключения.

Значение возврата

DuckDBSuccess в случае успеха или DuckDBError в случае неудачи.

`duckdb_interrupt`

Прервать запуск запроса

Синтаксис

void duckdb_interrupt(
  duckdb_connection connection
);

Параметры

connection: Подключение, которое нужно прервать

`duckdb_query_progress`

Получить ход выполнения запроса

Синтаксис

duckdb_query_progress_type duckdb_query_progress(
  duckdb_connection connection
);

Параметры

connection: Рабочее подключение

Значение возврата

-1, если нет прогресса, или процент выполнения.

`duckdb_disconnect`

Закрывает указанное подключение и освобождает всю память, выделенную для этого подключения.

Синтаксис

void duckdb_disconnect(
  duckdb_connection *connection
);

Параметры

connection: Подключение для закрытия.

`duckdb_library_version`

Возвращает версию связанной библиотеки DuckDB с постфиксом версии для версий разработки.

Обычно используется при разработке C-расширений, которые должны возвращать это значение для проверки совместимости.

Синтаксис

const char *duckdb_library_version(
  
);