chore: checkpoint reference documentation (#53)

Co-authored-by: goodroot <[email protected]>

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/).

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

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.

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",
             {