> ## 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.

# ALTER 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 `ALTER BACKUP` statement allows for new KMS encryption keys to be applied to an existing chain of encrypted backups (<InternalLink path="take-full-and-incremental-backups#full-backups">full</InternalLink> and <InternalLink path="take-full-and-incremental-backups#incremental-backups">incremental</InternalLink>). Each `ALTER BACKUP` statement must include the new KMS encryption key with `NEW_KMS`, and use `WITH OLD_KMS` to refer to at least one of the KMS URIs that were originally used to encrypt the backup.

After an `ALTER BACKUP` statement successfully completes, subsequent <InternalLink path="backup">`BACKUP`</InternalLink>, <InternalLink path="restore">`RESTORE`</InternalLink>, and <InternalLink path="show-backup">`SHOW BACKUP`</InternalLink> statements can use any of the existing or new KMS URIs to decrypt the backup.

CockroachDB supports AWS, Azure, and Google Cloud KMS keys. For more detail on encrypted backups and restores, see <InternalLink path="take-and-restore-encrypted-backups">Take and Restore Encrypted Backups</InternalLink>.

## Synopsis

<img src="https://mintcdn.com/cockroachlabs/URZZsrJ2y-tKyo7i/images/sql-diagrams/v25.1/alter_backup.svg?fit=max&auto=format&n=URZZsrJ2y-tKyo7i&q=85&s=0d677b2eb5f922450ceb6729bf3aa7ad" alt="alter_backup syntax diagram" style={{maxWidth: "100%", overflowX: "auto"}} width="723" height="147" data-path="images/sql-diagrams/v25.1/alter_backup.svg" />

## Parameters

| Parameter       | Description                                                                                                 |
| --------------- | ----------------------------------------------------------------------------------------------------------- |
| `subdirectory`  | The subdirectory containing the target **full** backup at the given `collectionURI`.                        |
| `LATEST`        | The most recent backup at the given `collectionURI`.                                                        |
| `collectionURI` | The URI that holds the backup collection.                                                                   |
| `ADD NEW_KMS`   | Apply the new KMS encryption key to the target backup.                                                      |
| `WITH OLD_KMS`  | Reference one of the existing KMS URI(s) originally used to encrypt the backup.                             |
| `kmsURI`        | The <InternalLink path="take-and-restore-encrypted-backups#uri-formats">URI</InternalLink> for the KMS key. |

## Required privileges

* `ALTER BACKUP` 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.
* `ALTER BACKUP` requires full read and write permissions to the target cloud storage bucket.

The backup collection's URI does **not** require the <InternalLink path="security-reference/authorization#admin-role">`admin` role</InternalLink> when using `s3`, `azure`, or `gs` with <InternalLink path="cloud-storage-authentication">`specified`</InternalLink> credentials. The backup collection's URI **does** require the <InternalLink path="security-reference/authorization#admin-role">`admin` role</InternalLink> when using `s3`, `azure`, or `gs` with <InternalLink path="cloud-storage-authentication">`implicit`</InternalLink> credentials.

We recommend using <InternalLink path="use-cloud-storage">cloud storage</InternalLink>.

## Examples

`ALTER BACKUP` will apply the new encryption information to the entire chain of backups (<InternalLink path="take-full-and-incremental-backups#full-backups">full</InternalLink> and <InternalLink path="take-full-and-incremental-backups#incremental-backups">incremental</InternalLink>).

<Note>
  When running `ALTER BACKUP` with a subdirectory, the statement must point to a <InternalLink path="take-full-and-incremental-backups#full-backups">full backup</InternalLink> in the backup collection.
</Note>

See <InternalLink path="cloud-storage-authentication">Cloud Storage Authentication</InternalLink> for more detail on authenticating to your cloud storage bucket.

### Add an AWS KMS key to an encrypted backup

To add a new KMS key to the most recent backup:

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
ALTER BACKUP LATEST IN 's3://{BUCKET NAME}?AWS_ACCESS_KEY_ID={KEY ID}&AWS_SECRET_ACCESS_KEY={SECRET ACCESS KEY}'
    ADD NEW_KMS = 'aws:///{new-key}?AWS_ACCESS_KEY_ID={KEY ID}&AWS_SECRET_ACCESS_KEY={SECRET ACCESS KEY}&REGION={location}'
    WITH OLD_KMS = 'aws:///{old-key}?AWS_ACCESS_KEY_ID={KEY ID}&AWS_SECRET_ACCESS_KEY={SECRET ACCESS KEY}&REGION={location}';
```

To add a new KMS key to a specific backup, issue an `ALTER BACKUP` statement that points to the full backup:

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
ALTER BACKUP '2022/03/23-213101.37' IN 's3://{BUCKET NAME}?AWS_ACCESS_KEY_ID={KEY ID}&AWS_SECRET_ACCESS_KEY={SECRET ACCESS KEY}'
    ADD NEW_KMS = 'aws:///{new-key}?AWS_ACCESS_KEY_ID={KEY ID}&AWS_SECRET_ACCESS_KEY={SECRET ACCESS KEY}&REGION={location}'
    WITH OLD_KMS = 'aws:///{old-key}?AWS_ACCESS_KEY_ID={KEY ID}&AWS_SECRET_ACCESS_KEY={SECRET ACCESS KEY}&REGION={location}';
```

To list backup directories at a collection's URI, see <InternalLink path="show-backup">`SHOW BACKUP`</InternalLink>.

### Add an Azure KMS key to an encrypted backup

To add a new KMS key to the most recent backup:

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
ALTER BACKUP LATEST IN 'azure-blob://{container name}?AUTH=specified&AZURE_ACCOUNT_NAME={account name}&AZURE_CLIENT_ID={client ID}&AZURE_CLIENT_SECRET={client secret}&AZURE_TENANT_ID={tenant ID}'
    ADD NEW_KMS = 'azure-kms:///{new key}/{new key version}?AZURE_TENANT_ID={tenant ID}&AZURE_CLIENT_ID={client ID}&AZURE_CLIENT_SECRET={client secret}&AZURE_VAULT_NAME={key vault name}'
    WITH OLD_KMS = 'azure-kms:///{old key}/{old key version}?AZURE_TENANT_ID={tenant ID}&AZURE_CLIENT_ID={client ID}&AZURE_CLIENT_SECRET={client secret}&AZURE_VAULT_NAME={key vault name}';
```

To add a new KMS key to a specific backup, issue an `ALTER BACKUP` statement that points to the full backup:

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
ALTER BACKUP '2023/03/14-203808.29' IN 'azure-blob://{container name}?AUTH=specified&AZURE_ACCOUNT_NAME={account name}&AZURE_CLIENT_ID={client ID}&AZURE_CLIENT_SECRET={client secret}&AZURE_TENANT_ID={tenant ID}'
    ADD NEW_KMS = 'azure-kms:///{new key}/{new key version}?AZURE_TENANT_ID={tenant ID}&AZURE_CLIENT_ID={client ID}&AZURE_CLIENT_SECRET={client secret}&AZURE_VAULT_NAME={key vault name}'
    WITH OLD_KMS = 'azure-kms:///{old key}/{old key version}?AZURE_TENANT_ID={tenant ID}&AZURE_CLIENT_ID={client ID}&AZURE_CLIENT_SECRET={client secret}&AZURE_VAULT_NAME={key vault name}';
```

To list backup directories at a collection's URI, see <InternalLink path="show-backup">`SHOW BACKUP`</InternalLink>.

### Add a Google Cloud KMS key to an encrypted backup

To add a new KMS key to the most recent backup:

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
ALTER BACKUP LATEST IN 'gs://{BUCKET NAME}?AUTH=specified&CREDENTIALS={ENCODED KEY}'
    ADD NEW_KMS = 'gs:///projects/{project name}/locations/{location}/keyRings/{key ring name}/cryptoKeys/{new key}?AUTH=specified&CREDENTIALS={encoded key}'
    WITH OLD_KMS = 'gs:///projects/{project name}/locations/{location}/keyRings/{key ring name}/cryptoKeys/{old key}?AUTH=specified&CREDENTIALS={encoded key}';
```

To add a new KMS key to a specific backup, issue an `ALTER BACKUP` statement that points to the full backup:

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
ALTER BACKUP '2022/03/23-213101.37' IN 'gs://{BUCKET NAME}?AUTH=specified&CREDENTIALS={ENCODED KEY}'
    ADD NEW_KMS = 'gs:///projects/{project name}/locations/{location}/keyRings/{key ring name}/cryptoKeys/{new key}?AUTH=specified&CREDENTIALS={encoded key}'
    WITH OLD_KMS = 'gs:///projects/{project name}/locations/{location}/keyRings/{key ring name}/cryptoKeys/{old key}?AUTH=specified&CREDENTIALS={encoded key}';
```

To list backup directories at a collection's URI, see <InternalLink path="show-backup">`SHOW BACKUP`</InternalLink>.

## See also

* <InternalLink path="take-and-restore-encrypted-backups">Take and Restore Encrypted Backups</InternalLink>
* <InternalLink path="backup">`BACKUP`</InternalLink>
* <InternalLink path="restore">`RESTORE`</InternalLink>
* <InternalLink path="use-cloud-storage">Use Cloud Storage</InternalLink>