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

# Take Locality-restricted Backups

The `EXECUTION LOCALITY` option allows you to restrict the nodes that can execute a [backup](https://docs.cockroachlabs.com/docs/stable/backup.md#detached) job by using a [locality filter](https://docs.cockroachlabs.com/docs/stable/cockroach-start.md#locality) when you create the backup. This will pin the [coordination of the backup job](https://docs.cockroachlabs.com/docs/stable/backup-architecture.md#job-creation-phase) and the nodes that [process the row data](https://docs.cockroachlabs.com/docs/stable/backup-architecture.md#export-phase) to the defined locality filter.

Pass the `WITH EXECUTION LOCALITY` option for [`RESTORE`](https://docs.cockroachlabs.com/docs/stable/restore) to restrict execution of the job to nodes with matching localities.

Defining an execution locality for a backup job is useful in the following cases:

* When nodes in a cluster operate in different locality tiers, networking rules can restrict nodes from accessing a storage bucket. For an example, refer to [Access backup storage restricted by network rules](#access-backup-storage-restricted-by-network-rules).
* When a multi-region cluster is running heavy workloads and an aggressive backup schedule, designating a region as the "backup" locality may improve latency. For an example, refer to [Create a non-primary region for backup jobs](#create-a-non-primary-region-for-backup-jobs).

> [!NOTE]
>
> CockroachDB also supports *locality-aware backups*, which allow you to partition and store backup data in a way that is optimized for locality. In general, when you run a locality-aware backup, nodes write backup data to the [cloud storage](https://docs.cockroachlabs.com/docs/stable/use-cloud-storage.md) bucket that is closest to the node locality configured at [node startup](https://docs.cockroachlabs.com/docs/stable/cockroach-start.md). Refer to [Take and Restore Locality-aware Backups](https://docs.cockroachlabs.com/docs/stable/take-and-restore-locality-aware-backups.md) for more detail.

## Technical overview

For a technical overview of how a locality-restricted backup works, refer to [Job coordination using the `EXECUTION LOCALITY` option](https://docs.cockroachlabs.com/docs/stable/backup-architecture#job-coordination-using-the-execution-locality-option).

## Supported products

The feature described on this page is available in **CockroachDB Basic**, **CockroachDB Standard**, **CockroachDB Advanced**, and **CockroachDB self-hosted** clusters when you are running [self-managed backups](https://docs.cockroachlabs.com/docs/cockroachcloud/take-and-restore-self-managed-backups.md). For a full list of features, refer to [Backup and restore product support](https://docs.cockroachlabs.com/docs/stable/backup-and-restore-overview.md#backup-and-restore-support).

## Syntax

To specify the locality filter for the coordinating node, run `EXECUTION LOCALITY` with key-value pairs. The key-value pairs correspond to the [locality designations](https://docs.cockroachlabs.com/docs/stable/cockroach-start.md#locality) a node is configured to use when it starts.

You can bind any ordered list of locality key-value pairs, from most inclusive to least inclusive, to a node at startup. For example, a user with a multi-region and multi-cloud deployment may bind each node with `cloud=,region=` locality tiers. To back up to a specific `cloud,region`, add `cloud={cloud},region={region}` as the execution locality arguments:

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
BACKUP DATABASE {database} INTO 'external://backup_storage' WITH EXECUTION LOCALITY = 'cloud=gce,region=us-west1';
```

When you run a backup or restore that uses `EXECUTION LOCALITY`, consider the following:

* The backup or restore job will fail if no nodes match the locality filter.
* The backup or restore job may take slightly more time to start, because it must select the node that coordinates the backup or restore (the *coordinating node*). Refer to [Job coordination using the `EXECUTION LOCALITY` option](https://docs.cockroachlabs.com/docs/stable/backup-architecture#job-coordination-using-the-execution-locality-option).
* Even after a backup or restore job has been pinned to a locality filter, it may still read data from another locality if no replicas of the data are available in the locality specified by the backup job's locality filter.
* If the job is created on a node that does not match the locality filter, you will receive an error even when the **job creation was successful**. This error indicates that the job execution moved to another node. To avoid this error when creating a manual job (as opposed to a [scheduled job](https://docs.cockroachlabs.com/docs/stable/create-schedule-for-backup.md)), you can use the [`DETACHED`](https://docs.cockroachlabs.com/docs/stable/backup#detached) option with `EXECUTION LOCALITY`. Then, use the [`SHOW JOB WHEN COMPLETE`](https://docs.cockroachlabs.com/docs/stable/show-jobs#show-job-when-complete) statement to determine when the job has finished. For more details, refer to [Job coordination using the `EXECUTION LOCALITY` option](https://docs.cockroachlabs.com/docs/stable/backup-architecture#job-coordination-using-the-execution-locality-option).
* The backup job will send [ranges](https://docs.cockroachlabs.com/docs/stable/architecture/overview.md#range) to the cloud storage bucket matching the node's locality. However, a range's locality will not necessarily match the node's locality. The backup job will attempt to back up ranges through nodes matching that range's locality, however this is not always possible.

## Examples

This section outlines some example uses of the `EXECUTION LOCALITY` option.

### Access backup storage restricted by network rules

For security or other reasons, a cluster may be subject to network rules across regions or to other locality requirements. For example, if you have a requirement that only nodes within the same region as the backup [cloud storage](https://docs.cockroachlabs.com/docs/stable/use-cloud-storage.md) location can access the storage bucket, you can configure the backup job's `EXECUTION LOCALITY` to execute only on nodes with network access to the bucket.

The following diagram shows a CockroachDB cluster where each of the nodes can communicate with each other through a specific port, but any other network traffic between regions is blocked. Replicas in regions that do not match the cloud storage region (Node 2) cannot access the storage to [export backup data](https://docs.cockroachlabs.com/docs/stable/backup-architecture.md#export-phase).

Instead, Node 3's locality does match the backup job's `EXECUTION LOCALITY`. Replicas that match a backup job's locality designation and hold the backup job's row data will begin reading and exporting to cloud storage.

![Using execution locality when there is a network restriction between locality requirements](https://mintcdn.com/cockroachlabs/rKZiWWix6XHNRLL_/images/v26.3/network-restriction.png?fit=max\&auto=format\&n=rKZiWWix6XHNRLL_\&q=85\&s=dd6a67ae2b092dc3d783d09c6886f3cc)

To execute the backup only on nodes in the same region as the cloud storage location, you can specify [locality filters](https://docs.cockroachlabs.com/docs/stable/cockroach-start.md#locality) that a node must match to take part in the backup job's execution.

For example, you can pin the execution of the backup job to `us-west-1`:

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
BACKUP DATABASE {database} INTO 'external://backup_storage_uswest' WITH EXECUTION LOCALITY = 'region=us-west-1', DETACHED;
```

To restore the most recent locality-restricted backup:

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
RESTORE FROM LATEST IN 'external://backup_storage_uswest' WITH EXECUTION LOCALITY = 'region=us-west-1', DETACHED;
```

Refer to the [`BACKUP`](https://docs.cockroachlabs.com/docs/stable/backup#detached) and [`RESTORE`](https://docs.cockroachlabs.com/docs/stable/restore) pages for further detail on other parameters and options.

### Create a non-primary region for backup jobs

Sometimes the execution of backup jobs can consume considerable resources when running [frequent full and incremental backups simultaneously](https://docs.cockroachlabs.com/docs/stable/create-schedule-for-backup.md). One approach to minimize the impact of running background jobs on foreground application traffic is to restrict the execution of backup jobs to a designated subset of nodes that are not also serving application traffic.

This diagram shows a CockroachDB cluster in four regions. The node used to run the backup job was configured with [non-voting replicas](https://docs.cockroachlabs.com/docs/stable/architecture/replication-layer.md#non-voting-replicas) to provide low-latency reads. The node in this region will complete the backup job coordination and data export to cloud storage.

![Using execution locality to create a non-primary region for backup jobs](https://mintcdn.com/cockroachlabs/Vnu3Mn2DzHS7Vfry/images/common/background-work.png?fit=max\&auto=format\&n=Vnu3Mn2DzHS7Vfry\&q=85\&s=6f9e21991fcc029bc13944f458313bdb)

For details, refer to:

* The [`--locality`](https://docs.cockroachlabs.com/docs/stable/cockroach-start#locality) flag to specify the locality tiers that describe the location of a node.
* The `num_voters` and `voter_constraints` variables on the [Replication Controls](https://docs.cockroachlabs.com/docs/stable/configure-replication-zones.md#num_voters) page to configure non-voting replicas via zone configurations.

After configuring the nodes in a specific region to use non-voting replicas, you can create the backup job and define its locality requirement for the nodes:

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
BACKUP DATABASE {database} INTO 'external://backup_storage' WITH EXECUTION LOCALITY = 'region={region},dc={datacenter}', DETACHED;
```

## See also

* [Backup and Restore Overview](https://docs.cockroachlabs.com/docs/stable/backup-and-restore-overview.md)
* [Backup Architecture](https://docs.cockroachlabs.com/docs/stable/backup-architecture.md)
* [`BACKUP`](https://docs.cockroachlabs.com/docs/stable/backup#detached)
* [`RESTORE`](https://docs.cockroachlabs.com/docs/stable/restore)