Выполнить контрольную точку базы данных

int sqlite3_wal_checkpoint_v2(
  sqlite3 *db,                    /* Database handle */
  const char *zDb,                /* Name of attached database (or NULL) */
  int eMode,                      /* SQLITE_CHECKPOINT_* value */
  int *pnLog,                     /* OUT: Size of WAL log in frames */
  int *pnCkpt                     /* OUT: Total number of frames checkpointed */
);

Интерфейс sqlite3_wal_checkpoint_v2(D,X,M,L,C) выполняет операцию контрольной точки для базы данных X из подключения к базе данных D в режиме M. Сведения о состоянии записываются в целые числа, на которые указывают L и C. Параметр M должен иметь допустимое значение режима контрольной точки:

SQLITE_CHECKPOINT_PASSIVE

Выполняет контрольную точку для максимально возможного числа кадров, не дожидаясь завершения работы читателей или писателей базы данных, а затем синхронизирует файл базы данных, если все кадры в журнале были обработаны. В режиме SQLITE_CHECKPOINT_PASSIVE обратный вызов обработчика занятости никогда не вызывается. С другой стороны, пассивный режим может оставить контрольную точку незавершённой, если одновременно работают читатели или писатели.

SQLITE_CHECKPOINT_FULL

Этот режим блокирует выполнение (вызывает обратный вызов обработчика занятости), пока не останется ни одного писателя базы данных и все читатели не будут читать из последнего снимка базы данных. Затем он обрабатывает все кадры в файле журнала и синхронизирует файл базы данных. Пока этот режим ожидает выполнения, он блокирует новых писателей базы данных, но новые читатели базы данных могут продолжать работу без ограничений.

SQLITE_CHECKPOINT_RESTART

Этот режим работает так же, как SQLITE_CHECKPOINT_FULL, с тем дополнением, что после обработки файла журнала он блокирует выполнение (вызывает обратный вызов обработчика занятости), пока все читатели не начнут читать только из файла базы данных. Это гарантирует, что следующий писатель начнёт журнал с самого начала. Как и SQLITE_CHECKPOINT_FULL, этот режим блокирует попытки новых писателей базы данных, пока ожидает выполнения, но не мешает читателям.

SQLITE_CHECKPOINT_TRUNCATE

Этот режим работает так же, как SQLITE_CHECKPOINT_RESTART, с тем дополнением, что перед успешным возвратом он также усекает файл журнала до нулевого размера.

SQLITE_CHECKPOINT_NOOP

В этом режиме всегда обрабатывается ноль кадров. Единственная причина вызвать контрольную точку NOOP — получить значения, возвращаемые sqlite3_wal_checkpoint_v2(), через выходные параметры *pnLog и *pnCkpt.

Если pnLog не равен NULL, то *pnLog устанавливается в общее число кадров в файле журнала или в -1, если контрольную точку не удалось выполнить из-за ошибки или потому, что база данных не находится в режиме WAL. Если pnCkpt не равен NULL, то *pnCkpt устанавливается в общее число обработанных кадров в файле журнала (включая кадры, обработанные до вызова функции) или в -1, если контрольную точку не удалось выполнить из-за ошибки или потому, что база данных не находится в режиме WAL. Обратите внимание: после успешного завершения SQLITE_CHECKPOINT_TRUNCATE файл журнала будет усечён до нулевого размера, поэтому значения *pnLog и *pnCkpt будут равны нулю.

Все вызовы получают исключительную блокировку «checkpoint» на файле базы данных. Если в это же время другой процесс выполняет операцию контрольной точки, получить блокировку невозможно, и возвращается SQLITE_BUSY. Даже если настроен обработчик занятости, в этом случае он не вызывается.

Режимы SQLITE_CHECKPOINT_FULL, RESTART и TRUNCATE также получают исключительную блокировку «writer» на файле базы данных. Если блокировку записи невозможно получить немедленно и настроен обработчик занятости, он вызывается, а попытки получить блокировку записи повторяются до тех пор, пока обработчик занятости не вернёт 0 или блокировка не будет успешно получена. Обработчик занятости также вызывается во время ожидания читателей базы данных, как описано выше. Если обработчик занятости возвращает 0 до получения блокировки записи или во время ожидания читателей базы данных, операция контрольной точки с этого момента выполняется так же, как SQLITE_CHECKPOINT_PASSIVE, — обрабатывается максимально возможное число кадров без дальнейшей блокировки. В этом случае возвращается SQLITE_BUSY.

Если параметр zDb равен NULL или указывает на строку нулевой длины, указанная операция выполняется для всех WAL-баз данных, подключённых к подключению к базе данных db. В этом случае значения, записанные в выходные параметры *pnLog и *pnCkpt, не определены. Если при обработке одной или нескольких подключённых WAL-баз данных возникает ошибка SQLITE_BUSY, операция всё равно выполняется для остальных подключённых баз данных, а в конце возвращается SQLITE_BUSY. Если при обработке подключённой базы данных возникает любая другая ошибка, обработка прекращается и код ошибки немедленно возвращается вызывающей стороне. Если при обработке подключённых баз данных ошибок не возникает (ни SQLITE_BUSY, ни других), возвращается SQLITE_OK.

Если zDb — имя подключённой базы данных, которая не находится в режиме WAL, возвращается SQLITE_OK, а значения *pnLog и *pnCkpt устанавливаются в -1. Если zDb не равен NULL (или не является строкой нулевой длины) и не совпадает с именем ни одной подключённой базы данных, вызывающей стороне возвращается SQLITE_ERROR.

Если интерфейс sqlite3_wal_checkpoint_v2() не возвращает SQLITE_MISUSE, он устанавливает сведения об ошибке, которые можно получить с помощью sqlite3_errcode() и sqlite3_errmsg().

Команду PRAGMA wal_checkpoint можно использовать для вызова этого интерфейса из SQL.

См. также списки объектов, констант и функций.