> ## Documentation Index
> Fetch the complete documentation index at: https://cockroachlabs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# CREATE SCHEDULE FOR BACKUP

export const InternalLink = ({version, path = "", children, ...props}) => {
  let detectedVersion = version || "stable";
  if (typeof window !== 'undefined' && !version) {
    const match = window.location.pathname.match(/\/docs\/([^/]+)/);
    if (match) {
      detectedVersion = match[1];
    }
  }
  const normalizedPath = path.startsWith("/") ? path.slice(1) : path;
  return <a href={`/docs/${detectedVersion}/${normalizedPath}`} {...props}>
      {children}
    </a>;
};

The `CREATE SCHEDULE FOR BACKUP` <InternalLink path="sql-statements">statement</InternalLink> creates a schedule for periodic <InternalLink path="backup">backups</InternalLink>.

For more information about creating, managing, monitoring, and restoring from a scheduled backup, see <InternalLink path="manage-a-backup-schedule">Manage a Backup Schedule</InternalLink>.

## Required privileges

<Note>
  Starting in v22.2, CockroachDB introduces a new <InternalLink path="security-reference/authorization#supported-privileges">system-level privilege model</InternalLink> that provides finer control over a user's privilege to work with the database, including taking backups.

  There is continued support for the [legacy privilege model](#required-privileges-using-the-legacy-privilege-model) for backups in v22.2, however it **will be removed** in a future release of CockroachDB. We recommend implementing the new privilege model that follows in this section for all new and existing backups.
</Note>

You can <InternalLink path="grant#grant-privileges-on-specific-tables-in-a-database">grant</InternalLink> the `BACKUP` privilege to a user or role depending on the type of backup:

| Backup   | Privilege                                                                                                                                                                                                                                    |
| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Cluster  | Grant a user the `BACKUP`<InternalLink path="security-reference/authorization#supported-privileges">system-level privilege</InternalLink>. For example, `GRANT SYSTEM BACKUP TO user;`.                                                      |
| Database | Grant a user the `BACKUP` privilege on the target database. For example, `GRANT BACKUP ON DATABASE test\_db TO user;`.                                                                                                                       |
| Table    | Grant a user the `BACKUP` privilege at the table level. This gives the user the privilege to back up the schema and all user-defined types that are associated with the table. For example, `GRANT BACKUP ON TABLE test\_db.table TO user;`. |

The listed privileges do not cascade to objects lower in the schema tree. For example, if you are granted database-level `BACKUP` privileges, this does not give you the privilege to back up a table. If you need the `BACKUP` privilege on a database to apply to all newly created tables in that database, use <InternalLink path="security-reference/authorization#default-privileges">`DEFAULT PRIVILEGES`</InternalLink>. You can add `BACKUP` to the user or role's default privileges with <InternalLink path="alter-default-privileges#grant-default-privileges-to-a-specific-role">`ALTER DEFAULT PRIVILEGES`</InternalLink>.

<Note>
  You can grant the `BACKUP` privilege to a user or role **without** the `SELECT` privilege on a table. As a result, these users will be able to take backups, but they will not be able to run a `SELECT` query on that data directly. However, these users could still read this data indirectly, by restoring it from any backups they produce.
</Note>

Members of the <InternalLink path="security-reference/authorization#admin-role">`admin` role</InternalLink> can run all three types of backups (cluster, database, and table) without the need to grant a specific `BACKUP` privilege. However, we recommend using the `BACKUP` privilege model to create users or roles and grant them `BACKUP` privileges as necessary for stronger access control.

### Privileges for managing a backup job

To manage a backup job with <InternalLink path="pause-job">`PAUSE JOB`</InternalLink>, <InternalLink path="resume-job">`RESUME JOB`</InternalLink>, or <InternalLink path="cancel-job">`CANCEL JOB`</InternalLink>, users must have at least one of the following:

* Be a member of the <InternalLink path="security-reference/authorization#admin-role">`admin` role</InternalLink>.
* The <InternalLink path="security-reference/authorization">`CONTROLJOB` role option</InternalLink>.

To view a backup job with <InternalLink path="show-jobs">`SHOW JOB`</InternalLink>, users must have at least one of the following:

* The <InternalLink path="security-reference/authorization#supported-privileges">`VIEWJOB` privilege</InternalLink>, which allows you to view all jobs (including `admin` -owned jobs).
* Be a member of the <InternalLink path="security-reference/authorization#admin-role">`admin` role</InternalLink>.
* The <InternalLink path="security-reference/authorization">`CONTROLJOB` role option</InternalLink>.

See <InternalLink path="grant">`GRANT`</InternalLink> for detail on granting privileges to a role or user.

## Required privileges using the legacy privilege model

The following details the legacy privilege model that CockroachDB supports in v22.2 and earlier. Support for this privilege model will be removed in a future release of CockroachDB:

* <InternalLink path="take-full-and-incremental-backups#full-backups">Full cluster backups</InternalLink> can only be run by members of the <InternalLink path="security-reference/authorization#admin-role">`admin` role</InternalLink>. By default, the `root` user belongs to the `admin` role.
* For all other backups, the user must have <InternalLink path="security-reference/authorization#managing-privileges">read access</InternalLink> on all objects being backed up. Database backups require `CONNECT` privileges, and table backups require `SELECT` privileges. Backups of user-defined schemas, or backups containing user-defined types, require `USAGE` privileges.

See the [Required privileges](#required-privileges) section for the updated privilege model.

## Destination privileges

You can grant a user the `EXTERNALIOIMPLICITACCESS` <InternalLink path="security-reference/authorization#supported-privileges">system-level privilege</InternalLink>.

Either the `EXTERNALIOIMPLICITACCESS` system-level privilege or the <InternalLink path="security-reference/authorization#admin-role">`admin`</InternalLink> role is required for the following scenarios:

* Interacting with a cloud storage resource using <InternalLink path="cloud-storage-authentication">`IMPLICIT` authentication</InternalLink>.
* Using a [custom endpoint](https://docs.aws.amazon.com/sdk-for-go/api/aws/endpoints) on S3.
* Using the <InternalLink path="cockroach-nodelocal-upload">`cockroach nodelocal upload`</InternalLink> command.

No special privilege is required for:

* Interacting with an Amazon S3 and Google Cloud Storage resource using `SPECIFIED` credentials. Azure Storage is always `SPECIFIED` by default.
* Using <InternalLink path="use-userfile-storage">Userfile</InternalLink> storage.

We recommend using <InternalLink path="use-cloud-storage">cloud storage</InternalLink>. You also need to ensure that the permissions at your storage destination are configured for the operation. See <InternalLink path="use-cloud-storage#storage-permissions">Storage Permissions</InternalLink> for a list of the necessary permissions that each bulk operation requires.

## Synopsis

```text theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
CREATE SCHEDULE [IF NOT EXISTS] <label>
FOR BACKUP [<targets] INTO <location>
[WITH <backup_options>[=<value] [, ...]]
RECURRING [crontab] [FULL BACKUP <crontab|ALWAYS]
[WITH SCHEDULE OPTIONS <schedule_option>[= <value>] [, ...] ]

Targets:
   Empty targets list: backup full cluster.
   TABLE

[, ...]
DATABASE  [, ...]
```

## Parameters

| Parameter                                | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `IF NOT EXISTS`                          | Use to specify that a scheduled backup should not be created if the [`label`](#label) already exists. Produces an error if the schedule label already exists, or if the `label` is not specified.                                                                                                                                                                                                                                                                                                                                             |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| <a id="label" />                         | `label`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | The name used to identify the backup schedule. This is optional and does not need to be unique. If not provided, the schedule will be assigned the name `BACKUP`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `targets`                                | The targets you want to back up: <ul><li>[cluster](#create-a-scheduled-backup-for-a-cluster) `[ ]`</li><li>[database](#create-a-scheduled-backup-for-a-database) `DATABASE <database_name> [, ...]`</li><li>[table](#create-a-scheduled-backup-for-a-table) `TABLE <table_pattern> [, ...]`</li></ul>                                                                                                                                                                                                                                         |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `table\_pattern`                         | The <InternalLink path="create-table">table(s)</InternalLink> or <InternalLink path="views">view(s)</InternalLink> you want to back up.                                                                                                                                                                                                                                                                                                                                                                                                       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `database\_name`                         | The name of the <InternalLink path="create-database">database(s)</InternalLink> you want to back up (i.e., create backups of all tables and views in the database).                                                                                                                                                                                                                                                                                                                                                                           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `location`                               | The URI where you want to store the backup. The backup files will be stored in year > month > day subdirectories. The location can be <InternalLink path="use-cloud-storage">cloud storage</InternalLink>, or `nodelocal`.  **Note:** If you want to schedule a backup using temporary credentials, we recommend that you use `implicit` authentication; otherwise, you'll need to drop and then recreate schedules each time you need to update the credentials.                                                                             |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `backup\_options`                        | Control the backup behavior with a comma-separated list of [options](#backup-options).                                                                                                                                                                                                                                                                                                                                                                                                                                                        |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `RECURRING crontab`                      | Specifies when the backup should be taken. A separate schedule may be created automatically to write full backups at a regular cadence, depending on the frequency of the incremental backups. You can likewise modify this separate schedule with <InternalLink path="alter-backup-schedule">`ALTER BACKUP SCHEDULE`</InternalLink>. The schedule is specified as a <InternalLink path="string">`STRING`</InternalLink> in [crontab format](https://wikipedia.org/wiki/Cron). All times in UTC.  Example: `'@daily'` (run daily at midnight) |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| <a id="full-backup-clause" />            | `FULL BACKUP crontab`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Specifies when to take a new full backup. The schedule is specified as a <InternalLink path="string">`STRING`</InternalLink> in [crontab format](https://wikipedia.org/wiki/Cron) or as `ALWAYS`. <br /><br />If `FULL BACKUP ALWAYS` is specified, then the backups triggered by the `RECURRING` clause will always be full backups. <br />`ALWAYS` is the only accepted value of `FULL BACKUP`.<br /><br />If the `FULL BACKUP` clause is omitted, CockroachDB will default to the following full backup schedule: <ul><li>`RECURRING` \<= 1 hour: Default to `FULL BACKUP '@daily'`</li><li>`RECURRING` > 1 hour and \<= 1 day: Default to `FULL BACKUP '@weekly'`</li><li>Otherwise: Default to `FULL BACKUP ALWAYS`</li></ul> |
| `WITH SCHEDULE OPTIONS schedule\_option` | Control the schedule behavior with a comma-separated list of [these options](#schedule-options).                                                                                                                                                                                                                                                                                                                                                                                                                                              |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |

<Note>
  For schedules that include both <InternalLink path="take-full-and-incremental-backups">full and incremental backups</InternalLink>, CockroachDB will create two schedules (one for each type). See [Incremental backup schedules](#incremental-backup-schedules) for more information.
</Note>

### Backup options

| Option                        | Value                                                  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |                                                                                                                                                                                                                                                                                                                             |
| ----------------------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `revision\_history`           | <InternalLink path="bool">`BOOL`</InternalLink> / None | Create a backup with full <InternalLink path="take-backups-with-revision-history-and-restore-from-a-point-in-time">revision history</InternalLink>, which records every change made to the cluster within the garbage collection period leading up to and including the given timestamp.  You can specify a backup with revision history without any value e.g., `WITH revision\_history`. Or, you can explicitly define `WITH revision\_history = 'true' / 'false'`. The `revision\_history` option defaults to `true` when used with <InternalLink path="backup">`BACKUP`</InternalLink> or `CREATE SCHEDULE FOR BACKUP`. A value is **required** when using `ALTER BACKUP SCHEDULE` to <InternalLink path="alter-backup-schedule">alter a backup schedule</InternalLink>. |                                                                                                                                                                                                                                                                                                                             |
| `encryption\_passphrase`      | <InternalLink path="string">`STRING`</InternalLink>    | The passphrase used to <InternalLink path="take-and-restore-encrypted-backups">encrypt the files</InternalLink> (`BACKUP` manifest and data files) that the `BACKUP` statement generates. This same passphrase is needed to decrypt the file when it is used to <InternalLink path="take-and-restore-encrypted-backups">restore</InternalLink> and to list the contents of the backup when using <InternalLink path="show-backup">`SHOW BACKUP`</InternalLink>. There is no practical limit on the length of the passphrase.                                                                                                                                                                                                                                                 |                                                                                                                                                                                                                                                                                                                             |
| `detached`                    | <InternalLink path="bool">`BOOL`</InternalLink> / None | **Note:** Backups running on a schedule have the `detached` option applied implicitly. Therefore, you cannot modify this option for scheduled backups.  When a backup runs in `detached` mode, it will execute asynchronously. The job ID will be returned after the backup <InternalLink path="backup-architecture#job-creation-phase">job creation</InternalLink> completes. Note that with `detached` specified, further job information and the job completion status will not be returned. For more on the differences between the returned job data, see the <InternalLink path="backup#run-a-backup-asynchronously">example</InternalLink>. To check on the job status, use the <InternalLink path="show-jobs">`SHOW JOBS`</InternalLink> statement.                  |                                                                                                                                                                                                                                                                                                                             |
| <a id="execution_locality" /> | `EXECUTION LOCALITY`                                   | Key-value pairs                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Restricts the execution of the backup to nodes that match the defined locality filter requirements. For example, `WITH EXECUTION LOCALITY = 'region=us-west-1a,cloud=aws'`.  Refer to <InternalLink path="take-locality-restricted-backups">Take Locality-restricted backups</InternalLink> for usage and reference detail. |
| `kms`                         | <InternalLink path="string">`STRING`</InternalLink>    | The URI of the cryptographic key stored in a key management service (KMS), or a comma-separated list of key URIs, used to <InternalLink path="take-and-restore-encrypted-backups#examples">take and restore encrypted backups</InternalLink>. Refer to <InternalLink path="take-and-restore-encrypted-backups#uri-formats">URI Formats</InternalLink>. The key or keys are used to encrypt the manifest and data files that the `BACKUP` statement generates and to decrypt them during a <InternalLink path="take-and-restore-encrypted-backups#examples">restore</InternalLink> operation, and to list the contents of the backup when using <InternalLink path="show-backup">`SHOW BACKUP`</InternalLink>.  AWS KMS, Google Cloud KMS, and Azure Key Vault are supported. |                                                                                                                                                                                                                                                                                                                             |
| `incremental\_location`       | <InternalLink path="string">`STRING`</InternalLink>    | Create an incremental backup in a different location than the default incremental backup location.  `WITH incremental\_location = 'explicit\_incrementals\_URI'`  See <InternalLink path="take-full-and-incremental-backups#incremental-backups-with-explicitly-specified-destinations">Incremental backups with explicitly specified destinations</InternalLink> for usage.  **Warning:** The `incremental\_location` parameter is deprecated as of v25.4 and will be removed in a future release. Until the parameter is removed, you can continue to work with existing backups that use a custom `incremental\_location`.                                                                                                                                                |                                                                                                                                                                                                                                                                                                                             |

### Schedule options

| Option                                         | Value                                                               | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ---------------------------------------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `first\_run`                                   | <InternalLink path="timestamp">`TIMESTAMPTZ`</InternalLink> / `now` | Execute the schedule at the specified time in the future. If not specified, the default behavior is to execute the schedule based on its next `RECURRING` time.                                                                                                                                                                                                                                                                                                  |
| `on\_execution\_failure`                       | `retry` / `reschedule` / `pause`                                    | If an error occurs during the backup execution, do the following:  - `retry`: Retry the backup right away.  - `reschedule`: Retry the backup by rescheduling it based on the `RECURRING` expression.  - `pause`: Pause the schedule. This requires manual intervention to <InternalLink path="resume-schedules">resume the schedule</InternalLink>.  **Default**: `reschedule`                                                                                   |
| `on\_previous\_running`                        | `start` / `skip` / `wait`                                           | If the previous backup started by the schedule is still running, do the following:  - `start`: Start the new backup anyway, even if the previous one is still running.  - `skip`: Skip the new backup and run the next backup based on the `RECURRING` expression.  - `wait`: Wait for the previous backup to complete.  **Default**: `wait`. The option affects backups started by the full backup schedule only. Incremental backups are always set to `wait`. |
| `ignore\_existing\_backups`                    | N/A                                                                 | If backups were already created in the <InternalLink path="use-cloud-storage">destination</InternalLink> that the new schedule references, this option must be passed to acknowledge that the new schedule may be backing up different objects.                                                                                                                                                                                                                  |
| `updates\_cluster\_last\_backup\_time\_metric` | N/A                                                                 | (<InternalLink path="security-reference/authorization#admin-role">`admin` privileges</InternalLink> required) When set during backup schedule creation, this option updates the <InternalLink path="backup-and-restore-monitoring#available-metrics">`schedules\_backup\_last\_completed\_time`</InternalLink> metric for the scheduled backup.                                                                                                                  |

## Considerations

* We recommend that you schedule your backups at a cadence that your cluster can keep up with; for example, if a previous backup is still running when it is time to start the next one, adjust the schedule so the backups do not end up falling behind or update the [`on_previous_running` option](#on-previous-running-option).
* To prevent scheduled backups from falling behind, first determine how long a single backup takes and use that as your starting point for the schedule's cadence.
* Ensure you are monitoring your backup schedule (e.g., <InternalLink path="monitor-cockroachdb-with-prometheus">Prometheus</InternalLink> ) and alerting metrics that will confirm that your backups are completing, but also that they're not running more concurrently than you expect.
* The `AS OF SYSTEM TIME` clause cannot be set on scheduled backups. Scheduled backups are started shortly after the scheduled time has passed by an internal polling mechanism and are automatically run with `AS OF SYSTEM TIME` set to the time at which the backup was scheduled to run.
* If you want to schedule a backup using temporary credentials, we recommend that you use `implicit` authentication; otherwise, you'll need to drop and then recreate schedules each time you need to update the credentials.

### Protected timestamps and scheduled backups

Scheduled backups ensure that the data to be backed up is protected from garbage collection until it has been successfully backed up. This active management of <InternalLink path="architecture/storage-layer#protected-timestamps">protected timestamps</InternalLink> means that you can run scheduled backups at a cadence independent from the <InternalLink path="configure-replication-zones">GC TTL</InternalLink> of the data. This is unlike non-scheduled backups that are tightly coupled to the GC TTL. See <InternalLink path="take-full-and-incremental-backups#garbage-collection-and-backups">Garbage collection and backups</InternalLink> for more detail.

The data being backed up will not be eligible for garbage collection until a successful backup completes. At this point, the schedule will release the existing protected timestamp record and write a new one to protect data for the next backup that is scheduled to run. It is important to consider that when a scheduled backup fails there will be an accumulation of data until the next successful backup. Resolving the backup failure or <InternalLink path="drop-schedules">dropping the backup schedule</InternalLink> will make the data eligible for garbage collection once again.

You can also use the `exclude_data_from_backup` option with a scheduled backup as a way to prevent protected timestamps from prolonging garbage collection on a table. See the example <InternalLink path="take-full-and-incremental-backups">Exclude a table's data from backups</InternalLink> for usage information.

We recommend monitoring your backup schedule to alert for failed backups:

* See the <InternalLink path="backup-and-restore-monitoring">Backup and Restore Monitoring</InternalLink> page for a general overview and list of metrics available for backup, scheduled backup, and restore jobs.
* See <InternalLink path="manage-a-backup-schedule#set-up-monitoring-for-the-backup-schedule">Set up monitoring for the backup schedule</InternalLink> for metrics and monitoring backup schedules specifically.

### Incremental backup schedules

The incremental backup schedule is created in a paused state, and is only un-paused on completion of the first, scheduled full backup. This ensures that the first incremental backup is only executed once it has a full backup to build a chain from. Thereafter, the incremental backups are scheduled to run at its specified cadence.

Incremental backups always append to the latest, complete full backup. An incremental backup can run concurrently with a full backup, but in such a situation it will continue to append to the previous full backup that has already completed.

An incremental backup will always wait for another incremental backup started by the same schedule to complete before running. This prevents incremental backups from backing up overlapping spans of time in the same backup chain. To enforce this, backup schedules created or altered using the [`on_previous_running` option](#on-previous-running-option) will have the full backup schedule created with the user specified option, but will **always default** the incremental backup schedule option to `on_previous_running = wait`.

## View and control backup schedules

Once a backup schedule is successfully created, you can do the following:

| Action              | SQL Statement                                                                     |
| ------------------- | --------------------------------------------------------------------------------- |
| View the schedule   | <InternalLink path="show-schedules">`SHOW SCHEDULES`</InternalLink>               |
| Pause the schedule  | <InternalLink path="pause-schedules">`PAUSE SCHEDULES`</InternalLink>             |
| Resume the schedule | <InternalLink path="resume-schedules">`RESUME SCHEDULES`</InternalLink>           |
| Drop the schedule   | <InternalLink path="drop-schedules">`DROP SCHEDULES`</InternalLink>               |
| Alter the schedule  | <InternalLink path="alter-backup-schedule">`ALTER BACKUP SCHEDULE`</InternalLink> |

## View and control a backup initiated by a schedule

After CockroachDB successfully initiates a scheduled backup, it registers the backup as a job. You can do the following with each individual backup job:

| Action                 | SQL Statement                                               |
| ---------------------- | ----------------------------------------------------------- |
| View the backup status | <InternalLink path="show-jobs">`SHOW JOBS`</InternalLink>   |
| Pause the backup       | <InternalLink path="pause-job">`PAUSE JOB`</InternalLink>   |
| Resume the backup      | <InternalLink path="resume-job">`RESUME JOB`</InternalLink> |
| Cancel the backup      | <InternalLink path="cancel-job">`CANCEL JOB`</InternalLink> |

You can also visit the <InternalLink path="ui-jobs-page">**Jobs** page</InternalLink> of the DB Console to view job details. The `BACKUP` statement will return when the backup is finished or if it encounters an error.

## Examples

### Create a schedule for full backups only

To schedule full backups of clusters, databases, or tables, use the `FULL BACKUP ALWAYS` clause, for example:

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
> CREATE SCHEDULE core_schedule_label
  FOR BACKUP INTO 's3://test/schedule-test-core?AWS_ACCESS_KEY_ID=x&AWS_SECRET_ACCESS_KEY=x'
    RECURRING '@daily'
    FULL BACKUP ALWAYS
    WITH SCHEDULE OPTIONS first_run = 'now';
```

```text theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
     schedule_id     |        name         | status |         first_run         | schedule |                                                                                       backup_stmt
---------------------+---------------------+--------+---------------------------+----------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
  588799238330220545 | core_schedule_label | ACTIVE | 2020-09-11 00:00:00+00:00 | @daily   | BACKUP INTO 's3://test/schedule-test-core?AWS_ACCESS_KEY_ID=x&AWS_SECRET_ACCESS_KEY=x' WITH detached
(1 row)
```

### Create a scheduled backup for a cluster

This example creates a schedule for a cluster backup with revision history that's taken every day at midnight:

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
> CREATE SCHEDULE schedule_label
  FOR BACKUP INTO 's3://test/backups/schedule_test?AWS_ACCESS_KEY_ID=x&AWS_SECRET_ACCESS_KEY=x'
    WITH revision_history
    RECURRING '@daily';
```

```text theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
     schedule_id     |     name       |                     status                     |            first_run             | schedule |                                                                               backup_stmt
---------------------+----------------+------------------------------------------------+----------------------------------+----------+---------------------------------------------------------------------------------------------------------------------------------------------------------
  588796190000218113 | schedule_label | PAUSED: Waiting for initial backup to complete | NULL                             | @daily   | BACKUP INTO LATEST IN 's3://test/schedule-test?AWS_ACCESS_KEY_ID=x&AWS_SECRET_ACCESS_KEY=x' WITH revision_history, detached
  588796190012702721 | schedule_label | ACTIVE                                         | 2020-09-10 16:52:17.280821+00:00 | @weekly  | BACKUP INTO 's3://test/schedule-test?AWS_ACCESS_KEY_ID=x&AWS_SECRET_ACCESS_KEY=x' WITH revision_history, detached
(2 rows)
```

Because the [`FULL BACKUP` clause](#full-backup-clause) is not included, CockroachDB also scheduled a full backup to run `@weekly`. This is the default cadence for incremental backups `RECURRING` > 1 hour but \<= 1 day.

### Create a scheduled backup for a database

This example creates a schedule for a backup of the database `movr` with revision history that's taken every day 1 minute past midnight (`00:00:01`):

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
> CREATE SCHEDULE schedule_database
  FOR BACKUP DATABASE movr INTO 's3://test/schedule-database?AWS_ACCESS_KEY_ID=x&AWS_SECRET_ACCESS_KEY=x'
    WITH revision_history
    RECURRING '1 0 * * *';
```

```text theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
     schedule_id     |       name        |                     status                     |            first_run             | schedule  |                                                                           backup_stmt
---------------------+-------------------+------------------------------------------------+----------------------------------+-----------+-----------------------------------------------------------------------------------------------------------------------------------------------------
  588819866656997377 | schedule_database | PAUSED: Waiting for initial backup to complete | NULL                             | 1 0 * * * | BACKUP DATABASE movr INTO LATEST IN 's3://test/schedule-database?AWS_ACCESS_KEY_ID=x&AWS_SECRET_ACCESS_KEY=x' WITH revision_history, detached
  588819866674233345 | schedule_database | ACTIVE                                         | 2020-09-10 18:52:42.823003+00:00 | @weekly   | BACKUP DATABASE movr INTO 's3://test/schedule-database?AWS_ACCESS_KEY_ID=x&AWS_SECRET_ACCESS_KEY=x' WITH revision_history, detached
(2 rows)
```

Because the [`FULL BACKUP` clause](#full-backup-clause) is not included, CockroachDB also scheduled a full backup to run `@weekly`. This is the default cadence for incremental backups `RECURRING` > 1 hour but \<= 1 day.

You will encounter an error if you run multiple <InternalLink path="take-full-and-incremental-backups#backup-collections">backup collections</InternalLink> to the same storage URI. Backup collections can contain multiple full and incremental backups, but each collection's URI must be unique. If you are using backup schedules, each schedule must have a unique URI.

### Create a scheduled backup for a table

This example creates a schedule for a backup of the table `movr.vehicles` with revision history that's taken every hour:

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
> CREATE SCHEDULE schedule_table
  FOR BACKUP TABLE movr.vehicles INTO 's3://test/schedule-table?AWS_ACCESS_KEY_ID=x&AWS_SECRET_ACCESS_KEY=x'
    WITH revision_history
    RECURRING '@hourly';
```

```text theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
     schedule_id     |       name     |                     status                     |            first_run             | schedule |                                                                             backup_stmt
---------------------+----------------+------------------------------------------------+----------------------------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------
  588820615348027393 | schedule_table | PAUSED: Waiting for initial backup to complete | NULL                             | @hourly  | BACKUP TABLE movr.vehicles INTO LATEST IN 's3://test/schedule-table?AWS_ACCESS_KEY_ID=x&AWS_SECRET_ACCESS_KEY=x' WITH revision_history, detached
  588820615382302721 | schedule_table | ACTIVE                                         | 2020-09-10 18:56:31.305782+00:00 | @daily   | BACKUP TABLE movr.vehicles INTO 's3://test/schedule-table?AWS_ACCESS_KEY_ID=x&AWS_SECRET_ACCESS_KEY=x' WITH revision_history, detached
(2 rows)
```

Because the [`FULL BACKUP` clause](#full-backup-clause) is not included, CockroachDB also scheduled a full backup to run `@daily`. This is the default cadence for incremental backups `RECURRING` \<= 1 hour.

### Create a scheduled backup with a scheduled first run

This example creates a schedule for a backup of the table `movr.vehicles` with revision history that's taken every hour, with its first run scheduled for `2020-09-15 00:00:00.00` (UTC):

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
> CREATE SCHEDULE scheduled_first_run
  FOR BACKUP TABLE movr.vehicles INTO 's3://test/schedule-table?AWS_ACCESS_KEY_ID=x&AWS_SECRET_ACCESS_KEY=x'
    WITH revision_history
    RECURRING '@hourly'
    WITH SCHEDULE OPTIONS first_run = '2020-09-15 00:00:00.00';
```

```text theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
     schedule_id     |        name         |                     status                     |         first_run         | schedule |                                                                                backup_stmt
---------------------+---------------------+------------------------------------------------+---------------------------+----------+----------------------------------------------------------------------------------------------------------------------------------------------------------
  589963390457741313 | scheduled_first_run | PAUSED: Waiting for initial backup to complete | NULL                      | @hourly  | BACKUP TABLE movr.vehicles INTO LATEST IN 's3://test/scheduled-first-run?AWS_ACCESS_KEY_ID=x&AWS_SECRET_ACCESS_KEY=x' WITH revision_history, detached
  589963390487363585 | scheduled_first_run | ACTIVE                                         | 2020-09-15 00:00:00+00:00 | @daily   | BACKUP TABLE movr.vehicles INTO 's3://test/scheduled-first-run?AWS_ACCESS_KEY_ID=x&AWS_SECRET_ACCESS_KEY=x' WITH revision_history, detached
(2 rows)
```

Because the [`FULL BACKUP` clause](#full-backup-clause) is not included, CockroachDB also scheduled a full backup to run `@daily`. This is the default cadence for incremental backups `RECURRING` \<= 1 hour.

### Create a scheduled backup with schedule options

This example creates a schedule for a cluster backup with the `on_previous_running` option:

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
> CREATE SCHEDULE schedule_option
  FOR BACKUP INTO 's3://test/backups/schedule_test?AWS_ACCESS_KEY_ID=x&AWS_SECRET_ACCESS_KEY=x'
    RECURRING '@daily'
    WITH SCHEDULE OPTIONS on_previous_running = 'start';
```

```text theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
     schedule_id     |      label      |                     status                     |          first_run           | schedule |                                                         backup_stmt
---------------------+-----------------+------------------------------------------------+------------------------------+----------+------------------------------------------------------------------------------------------------------------------------------
  866226603264475137 | schedule_option | PAUSED: Waiting for initial backup to complete | NULL                         | @daily   | BACKUP INTO LATEST IN 's3://test/backups/schedule_test?AWS_ACCESS_KEY_ID=x&AWS_SECRET_ACCESS_KEY=x' WITH detached
  866226603270635521 | schedule_option | ACTIVE                                         | 2023-05-18 14:56:20.39198+00 | @weekly  | BACKUP INTO 's3://test/backups/schedule_test?AWS_ACCESS_KEY_ID=x&AWS_SECRET_ACCESS_KEY=x' WITH detached
(2 rows)
```

The schedule starts a new backup, even if the previous one is still running because the user specified option for `on_previous_running = 'start'`. The [incremental backup remains `PAUSED`](#incremental-backup-schedules) until the initial full backup is complete.

Because the [`FULL BACKUP` clause](#full-backup-clause) is not included, CockroachDB also schedules a full backup to run `@daily`. This is the default cadence for incremental backups `RECURRING` \<= 1 hour.

### View scheduled backup details

When a <InternalLink path="create-schedule-for-backup">backup is created by a schedule</InternalLink>, it is stored within a collection of backups in the given location. To view details for a backup created by a schedule, you can use the following:

* `SHOW BACKUPS IN collectionURI` statement to <InternalLink path="show-backup#view-a-list-of-the-available-full-backup-subdirectories">view a list of the full backup's subdirectories</InternalLink>.
* `SHOW BACKUP FROM subdirectory IN collectionURI` statement to <InternalLink path="show-backup#view-a-list-of-the-full-and-incremental-backups-in-a-specific-full-backup-subdirectory">view a list of the full and incremental backups that are stored in a specific full backup's subdirectory</InternalLink>.
* Use the <InternalLink path="ui-schedules-page">Schedules page</InternalLink> in the <InternalLink path="ui-overview">DB Console</InternalLink> to view a list of created backup schedules and their individual details.

For more details, see <InternalLink path="show-backup">`SHOW BACKUP`</InternalLink>.

## See also

* <InternalLink path="manage-a-backup-schedule">Manage a Backup Schedule</InternalLink>
* <InternalLink path="backup">`BACKUP`</InternalLink>
* <InternalLink path="restore">`RESTORE`</InternalLink>
* <InternalLink path="show-backup">`SHOW BACKUP`</InternalLink>
* <InternalLink path="show-schedules">`SHOW SCHEDULES`</InternalLink>
* <InternalLink path="pause-schedules">`PAUSE SCHEDULES`</InternalLink>
* <InternalLink path="resume-schedules">`RESUME SCHEDULES`</InternalLink>
* <InternalLink path="drop-schedules">`DROP SCHEDULES`</InternalLink>
* <InternalLink path="alter-backup-schedule">`ALTER BACKUP SCHEDULE`</InternalLink>
* <InternalLink path="pause-job">`PAUSE JOB`</InternalLink>
* <InternalLink path="pause-job">`RESUME JOB`</InternalLink>
* <InternalLink path="cancel-job">`CANCEL JOB`</InternalLink>
* <InternalLink path="take-full-and-incremental-backups">Take Full and Incremental Backups</InternalLink>
* <InternalLink path="cockroach-sql">Use the Built-in SQL Client</InternalLink>
* <InternalLink path="cockroach-commands">`cockroach` Commands Overview</InternalLink>
