Модуль проверки контрольных сумм VFS

1. Обзор

Расширение проверки контрольных сумм VFS — это VFS-обёртка, которая добавляет 8-байтовую контрольную сумму в конец каждой страницы в базе данных SQLite. Контрольная сумма добавляется при записи каждой страницы и проверяется при чтении каждой страницы. Контрольная сумма предназначена для обнаружения повреждения базы данных, вызванного случайными изменениями битов в устройстве массового хранения.

Для расширения проверки контрольных сумм VFS требуется версия SQLite 3.32.0 (2020-05-22) или более поздняя. Оно не будет работать с более ранними версиями SQLite.

2. Компиляция

Модуль проверки контрольных сумм VFS — это загружаемое расширение. Оно не включено в сборку. Его необходимо добавить в SQLite во время компиляции или во время выполнения. Исходный код модуля проверки контрольных сумм VFS находится в файле исходного кода ext/misc/cksumvfs.c в дереве исходных кодов SQLite SQLite.

Чтобы скомпилировать модуль проверки контрольных сумм VFS в загружаемое расширение во время выполнения, используйте команды, похожие на следующие:

• (linux) → gcc -fPIC -shared cksumvfs.c -o cksumvfs.so
• (mac) → clang -fPIC -dynamiclib cksumvfs.c -o cksumvfs.dylib
• (windows) → cl cksumvfs.c -link -dll -out:cksumvfs.dll

Конечно, вы можете добавить дополнительные параметры компилятора в соответствии с потребностями вашего проекта.

Чтобы статически связать это расширение с вашим продуктом, скомпилируйте его как любой другой модуль языка C, но добавьте параметр "-DSQLITE_CKSUMVFS_STATIC", чтобы модуль понял, что он статически связан, а не динамически.

3. Загрузка

Для загрузки этого расширения как динамической библиотеки сначала необходимо создать временное подключение к базе данных SQLite, которое будет использоваться в качестве аргумента для вызова API sqlite3_load_extension(). Затем вы вызываете API sqlite3_load_extension() и закрываете временное подключение к базе данных. Все последующие подключения к базе данных, которые будут открыты, будут включать это расширение. Например:

sqlite3 *db;
sqlite3_open(":memory:", &db);
sqlite3_load_extension(db, "./cksumvfs");
sqlite3_close(db);

Если это расширение скомпилировано с -DSQLITE_CKSUMVFS_STATIC и статически связано с приложением, инициализируйте его с помощью одного API-вызова следующим образом:

sqlite3_cksumvfs_init();

Cksumvfs — это VFS-обёртка. При загрузке «cksmvfs» становится новым стандартным VFS, и он использует предыдущий стандартный VFS как следующий VFS в стеке. Обычно это то, что вам нужно. Однако в сложных ситуациях, когда загружаются несколько VFS-обёрток, может быть важно убедиться, что cksumvfs загружается в правильном порядке, чтобы она последовательно встраивалась в стек стандартных VFS-обёрток в нужном порядке.

4. Использование

Открывайте подключения к базе данных с помощью интерфейсов sqlite3_open() или sqlite3_open_v2(), как обычно. Обычные файлы баз данных (без контрольных сумм) будут работать нормально. Базы данных с контрольными суммами вернут ошибку SQLITE_IOERR_DATA, если будет встречена страница с неверной контрольной суммой.

Проверка контрольных сумм работает только для баз данных, у которых значение зарезервированных байтов равно точно 8. Значение по умолчанию для зарезервированных байтов равно 0. Следовательно, вновь созданные файлы баз данных по умолчанию не будут включать контрольную сумму.

Чтобы создать базу данных, которая включает контрольную сумму, измените значение зарезервированных байтов на 8, выполнив код, подобный этому:

int n = 8;
sqlite3_file_control(db, 0, SQLITE_FCNTL_RESERVE_BYTES, &n);

Если вы сделаете это сразу после создания нового файла базы данных, прежде чем в файл будет записано что-либо ещё, то, возможно, этого будет достаточно. В противном случае после API-вызова выше нужно выполнить:

sqlite3_exec(db, "VACUUM", 0, 0, 0);

Выполнение VACUUM не повредит, даже если вам это не нужно. Если база данных находится в режиме WAL, необходимо закрыть и снова открыть все подключения к базе данных, прежде чем продолжить.

Из командной строки используйте команду ".filectrl reserve_bytes 8", за которой следует "VACUUM;".

Обратите внимание, что SQLite позволяет увеличивать количество зарезервированных байтов, но не уменьшать его. Поэтому, если у файла базы данных уже есть значение зарезервированных байтов больше 8, нет возможности активировать проверку контрольных сумм для этой базы данных, кроме как сбросить и восстановить файл базы данных. Также обратите внимание, что другие расширения также могут использовать зарезервированные байты. Проверка контрольных сумм будет несовместима с этими другими расширениями.

5. Проверка контрольных сумм

Если какая-либо контрольная сумма неверна, команда "PRAGMA quick_check" найдёт её. Чтобы проверить, действительно ли контрольные суммы включены и работают, используйте SQL, подобный следующему:

SELECT count(*), verify_checksum(data)
  FROM sqlite_dbpage
 GROUP BY 2;

Функция verify_checksum() может вернуть три значения: 1, 0 и NULL. 1 возвращается, если контрольная сумма верна. 0 возвращается, если контрольная сумма неверна. NULL возвращается, если страница нечитаема. Если проверка контрольных сумм включена, чтение завершится ошибкой, если контрольная сумма неверна, поэтому обычным результатом verify_checksum() для неверной контрольной суммы является NULL.

Если всё в порядке, запрос выше должен вернуть одну строку, где второй столбец равен 1. Любой другой результат указывает на ошибку контрольной суммы или отключение проверки контрольных сумм.

6. Управление проверкой контрольных сумм

Расширение cksumvfs реализует новое предложение PRAGMA, которое можно использовать для отключения, повторного включения или запроса состояния проверки контрольных сумм:

PRAGMA checksum_verification;          -- query status
PRAGMA checksum_verification=OFF;      -- disable verification
PRAGMA checksum_verification=ON;       -- re-enable verification

Предикат «checksum_verification» вернёт «1» (true) или «0» (false), если проверка контрольных сумм включена или выключена соответственно. В данном контексте «проверка» означает функцию, которая вызывает ошибки SQLITE_IOERR_DATA, если при чтении обнаруживается несовпадение контрольных сумм. Контрольные суммы всегда обновляются, пока значение зарезервированных байтов базы данных равно 8, независимо от настроек данного предиката. Проверка контрольных сумм может быть отключена (например), чтобы провести криминалистический анализ базы данных, которая ранее сообщила об ошибке контрольной суммы.

Предикат «checksum_verification» всегда вернёт «0», если у файла базы данных нет значения зарезервированных байтов 8. Предикат не вернёт никаких строк, если расширение cksumvfs не загружено.

Эта страница была изменена в последний раз 2022-01-08 05:02:57 UTC