FORCE RESTORE (beta)

Forces the restoration of a specific backup even if that backup is incomplete.

Important: The DSE Backup and Restore Service is currently in beta and is intended to be used by users provisioning DSE via the DataStax Cass Operator in a Kubernetes cluster.
Forces the restoration of a specific backup even if that backup is incomplete. Requires a target keyspace or a list of target tables within that keyspace, and a backup store name. Custom backup store settings can be specified as can a new keyspace for restored data. Returns a UUID for the restore operation.
Attention: After a FORCE RESTORE, you must run a nodetool repair or schedule a manual nodesync on the node. See:

Synopsis

RESTORE targets
    FROM BACKUP backup_id
    FROM STORE store_name 
    [ WITH settings=settings ] 
    [ INTO keyspace_name_new ] ;
Table 1. Legend
Syntax conventions Description
UPPERCASE Literal keyword.
Lowercase Not literal.
Italics Variable value. Replace with a user-defined value.
[] Optional. Square brackets ( [] ) surround optional command arguments. Do not type the square brackets.
( ) Group. Parentheses ( ( ) ) identify a group to choose from. Do not type the parentheses.
| Or. A vertical bar ( | ) separates alternative elements. Type any one of the elements. Do not type the vertical bar.
... Repeatable. An ellipsis ( ... ) indicates that you can repeat the syntax element as often as required.
'Literal string' Single quotation ( ' ) marks must surround literal strings in CQL statements. Use single quotation marks to preserve upper case.
{ key : value } Map collection. Braces ( { } ) enclose map collections or key value pairs. A colon separates the key and the value.
<datatype1,datatype2> Set, list, map, or tuple. Angle brackets ( < > ) enclose data types in a set, list, map, or tuple. Separate the data types with a comma.
cql_statement; End CQL statement. A semicolon ( ; ) terminates all CQL statements.
[--] Separate the command line options from the command arguments with two hyphens ( -- ). This syntax is useful when arguments might be mistaken for command line options.
' <schema> ... </schema> ' Search CQL only: Single quotation marks ( ' ) surround an entire XML schema declaration.
@xml_entity='xml_entity_type' Search CQL only: Identify the entity and literal value to overwrite the XML element in the schema and solrConfig files.
targets

A full single keyspace or a list of tables within that keyspace. Tables are prefixed with the keyspace and multiple tables are separated by commas, for example, keyspace_1.my_table_1, keyspace_1.my_table_2.

store_name

Name of the backup store. Store names can use alphanumeric characters and underscores only. They are case insensitive.

settings
A key/value list of settings particular to the store class. For example, for an FSBlobStore class:
settings = {'path':'/path/to/data', 'retention_time':'1w'}

Common settings for all store classes

The following settings can be used with any store class.

Setting Description Type Required
transfer_rate_limit_mbs Maximum upload rate per node in MB per second. int false
retention_time Time duration for which a snapshot is retained. duration false
retention_number Number of snapshots retained. int false

The parameters retention_time and retention_number can be used individually or in combination. Setting either to 0 ignores the respective parameter.

Examples

Retain backup younger than one week:

'retention_time':'1w'
Retain a minimum of 3 full backup at any point in time:
'retention_number':3
Note: Any non-full backup with a status of INCOMPLETE or QUORUM that occurs between the full snapshots is retained as well.
Retain a mininum of 3 full backups even if older than one week:
'retention_time':'1w','retention_number':3 
Important: If, for example, there happen to be four full backups within the retention_time window, all four are retained. If there are only two backups, however, the last backup older than the retention_time window will also be retained. In addition, any non-full backup with a status of INCOMPLETE or QUORUM that occurs between the full backups is retained as well.

FSBlobStore class settings

The following settings are applicable only to the FSBlobStore class.

Setting Description Type Required
path Path where snapshots are stored. The directory must exist. text true

AzureBlobStore class settings

The following settings are applicable only to the AzureBlobStore class.

Setting Description Type Required
container Azure container in which snapshots are stored. text true
endpoint Azure endpoint. May be replaced with the Azure account name. text true
sas_token The Azure sas_token. text true unless Azure Managed Identity authentication mechanism is in use.

GoogleCloudBlobStore class settings

The following settings are applicable only to the GoogleCloudBlobStore class.

Setting Description Type Required
bucket Google Cloud bucket in which snaphots are stored. text true
client_email Email address associated with the Google Cloud account. text false unless private_key is set
client_id Client ID associated with the Google Cloud account. text false
private_key Private key associated with the Google Cloud account. text false unless client_email is set
private_key_id Private key ID of the private_key associated with the Google Cloud account. text false
project_id Project ID associated with the Google Cloud bucket. text false
endpoint Google Cloud Endpoint. See https://cloud.google.com/endpoints/docs/quickstart-endpoints. text false

Authentication details

If no credentials are set in the GoogleCloudBlobStore settings, Application Default Credentials (ADC) are used. Credentials are checked in the following order:
  1. ADC checks the environment variable, GOOGLE_APPLICATION_CREDENTIALS, and, if set, uses the referenced service account file.
  2. If GOOGLE_APPLICATION_CREDENTIALS is not set, ADC uses the default service account provided by the Compute Engine, Kubernetes Engine, App Engine, or Cloud Functions depending on the environment on which the application is running.
  3. If no credentials are found, an error occurs.

See: https://cloud.google.com/docs/authentication/production.

S3BlobStore class settings

The following settings are applicable to only the S3BlobStore class.

Setting Description Type Required
bucket AWS bucket in which snapshots are stored. text true
region AWS region, an alternative to the endpoint setting. text true if endpoint is not set
access_key Access key used for authentication. text false
secret_key Secret key used for authentication. text false
default_socket_timeout Socket timeout in ms.

Default: 50,000

int false
max_error_retry Maximum retries when an error occurs.

Default: 3

int false
default_throttle_retries Enables retry throttling.

Default: true

int false
server_side_encryption Enable server-side encryption (AES256).

Default: true

boolean false
accelerated_mode_enabled Enable AWS transfer acceleration. Only applicable to AWS S3. See https://docs.aws.amazon.com/AmazonS3/latest/dev/transfer-acceleration.html.

Default: true

boolean false
storage_class Storage class in which Binary Large Objects (BLOBS) are stored. See https://aws.amazon.com/s3/storage-classes/. text false
canned_acl Access Control List (ACL) for buckets and objects. text false
endpoint Endpoint for the AWS S3 server, an alternative to the region setting. text true if region is not set.

Authentication details

If no details are specified in the S3BlobStore settings, the DefaultAWSCredentialsProviderChain is used. The DefaultAWSCredentialsProviderChain searches for credentials in the following order:
  1. The environment variables, AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.
  2. The Java system properties, aws.accessKeyId and aws.secretKey.
  3. A credential profile located at ~/.aws/credentials.
  4. Credentials provided through the Amazon EC2 container service if the AWS_CONTAINER_CREDENTIALS_RELATIVE_URI environment variable is set and the security manager has permission to access that variable.
  5. Instance profile credentials delivered using the Amazon EC2 metadata service.
keyspace_name_new

Name of the new keyspace into which the backup data should be restored. The keyspace must exist.

Examples

Restore a full keyspace backup

Restore a specific backup from a file system store class:
FORCE RESTORE keyspace_1
    FROM BACKUP backup_configuration_1-c0dfeb5b-323e-4e3d-8ebc-6948050e3e70
    FROM STORE fs_store_1;

02d2603a-7e22-11e9-8f9e-2a86e4085a59

Restore tables within a keyspace

Restore specific tables within a keyspace:
FORCE RESTORE keyspace_1.data_table_1, keyspace_1.data_table_2
    FROM BACKUP backup_configuration_1-c0dfeb5b-323e-4e3d-8ebc-6948050e3e70
    FROM STORE fs_store_1;

02d3333a-7e22-11e9-8f9e-2a86e4085a59

Restore a keyspace into a new keyspace

Restore a keyspace to a new keyspace:
FORCE RESTORE keyspace_1
    FROM BACKUP backup_configuration_1-c0dfeb5b-323e-4e3d-8ebc-6948050e3e70
    FROM STORE fs_store_1
    INTO KEYSPACE keyspace_2;

12f5533a-7e22-11e9-8f9e-2a86e4085a59

Restore a backup with custom store settings into a new cluster

On a node in a new cluster with the Backup and Restore Service enabled, restore a specific backup from an existing FSBlobStore backup store:
FORCE RESTORE keyspace_1
    FROM BACKUP backup_configuration_1-c0dfeb5b-323e-4e3d-8ebc-6948050e3e70
    USING 'FSBlobStore'
    WITH settings={'path': '/my/backup/path'};

12e2603b-7e22-11e9-8f9e-2a86e4085a62
The required settings for each backup store class are:
  • FSBlobStore: path
  • GoogleCloudBlobStore: bucket
  • S3BlobStore: bucket and region or bucket and endpoint
Attention: After a FORCE RESTORE, you must run a nodetool repair or schedule a manual nodesync on the node. See:
For instructions on enabling the DSE Backup and Restore Service, see Enabling and configuring the DSE Backup and Restore Service (beta) .