Главная/Учебник/Справочник расширения sqlite
272 экспортируемых символа · полный нативный API SQLite (семейство интерфейсов v3)

Справочник расширения sqlite

Включается вариантом сборки build.bat sqlite: движок статически линкуется в хост, скрипты делают #include <sqlite3.h> (заголовок даёт VFS) — именно он крутит db/main.db из demo. Семантическая документация — по официальной SQLite; эта страница даёт групповой индекс и замечания в контексте XServer.

Замечания в контексте XServer

Безопасность при многих worker

demo открывает базу в режиме FULLMUTEX (флаг open_v2) — один дескриптор может обслуживать колбэки нескольких worker, но межпоточное переиспользование объектов операторов по-прежнему стоит исключить (цепочку prepare-…-finalize держите в одном потоке).

Способ открытия

demo использует sqlite3_open_v2(path, &db, SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE, NULL); пути относительны каталогу приложения (каталог db/ общий для поколений, гл. 05).

Зависимость от варианта

В варианте default этих символов нет — скрипт со ссылкой на sqlite3_* не скомпилируется (поведение проверено на практике в упражнении гл. 02).

Семейство соединений и выполнения

sqlite3_open_v2 / close / close_v2 соединение

Открытие (флаги управляют чтением-записью / созданием / потоковым режимом) и закрытие. Режим demo: READWRITE | CREATE + FULLMUTEX.

int sqlite3_open_v2(const char *filename, sqlite3 **ppDb, int flags, const char *zVfs); int sqlite3_close(sqlite3 *db);

sqlite3_exec выполнение

Одношаговое выполнение SQL без результатов (создание таблиц, PRAGMA, простая запись) — путь создания таблиц в demo.

int sqlite3_exec(sqlite3 *db, const char *sql, int (*callback)(void*,int,char**,char**), void *arg, char **errmsg);

sqlite3_errmsg / sqlite3_errcode диагностика

Текст и код ошибки — первая станция при разборе (demo печатает их при неудачном открытии).

Пять шагов оператора (хребет параметризованных запросов)

Паттерн пяти шагов (реальное применение в demo database.h / item.h)проверено на реальной машинеисточник: demo-single/modules
sqlite3_stmt* pStmt = NULL;
/* 1. prepare: текст SQL -> объект оператора (?-плейсхолдеры, инъекции исключены) */
sqlite3_prepare_v2(G_DB, sSQL, -1, &pStmt, NULL);
/* 2. bind: привязка параметров по номеру (текст — копия через SQLITE_TRANSIENT) */
sqlite3_bind_text(pStmt, 1, sName, -1, SQLITE_TRANSIENT);
sqlite3_bind_int64(pStmt, 2, iId);
/* 3. step: продвижение на строку (SELECT) или выполнение (запись) */
while ( sqlite3_step(pStmt) == SQLITE_ROW ) {
    /* 4. column: чтение значений по столбцам */
    int64 iId = sqlite3_column_int64(pStmt, 0);
    const unsigned char* sName = sqlite3_column_text(pStmt, 1);
}
/* 5. finalize: освободить оператор - каждому prepare нужен finalize */
sqlite3_finalize(pStmt);

Семейство: sqlite3_prepare_v2, sqlite3_bind_text/int64/int/double/null/blob, sqlite3_step, sqlite3_column_*, sqlite3_reset (переиспользование оператора), sqlite3_finalize. Номера привязок начинаются с 1, номера столбцов — с 0 — эта разница в единицу и есть самая частая ошибка.

Семейство транзакций и пакетов

  • BEGIN / COMMIT / ROLLBACK выполняются через exec или оператор; пакетная запись — обязательно группой (пакетная вставка bench-write в demo обёрнута транзакцией)
  • sqlite3_last_insert_rowid: получение автоинкрементного первичного ключа
  • sqlite3_changes: число затронутых строк
  • Семейство резервного копирования (sqlite3_backup_*) входит в экспортную поверхность — скрипты горячих бэкапов могут пользоваться напрямую

Обзор семейства утилит

Экспортировано 272 символа, покрывающих: базовый интерфейс v3, blob-IO, утилиты blob и текста, ошибки и состояние, статистику памяти (sqlite3_memory_used и др.), управление рантаймом (sqlite3_limit / busy_timeout), запрещённую область загрузки расширений и другое. Полный список — в /xs/sqlite3.h внутри VFS (существует только в варианте sqlite); семантику по каждой функции смотрите в официальной документации SQLite.

Полное изложение в учебнике (управление соединениями, переиспользование prepared statement, пакетная запись в транзакциях, решение о передаче дескрипторов при горячей перезагрузке) — в главе 32 и Практике 1.