res.yaml

use: restore --cluster <id|name> --location [<dc>:]<provider>:<bucket> --snapshot-tag <tag> [flags]

short: Run an ad-hoc restore of schema or tables

long: |
  This command allows you to run an ad-hoc restore.
  Restore is always one of two types: restore schema ('--restore-schema' flag) or restore tables' contents ('--restore-tables' flag).
  In both cases, for the restore effects to be visible, you need to perform
  a specific follow-up action described by selected type.

location: |
  A list of backup locations separated by a comma, specifies places where restored backup is stored.
  
  The format is `[<dc>:]<provider>:<bucket>`.
  The `<dc>` parameter is optional. It allows you to specify the datacenter whose nodes will be used to restore the data
  from this location in a multi-dc setting, it must match Scylla nodes datacenter.
  By default, all live nodes are used to restore data from specified locations.
  If `--dc-mapping` is used, then `<dc>` parameter will be ignored.
  
  Note that specifying datacenters closest to backup locations might reduce download time of restored data.
  The supported storage '<provider>'s are 'azure', 'gcs', 's3'.
  The `<bucket>` parameter is a bucket name, it must be an alphanumeric string and **may contain a dash and or a dot, but other characters are forbidden**.

snapshot-tag: |
  Scylla Manager snapshot tag identifying restored backup.
  Snapshot tags can be obtained from backup listing ('./sctool backup list' command - e.g. sm_20060102150405UTC).

batch-size: |
  Number of SSTables per shard to process in one request by one node when restoring with rclone API (see --method flag).
  When restoring with native API, --batch-size is ignored and batches are as large as possible while keeping equal workload distribution across all nodes.
  Increasing the default batch size might significantly increase restore performance, as only one shard can work on restoring a single SSTable bundle.
  Set to 0 for best performance (batches will contain sstables of total size up to 5% of expected total node workload).

parallel: |
  The maximum number of Scylla restore jobs that can be run at the same time (on different SSTables).
  Each node can take part in at most one restore at any given moment.

transfers: |
  Sets the amount of file transfers to run in parallel when downloading files from backup location to Scylla node.
  Set to 0 for the fastest download (results in setting transfers to 2*node_shard_count).
  Set to -1 for using the transfers value defined in node's 'scylla-manager-agent.yaml' config file.

rate-limit: |
  Limits the download rate (as expressed in  megabytes (MiB) per second) at which sstables can be downloaded from backup location to Scylla nodes.
  You can set limits for more than one DC using a comma-separated list expressed in the format `[<dc>:]<limit>`.
  The <dc>: part is optional and is only needed when different datacenters require different download limits.
  Set to 0 for no limit (default 0).

allow-compaction: |
  Defines if auto compactions should be running on Scylla nodes during restore.
  Disabling auto compactions decreases restore time duration, but increases compaction workload after the restore is done.

unpin-agent-cpu: |
  Defines if ScyllaDB Manager Agent should be unpinned from CPUs during restore.
  This might significantly improve download speed at the cost of decreasing streaming speed. 

restore-schema: |
  Specifies restore type (alternative to '--restore-tables' flag).
  Restore will recreate schema by applying the backed up output of DESCRIBE SCHEMA WITH INTERNALS via CQL.
  It requires that restored keyspaces aren't present in the cluster.
  For the full list of prerequisites, please see https://manager.docs.scylladb.com/stable/restore/restore-schema.html.

restore-tables: |
  Specifies restore type (alternative to '--restore-schema' flag).
  Restore will recreate contents of tables specified by '--keyspace' flag.
  It requires that correct schema of restored tables is already present in the cluster (schema can be restored using '--restore-schema' flag).
  Moreover, in order to prevent situation in which current tables' contents overlaps restored data,
  tables should be truncated before initializing restore.
  For the full list of prerequisites, please see https://manager.docs.scylladb.com/stable/restore/restore-tables.html.

dry-run: |
  Validates and displays restore information without actually running the restore.
  This allows you to display what will happen should the restore run with the parameters you set.

show-tables: |
  Prints table names together with keyspace, used in combination with --dry-run.

dc-mapping: |
  Specifies mapping between DCs from the backup and DCs in the restored(target) cluster.

  The Syntax is "source_dc1=target_dc1,source_dc2=target_dc2" where multiple mappings are separated by comma (,)
  and source and target DCs are separated by equal (=).

  Example: "dc1=dc3,dc2=dc4" - data from dc1 should be restored to dc3 and data from dc2 should be restored to dc4.

  Only works with tables restoration (--restore-tables=true). 
  Note: Only DCs that are provided in mappings will be restored.

keyspace-mapping: |
  Specifies mapping between keyspaces from the backup and keyspaces in the restored(target) cluster.
  This allows restoring data from a source keyspace into a different (renamed) keyspace.

  The syntax is "source_ks1=target_ks1,source_ks2=target_ks2" where multiple mappings are separated by comma (,)
  and source and target keyspaces are separated by equal (=).

  Example: "ks1=ks_new" - data from keyspace ks1 in the backup will be restored to keyspace ks_new in the cluster.

  Only works with tables restoration (--restore-tables=true).
  The target keyspace must already exist in the cluster before starting the restore.
  Use the '--keyspace' flag to filter which source keyspaces are restored; it still refers to source keyspace names.

method: |
  Control native restore method (See https://manager.docs.scylladb.com/stable/restore/native-restore):

  * 'auto': Use the supported native restore functionalities, otherwise use rclone restore.
  * 'native': Use the native restore functionalities only.
  * 'rclone': Use the rclone restore functionalities only.
  
  Using native restore functionalities requires additional configuration and has its own limitations,
  which are described in detail in https://manager.docs.scylladb.com/stable/restore/native-restore.