diff --git a/operations/backup.md b/operations/backup.md index 28e4408c..622eeee6 100644 --- a/operations/backup.md +++ b/operations/backup.md @@ -96,7 +96,8 @@ platforms: - [GCP](https://cloud.google.com/compute/docs/disks/create-snapshots) - working with persistent disk snapshots -Cloud snapshot-based systems usually break down their backup process into two steps: +Cloud snapshot-based systems usually break down their backup process into two +steps: 1. Take a snapshot 2. Back up the snapshot @@ -258,3 +259,8 @@ Other file systems are untested and while they may work, we do not officially support them. See the [filesystem compatibility](/docs/deployment/capacity-planning/#supported-filesystems) section for more information. + +## Further reading + +To learn more, see the +[`CHECKPOINT` SQL reference documentation](/docs/reference/sql/checkpoint/). diff --git a/reference/sql/checkpoint.md b/reference/sql/checkpoint.md new file mode 100644 index 00000000..5a64135a --- /dev/null +++ b/reference/sql/checkpoint.md @@ -0,0 +1,94 @@ +--- +title: CHECKPOINT keyword +sidebar_label: CHECKPOINT +description: CHECKPOINT SQL keyword reference documentation. +--- + +Checkpoint SQL toggles the database into and out of "checkpoint mode". In this +mode the databases file system can be safely backed up using external tools, +such as disk snapshots or copy utilities. + +_Looking for a detailed guide backup creation and restoration? Check out our +[Backup and Restore](/docs/operations/backup/) guide!_ + +:::caution + +QuestDB currently does not support creating checkpoints on Windows. + +If you are a Windows user and require backup functionality, please +[comment on this issue](https://github.com/questdb/questdb/issues/4811). + +::: + +## CHECKPOINT syntax + +![Flow chart showing the syntax of the CHECKPOINT keyword](/img/docs/diagrams/checkpoint.svg) + +## CHECKPOINT overview + +To enable online backups, data in QuestDB is mutated via either file append or +via copy-on-write. Checkpoint leverages these storage methods to achieve +reliable and consistent restorations from your database backups. + +### What happens during CHECKPOINT CREATE? + +When initiatied, `CHECKPOINT CREATE`: + +- Disables background jobs that housekeep stale files and data blocks +- Takes snapshot of table transactions across the whole database (all tables) +- Creates a new on-disk data structure that captures append offsets and versions + of files that represent data for the above transactions. Typically this data + is stored in the `/var/lib/questdb/db/.checkpoint` directory. + - **Do not alter contents of this directory manually**! +- `fsync` - synchronously flushes page cache and buffers to disk + +### What happens after a checkpoint has been created? + +Once a checkpoint is created, QuestDB continues taking in writes. However, it +will consume more disk space. How much more depends on the shape of the data +that is being written. Data that is written via the append method will yeild +almost no additional disk space consumption other that of the data itself. In +contrast, the copy-on-write method will make data copies, which are usually +copies of non-recent table partitions. This will lead to an increase in disk +space consumption. + +**It is strongly recommended that you minimize the time database is in +checkpoint mode and monitor the free disk space closely. The recommended way to +achive this is to utilize file system SNAPSHOTS as described in +[our backup and restore guide](/docs/operations/backup/).** + +Also note that QuestDB can only enter checkpoint mode once. After that period of +time, the next checkpoint operation must be to exit checkpoint mode. Attempts to +create a new checkpoint when once exists will fail with the appropriate message. + +When in checkpoint mode, you can safely access the file system to take your +snapshot. + +### What happens after my snapshot is complete? + +After your snapshot is complete, checkpoint mode must be exited via the +`CHECKPOINT RELEASE` SQL. Once executed, QuestDB will reinstate the usual +housekeeping and reclaim disk space. + +The database restore is preformed semi-automatically on the database startup. +This is done deliberately to avoid the restore procedure running accidentally on +the source database instance. The database will attempt a restore when empty an +file, typically `/var/lib/questdb/_restore` is present. + +The restore procedure will use `/var/lib/questdb/db/.checkpoint` to adjust the +database files and remove extra data copies. After the restore is successful the +database is avaialble as normal with no extra intervantion required. + +## CHECKPOINT examples + +To enter checkpoint mode: + +```sql +CHECKPOINT CREATE +``` + +To exit checkpoint mode: + +```sql +CHECKPOINT RELEASE +``` diff --git a/reference/sql/snapshot.md b/reference/sql/snapshot.md index 5cf2700b..16b0b10f 100644 --- a/reference/sql/snapshot.md +++ b/reference/sql/snapshot.md @@ -4,7 +4,8 @@ sidebar_label: SNAPSHOT description: SNAPSHOT SQL keyword reference documentation. --- -Prepare the database for a full backup or a filesystem (disk) snapshot. +This is a *deprecated* syntax to prepare the database for a full backup or a filesystem (disk) snapshot. +`SNAPSHOT` SQL syntax has been superceded by [`CHECKPOINT` SQL syntax](/docs/reference/sql/checkpoint/) _For a detailed guide backup creation and restoration? Check out our [Backup and Restore](/docs/operations/backup/) guide!_ @@ -13,95 +14,3 @@ _For a detailed guide backup creation and restoration? Check out our ![Flow chart showing the syntax of the SNAPSHOT keyword](/img/docs/diagrams/snapshot.svg) -:::caution - -QuestDB currently does not support creating snapshots on Windows. - -If you are a Windows user and require backup functionality, please -[comment on this issue](https://github.com/questdb/questdb/issues/4811). - -::: - -## Snapshot process - -Database snapshots may be used in combination with filesystem snapshots or -together with file copying for a full data backup. Collecting a snapshot -involves the following steps: - -1. Run `SNAPSHOT PREPARE` statement to acquire reader locks for all database - tables, create table metadata file copies in the `snapshot` directory, and - flush the committed data to disk. -2. Start a filesystem snapshot or copy the - [root directory](/docs/concept/root-directory-structure/) to the backup - location on the disk. learn how to create a filesystem snapshot on the most - common cloud providers. -3. Run `SNAPSHOT COMPLETE` statement to release the reader locks and delete the - metadata file copies. - -### SNAPSHOT PREPARE - -To support precise usage, we'll unpack `SNAPSHOT PREPARE`. - -To answer: - -- What is the effect of `SNAPSHOT PERPARE`? -- Will QuestDB will write during `SNAPSHOT PREPAPRE` processing? -- Does QuestDB write to WAL during `SNAPSHOT PREPARE`, for processing at - `SNAPSHOT COMPLETE`? - -Using `SNAPSHOT PREPARE` triggers an fsync to sync outstanding writes to the -disk. It will then temporarily disable the cleanup process related to merging -out-of-order (O3) data. Then, the latest synced transaction will be used as the -checkpoint. After which, one can proceed with step 2 above, which is to take an -EBS snapshot of the files. Calling `SNAPSHOT COMPLETE` then resumes the usual -process, which cleans up old file versions that are no longer needed. - -In short: You can still write to the database during `SNAPSHOT PREPARE`. -However, old files versions are only purged after `SNAPSHOT COMPLETE`. During -`SNAPSHOT PREPARE` O3 writes are much more expensive on disk space while append -writes remain inexpensive. - -## Snapshot recovery - -In case of a full backup, you should also delete the old root directory and copy -the files from your backup to the same location or, alternatively, you can point -the database at the new root directory. - -When the database starts, it checks for the presence of a file named `_restore` -in the root directory. If the file is present, the database runs a snapshot -recovery procedure restoring the metadata files from the snapshot. - -When this happens, you should see the following in the server logs: - -``` -2022-03-07T08:24:12.348004Z I i.q.g.DatabaseSnapshotAgent starting snapshot recovery [trigger=file] -[...] -2022-03-07T08:24:12.349922Z I i.q.g.DatabaseSnapshotAgent snapshot recovery finished [metaFilesCount=1, txnFilesCount=1, cvFilesCount=1] -``` - -Snapshot recovery can be disabled using the `cairo.snapshot.recovery.enabled` -configuration key: - -```shell title="server.conf" -cairo.snapshot.recovery.enabled=false -``` - -## Examples - -```questdb-sql -SNAPSHOT PREPARE; --- Start a filesystem snapshot. -SNAPSHOT COMPLETE; -``` - -```questdb-sql -SNAPSHOT PREPARE; --- Copy the root directory: --- $ cp -r /root/dir/path /backup/dir/path -SNAPSHOT COMPLETE; -``` - -## Further reading - -- [Backup and Restore](/docs/operations/backup/) - Detailed guide on how to - create backups and restore them. diff --git a/sidebars.js b/sidebars.js index c3effda8..a6ecbaa6 100644 --- a/sidebars.js +++ b/sidebars.js @@ -176,6 +176,7 @@ module.exports = { "reference/sql/cancel-query", "reference/sql/case", "reference/sql/cast", + "reference/sql/checkpoint", "reference/sql/copy", "reference/sql/create-table", {