ALTER BACKUP

On this page

New in v22.1: The ALTER BACKUP statement allows for new KMS encryption keys to be applied to an existing chain of encrypted backups (full and incremental). 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 BACKUP, RESTORE, and SHOW BACKUP statements can use any of the existing or new KMS URIs to decrypt the backup.

CockroachDB supports AWS and Google Cloud KMS keys. For more detail on encrypted backups and restores, see Take and Restore Encrypted Backups.

Synopsis

Parameters

Required privileges

• ALTER BACKUP can only be run by members of the admin role. 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 admin role when using s3 or gs using SPECIFIED credentials. The backup collection's URI does require the admin role when using s3 or gs with IMPLICIT credentials.

We recommend using cloud storage for bulk operations.

Examples

ALTER BACKUP will apply the new encryption information to the entire chain of backups (full and incremental).

See Use Cloud Storage for Bulk Operations 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:

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:

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 SHOW BACKUP.

Add a Google Cloud KMS key to an encrypted backup

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

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:

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 SHOW BACKUP.

See also

• Take and Restore Encrypted Backups
• BACKUP
• RESTORE
• Use Cloud Storage for Bulk Operations

Was this helpful?