diff --git a/cratedb-ee-docs/features/backups/index.md b/cratedb-ee-docs/features/backups/index.md new file mode 100644 index 0000000..2062715 --- /dev/null +++ b/cratedb-ee-docs/features/backups/index.md @@ -0,0 +1,61 @@ +(backups)= +# Backups + +```{include} intro.md +``` + +## Repositories + +Snapshots are stored in a snapshot repository, such as an Amazon S3 bucket, an Azure +Blob Storage container or a local file system. Add a repository in the "Repositories" +tab of the Backups page, with the settings your storage requires. The settings +of each repository type are described in +{ref}`CREATE REPOSITORY `. The +credentials are stored by CrateDB only, not by the Console. + +Removing a repository from the Console doesn't delete the snapshots stored in +it. + +## Backup schedules + +To add a schedule, fill in: + +- **Name**: a name to recognize the schedule. +- **Repository**: the snapshot repository to store the snapshots in. +- **Schedule**: when to take a snapshot, as a + [cron pattern](https://www.ibm.com/docs/en/db2-as-a-service?topic=task-unix-cron-format) + in UTC. For example, `0 * * * *` takes a snapshot every hour. +- **Scope**: the whole cluster, or a list of tables. +- **Retention**: how many snapshots to keep. See Retention below. + +You can pause, edit and delete a schedule at any time. Deleting a schedule +doesn't delete its snapshots. + +Snapshots taken by a schedule are named after the schedule's ID and the time +the run started, in UTC. + +```{include} snapshots.md +:heading-offset: 1 +``` + +To restore a snapshot, select it in the list. See Restore below. + +```{include} retention.md +:heading-offset: 1 +``` + +```{include} restore.md +:heading-offset: 1 +``` + +## Good to know + +- Each schedule runs one snapshot at a time. If a snapshot is still running + when the schedule is due again, that run is skipped. +- A snapshot keeps running in CrateDB even if the Console restarts. Its run + is picked up again at the schedule's next run. +- Several schedules can take snapshots at the same time, even in the same + repository. +- Up to 3 snapshots can run at the same time. When 3 are already running, the + next scheduled snapshot waits and starts as soon as one of them finishes. +- Pause your schedules before upgrading CrateDB, and resume them afterwards. diff --git a/cratedb-ee-docs/features/backups/intro.md b/cratedb-ee-docs/features/backups/intro.md new file mode 100644 index 0000000..f35c478 --- /dev/null +++ b/cratedb-ee-docs/features/backups/intro.md @@ -0,0 +1,6 @@ +Backups are snapshots of your cluster, taken on a schedule and stored in a +snapshot repository. A backup schedule takes a snapshot of your cluster, +at the times you set. It also deletes old snapshots, following its retention settings. + +Each time a schedule runs, it starts a snapshot and follows it until it ends. The +run shows the snapshot's result: success, partial or failed. diff --git a/cratedb-ee-docs/features/backups/restore.md b/cratedb-ee-docs/features/backups/restore.md new file mode 100644 index 0000000..06dbad4 --- /dev/null +++ b/cratedb-ee-docs/features/backups/restore.md @@ -0,0 +1,21 @@ +# Restore + +You can restore a snapshot that succeeded or partially succeeded. From a partial +snapshot, the incomplete parts are left out. + +- **Tables**: restore the tables you select. For a table that already exists, + you can skip it or restore it as a copy, under a new name. Existing tables are + never overwritten. +- **Whole cluster**: restore everything the snapshot contains. Only available + for snapshots of the whole cluster. + +:::{caution} +Restoring the whole cluster: +- fails if any table of the snapshot already exists. Drop those tables first, + or restore them one by one as copies; +- replaces users, privileges, views, user-defined functions and cluster + settings with the ones in the snapshot. Users created after the snapshot are + deleted. Make sure the user you log in with exists in the snapshot. +::: + +Backup schedules skip their runs while a restore is in progress. diff --git a/cratedb-ee-docs/features/backups/retention.md b/cratedb-ee-docs/features/backups/retention.md new file mode 100644 index 0000000..8c228fc --- /dev/null +++ b/cratedb-ee-docs/features/backups/retention.md @@ -0,0 +1,17 @@ +# Retention + +After each successful run, the schedule deletes the snapshots it no longer needs +to keep: + +- **Keep last**: the number of newest snapshots that are always kept. Required. +- **Keep all for (days)**: also keep every snapshot taken in the last days. + Optional. +- **Keep one per day for (days)**: also keep the first snapshot of each day. + Optional. + +For example, keep last `14`, keep all for `1` day and keep one per day for `14` +days keeps every snapshot of the last day, one snapshot per day for two weeks, +and never fewer than 14 snapshots. + +A schedule only deletes its own snapshots. Snapshots taken by hand or by other +schedules are never deleted. diff --git a/cratedb-ee-docs/features/backups/snapshots.md b/cratedb-ee-docs/features/backups/snapshots.md new file mode 100644 index 0000000..a6c3967 --- /dev/null +++ b/cratedb-ee-docs/features/backups/snapshots.md @@ -0,0 +1,12 @@ +# Snapshots + +The Snapshots screen lists your cluster's snapshots, with their state, start time, +duration and failures. + +A snapshot can be: + +- **In progress**: the snapshot is still running. +- **Success**: every table was saved. +- **Partial**: some parts couldn't be saved. The failures show which ones. The + snapshot can still be restored, without those parts. +- **Failed**: nothing usable was saved. The snapshot can't be restored. diff --git a/cratedb-ee-docs/features/index.rst b/cratedb-ee-docs/features/index.rst index 25163e7..8dd1c6e 100644 --- a/cratedb-ee-docs/features/index.rst +++ b/cratedb-ee-docs/features/index.rst @@ -15,3 +15,4 @@ In addition to that, the following you can also find the following features: console automation + backups/index