[Yandex Cloud documentation](../../index.md) > [Yandex Managed Service for ClickHouse®](../index.md) > [Step-by-step guides](index.md) > Clusters > Managing backups

# Managing backups in Managed Service for ClickHouse®


You can create [backups](../concepts/backup.md) and use existing backups to restore clusters.

Managed Service for ClickHouse® automatically takes a daily backup as well. You can [set the backup start time](#set-backup-window) and [retention period](#set-backup-retain).

## Creating a backup {#create-backup}

{% note warning %}

The system uses random replica hosts to create backups. If cluster hosts lack data consistency, restoring such a cluster from a backup does not guarantee complete data recovery. For more information, see [Backups](../concepts/backup.md).

{% endnote %}

{% list tabs group=instructions %}

- Management console {#console}
  
  1. In the [management console](https://console.yandex.cloud), select the folder containing the cluster.
  1. Navigate to **Managed Service for ClickHouse**.
  1. Click the name of your cluster and select the **Backups** tab.
  1. Click **Create backup**.

  This will initiate creating a backup without any additional confirmation.

- CLI {#cli}
  
  If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../cli/quickstart.md#install).
  
  The folder used by default is the one specified when [creating](../../cli/operations/profile/profile-create.md) the CLI profile. To change the default folder, use the `yc config set folder-id <folder_ID>` command. You can also specify a different folder for any command using `--folder-name` or `--folder-id`. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.
  
  To create a cluster backup:
  
  1. View the description of the CLI command for creating a ClickHouse® backup:
  
      ```bash
      yc managed-clickhouse cluster backup --help
      ```
  
  1. Send the following request to create a cluster backup, specifying the cluster name or ID:
  
      ```bash
      yc managed-clickhouse cluster backup <cluster_name_or_ID>
      ```
  
      You can get the cluster name and ID with the [list of clusters in the folder](cluster-list.md#list-clusters).

- REST API {#api}

    1. [Get an IAM token for API authentication](../api-ref/authentication.md) and put it into an environment variable:

        ```bash
        export IAM_TOKEN="<IAM_token>"
        ```

    1. Call the [Cluster.Backup](../api-ref/Cluster/backup.md) method, e.g., via the following [cURL](https://curl.se/) request:

        ```bash
        curl \
            --request POST \
            --header "Authorization: Bearer $IAM_TOKEN" \
            --header "Content-Type: application/json" \
            --url 'https://mdb.api.cloud.yandex.net/managed-clickhouse/v1/clusters/<cluster_ID>:backup'
        ```

        You can request the cluster ID with the [list of clusters in the folder](cluster-list.md#list-clusters).

    1. View the [server response](../api-ref/Cluster/backup.md#responses) to make sure your request was successful.

- gRPC API {#grpc-api}

    1. [Get an IAM token for API authentication](../api-ref/authentication.md) and put it into an environment variable:

        ```bash
        export IAM_TOKEN="<IAM_token>"
        ```

    1. Clone the [cloudapi](https://github.com/yandex-cloud/cloudapi) repository:
       
       ```bash
       cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi
       ```
       
       Below, we assume that the repository contents reside in the `~/cloudapi/` directory.

    1. Call the [ClusterService.Backup](../api-ref/grpc/Cluster/backup.md) method, e.g., via the following [gRPCurl](https://github.com/fullstorydev/grpcurl) request:

        ```bash
        grpcurl \
            -format json \
            -import-path ~/cloudapi/ \
            -import-path ~/cloudapi/third_party/googleapis/ \
            -proto ~/cloudapi/yandex/cloud/mdb/clickhouse/v1/cluster_service.proto \
            -rpc-header "Authorization: Bearer $IAM_TOKEN" \
            -d '{
                  "cluster_id": "<cluster_ID>"
                }' \
            mdb.api.cloud.yandex.net:443 \
            yandex.cloud.mdb.clickhouse.v1.ClusterService.Backup
        ```

        You can request the cluster ID with the [list of clusters in the folder](cluster-list.md#list-clusters).

    1. View the [server response](../api-ref/grpc/Cluster/backup.md#yandex.cloud.operation.Operation) to make sure your request was successful.

{% endlist %}

While you are creating a backup, the cluster performance may degrade.

## Restoring a cluster from a backup {#restore}

{% note warning %}

For clusters running an unsupported [DBMS version](../concepts/update-policy.md#versioning-policy), restoring from backups is not available.

{% endnote %}

You can restore an individual [shard](../concepts/sharding.md) or the whole cluster.


Before you begin, [assign](../../iam/operations/roles/grant.md) the following roles to your Yandex Cloud account:

* [managed-clickhouse.restorer](../../iam/roles-reference.md#managed-clickhouse-restorer) or higher for the backup folder and the new cluster folder.
* [iam.serviceAccounts.user](../../iam/security/index.md#iam-serviceAccounts-user) or higher if restoring a cluster attached to a [service account](../../iam/concepts/users/service-accounts.md).


{% note alert "Important" %}

When restoring a backup to a cluster without any ZooKeeper hosts, all the `ReplicatedMergeTree` tables will be converted to simple `MergeTree` tables. Converted tables will contain the same data. For more information, see [this ClickHouse® guide](https://clickhouse.com/docs/enen/engines/table-engines/mergetree-family/replication).

{% endnote %}

{% list tabs group=instructions %}

- Management console {#console}

  To restore an existing cluster from a backup:
  1. In the [management console](https://console.yandex.cloud), select the folder where you want to restore a cluster.
  1. Navigate to **Managed Service for&nbsp;ClickHouse**.
  1. Click the name of your cluster and select the **Backups** tab.
  1. Click ![image](../../_assets/console-icons/ellipsis.svg) for the backup you need and then click **Restore cluster**.
  1. Update the new cluster settings, if required. You can select a folder for the new cluster from the **Folder** list.

  1. Optionally, to restore individual databases or tables:

      1. Under **Basic parameters**, enable **Partial recovery**.
      1. Make the list for restoration by entering the database name, table name, or a mask, e.g., `table*`.

          If you want to restore an entire database, use `*` as the mask.

      1. Click ![image](../../_assets/console-icons/plus.svg) **Add**.
      1. Repeat these steps for each database or table you need restored.

  1. Optionally, if the backup was created for a sharded cluster, you can select shards for restoration:

      * To restore a single shard, make sure to leave only that particular shard checked under **Shards**. Uncheck the rest of the shards.
      * To restore the whole cluster, leave all shards checked under **Shards**.

      You can set a separate configuration for each shard you restore.

  1. Click **Restore cluster**.

  To restore a previously deleted cluster from a backup:
  1. In the [management console](https://console.yandex.cloud), select the folder where you want to restore a cluster.
  1. Navigate to **Managed Service for&nbsp;ClickHouse**.
  1. In the left-hand panel, select ![image](../../_assets/console-icons/archive.svg) **Backups**.
  1. Click ![image](../../_assets/console-icons/ellipsis.svg) for your backup and click **Restore cluster**.
  1. Update the new cluster settings, if required. You can select a folder for the new cluster from the **Folder** list.

  1. Optionally, to restore individual databases or tables:

      1. Under **Basic parameters**, enable **Partial recovery**.
      1. Make the list for restoration by entering the database name, table name, or a mask, e.g., `table*`.

          If you want to restore an entire database, use `*` as the mask.

      1. Click ![image](../../_assets/console-icons/plus.svg) **Add**.
      1. Repeat these steps for each database or table you need restored.

  1. Optionally, if the backup was created for a sharded cluster, you can select shards for restoration:

      * To restore a single shard, make sure to leave only that particular shard checked under **Shards**. Uncheck the rest of the shards.
      * To restore the whole cluster, leave all shards checked under **Shards**.

      You can set a separate configuration for each shard you restore.

  1. Click **Restore cluster**.

  Managed Service for ClickHouse® will start creating the cluster from the backup.

- CLI {#cli}

  If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../cli/quickstart.md#install).

  The folder used by default is the one specified when [creating](../../cli/operations/profile/profile-create.md) the CLI profile. To change the default folder, use the `yc config set folder-id <folder_ID>` command. You can also specify a different folder for any command using `--folder-name` or `--folder-id`. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.

  To restore a cluster from a backup:

  1. View the description of the CLI command for restoring a ClickHouse® cluster:

      ```bash
      yc managed-clickhouse cluster restore --help
      ```

  1. Get the list of available ClickHouse® cluster backups:

      ```bash
      yc managed-clickhouse backup list
      ```

      ```text
      +----------------------+---------------------+----------------------+---------------------+-------------+-------+-----------+
      |            ID        |     CREATED AT      |  SOURCE CLUSTER ID   |     STARTED AT      | SHARD NAMES | SIZE  |   TYPE    |
      +----------------------+---------------------+----------------------+---------------------+-------------+-------+-----------+
      | mdb29m1kk9v2******** | 2023-12-08 00:09:17 | c9qud5etkq19******** | 2023-12-08 00:08:06 | shard1      | 30 KB | AUTOMATED |
      | ...                  |                     |                      |                     |             |       |           |
      +----------------------+---------------------+----------------------+---------------------+-------------+-------+-----------+
      ```

  1. To restore a cluster, run the command below considering the backup type:

      * If the backup was created for all cluster shards at once, which is the [backup option currently used](../concepts/backup.md#size), provide a single backup ID in the command:

          
          ```bash
          yc managed-clickhouse cluster restore \
             --backup-id=<cluster_ID>:<backup_ID> \
             --name=<cluster_name> \
             --environment=<environment> \
             --network-name=<network_name> \
             --host type=<host_type>,`
                   `zone-id=<availability_zone>,`
                   `subnet-id=<subnet_ID> \
             --shard name=<shard_name>,`
                   `weight=<shard_weight> \
             --clickhouse-disk-size=<storage_size_in_GB> \
             --clickhouse-disk-type=<disk_type> \
             --clickhouse-resource-preset=<host_class> \
             --include-patterns <list_of_databases_and_tables_to_restore>
          ```


          Where:

          * `--backup-id`: Cluster and backup IDs.
          * `--name`: Cluster name.
          * `--environment`: Environment:

              * `PRODUCTION`: For stable versions of your applications.
              * `PRESTABLE`: For testing purposes. The prestable environment is similar to the production environment and likewise covered by an SLA, but it is the first to get new features, improvements, and bug fixes. In the prestable environment, you can test new versions for compatibility with your application.

          * `--network-name`: [Network name](../../vpc/concepts/network.md#network).
          * `--host`: Host settings:

              * `type`: Host type, `clickhouse` or `zookeeper`.
              * `zone-id`: [Availability zone](../../overview/concepts/geo-scope.md).
              * `subnet-id`: [Subnet ID](../../vpc/concepts/network.md#subnet). Specify it if the selected availability zone has two or more subnets.

          * `--shard`: Shard parameters:

              * `name`: Shard name.
              * `weight`: Shard weight. The minimum value is `0`.

              To restore a single cluster shard, only specify the parameters for the shard to restore. The shard name must match its name in the source cluster.

              To restore the whole cluster, you may skip shard parameters.

          * `--resource-preset`: [Host class](../concepts/instance-types.md#available-flavors).
          * `--disk-size`: Storage size, in GB.
          * `--disk-type`: [Disk type](../concepts/storage.md):

              
              * `network-hdd`
              * `network-ssd`
              * `local-ssd`
              * `network-ssd-nonreplicated`
              * `network-ssd-io-m3`


          * `--include-patterns` and `--exclude-patterns`: Settings for restoring individual databases and tables:

              * `--include-patterns`: List of databases and tables to restore, e.g., `db1.table1,db2.*,db3.table*`.
              * `--exclude-patterns`: List of databases and tables to exclude from restoring, e.g., `db1.table1,db2.*,db3.table*`. All databases and tables except those specified in the exclusion parameter will be restored.

              In the recovery command, you can specify only one of the following parameters: `--include-patterns` or `--exclude-patterns`.

      * If separate backups were created for each cluster shard, which is the [legacy backup option](../concepts/backup.md#size), provide the backup IDs of all the cluster shards to restore the whole cluster:

          ```bash
          yc managed-clickhouse cluster restore \
             --backup-id=<list_of_backup_IDs_for_all_shards> \
             ...
          ```

- REST API {#api}

    1. [Get an IAM token for API authentication](../api-ref/authentication.md) and put it into an environment variable:

        ```bash
        export IAM_TOKEN="<IAM_token>"
        ```

    1. Call the [Cluster.Restore](../api-ref/Cluster/restore.md) method, e.g., via the following [cURL](https://curl.se/) request:

        1. Create a file named `body.json` and paste the following code into it:

            ```json
            {
              "backupId": "<cluster_ID>:<backup_ID>",
              "additionalBackupIds": [
                <list_of_additional_backup_IDs>
              ],
              "name": "<cluster_name>",
              "environment": "<environment>",
              "configSpec": { <cluster_configuration> },
              "hostSpecs": [
                {
                  "type": "<host_type>",
                  "zoneId": "<availability_zone>",
                  "subnetId": "<subnet_ID>",
                  "shardName": "<shard_name>",
                  "assignPublicIp": <public_access_to_host>
                },
                { <similar_settings_for_host_2> },
                { ... },
                { <similar_settings_for_host_N> }
              ],
              "shardSpecs: [
                {
                  "name": "<shard_name>",
                  "configSpec": {
                    "clickhouse": {
                      "weight": "<shard_weight>"
                    }
                }
              ],
              "folderId": "<folder_ID>",
              "networkId": "<network_ID>",
              "serviceAccountId": "<service_account_ID>",
              "securityGroupIds": [
                <list_of_security_group_IDs>
              ],
              "deletionProtection": <cluster_deletion_protection>,
              "partialRestore": {
                "includePatterns": [<list_of_databases_and_tables_to_restore>],
                "excludePatterns": [<list_of_databases_and_tables_to_exclude_from_restoring>]
              }
            }
            ```

            Where:

            * `backupId`: Cluster and backup IDs.

                This will restore your cluster as a whole.

            * `additionalBackupIds`: Array of additional backup IDs. Use this parameter if separate backups were created for each shard, which is the legacy backup option.

                This will restore the shards for which those backups were created. To restore the whole cluster, provide backup IDs for all cluster shards.

            * `name`: Cluster name.
            * `environment`: Environment:

                * `PRODUCTION`: For stable versions of your applications.
                * `PRESTABLE`: For testing purposes. The prestable environment is similar to the production environment and likewise covered by an SLA, but it is the first to get new features, improvements, and bug fixes. In the prestable environment, you can test new versions for compatibility with your application.

            * `configSpec`: ClickHouse® cluster configuration. For a detailed description of the parameters, see the [Cluster.restore](../api-ref/Cluster/restore.md) method description.
            * `hostSpecs`: Array of settings for the new hosts. Each array element contains the configuration for a single host and has the following structure:

                * `type`: Host type.
                * `zoneId`: Availability zone.
                * `subnetId`: Subnet ID.
                * `shardName`: Shard name.
                * `assignPublicIp`: Internet access to the host via a public IP address, `true` or `false`.

            * `shardSpecs`: Array of settings of the shards to restore:

              * `name`: Shard name. The value must match the shard name in the source cluster.
              * `configSpec.clickhouse.weight`: Shard weight. The minimum value is `0`.

              To restore a single cluster shard, only specify the parameters for the shard to restore.

              To restore the whole cluster, you may skip this parameter.

              You can set a separate configuration for each shard you restore.

            * `folderId`: ID of the folder where you want to create your cluster.
            * `networkId`: ID of the network where you want to deploy your cluster.
            * `serviceAccountId`: Service account ID.
            * `securityGroupIds`: Array of security group IDs.
            * `deletionProtection`: Option to manage cluster protection against accidental deletion.

                Even with cluster deletion protection enabled, one can still delete a user or database or connect manually and delete the database contents.

            * `partialRestore`: Settings for restoring individual databases and tables:

                * `includePatterns`: List of databases and tables to restore, e.g., `["db1.table1", "db2.*", "db3.table*"]`.
                * `excludePatterns`: List of databases and tables to exclude from restoring, e.g., `["db2.table*", "db3.table3"]`.

                If tables are specified by mask in the `includePatterns` parameter, you can use the `excludePatterns` parameter to exclude specific tables within that mask. You can restore a database except for a certain table, e.g., `includePatterns: dbname1.*` and `excludePatterns: dbname1.bad_table`.

            You can get the cluster ID and backup ID with the [list of backups in the folder](#list-backups).

        1. Run this query:

            ```bash
            curl \
                --request POST \
                --header "Authorization: Bearer $IAM_TOKEN" \
                --header "Content-Type: application/json" \
                --url 'https://mdb.api.cloud.yandex.net/managed-clickhouse/v1/clusters:restore' \
                --data "@body.json"
            ```

    1. Check the [server response](../api-ref/Cluster/restore.md#responses) to make sure your request was successful.

- gRPC API {#grpc-api}

    1. [Get an IAM token for API authentication](../api-ref/authentication.md) and put it into an environment variable:

        ```bash
        export IAM_TOKEN="<IAM_token>"
        ```

    1. Clone the [cloudapi](https://github.com/yandex-cloud/cloudapi) repository:
       
       ```bash
       cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi
       ```
       
       Below, we assume that the repository contents reside in the `~/cloudapi/` directory.

    1. Call the [ClusterService.Restore](../api-ref/grpc/Cluster/restore.md) method, e.g., via the following [gRPCurl](https://github.com/fullstorydev/grpcurl) request:

        1. Create a file named `body.json` and paste the following code into it:

            ```json
            {
              "backup_id": "<cluster_ID>:<backup_ID>",
              "additional_backup_ids": [
                <list_of_additional_backup_IDs>
              ],
              "name": "<cluster_name>",
              "environment": "<environment>",
              "config_spec": { <cluster_configuration> },
              "host_specs": [
                {
                  "type": "<host_type>",
                  "zone_id": "<availability_zone>",
                  "subnet_id": "<subnet_ID>",
                  "shard_name": "<shard_name>",
                  "assign_public_ip": <public_access_to_host>
                },
                { <similar_settings_for_host_2> },
                { ... },
                { <similar_settings_for_host_N> }
              ],
              "shard_specs: [
                {
                  "name": "<shard_name>",
                  "config_spec": {
                    "clickhouse": {
                      "weight": "<shard_weight>"
                    }
                }
              ],
              "folder_id": "<folder_ID>",
              "network_id": "<network_ID>",
              "service_account_id": "<service_account_ID>",
              "security_group_ids": [
                <list_of_security_group_IDs>
              ],
              "deletion_protection": <cluster_deletion_protection>,
              "partial_restore": {
                "include_patterns": [<list_of_databases_and_tables_to_restore>],
                "exclude_patterns": [<list_of_databases_and_tables_to_exclude_from_restoring>]
              }
            }
            ```

            Where:

            * `backup_id`: Cluster and backup IDs.

                This will restore your cluster as a whole.

            * `additional_backup_ids`: Array of additional backup IDs. Use this parameter if separate backups were created for each shard, which is the legacy backup option.

                This will restore the shards for which those backups were created. To restore the whole cluster, provide backup IDs for all cluster shards.

            * `name`: Cluster name.
            * `environment`: Environment:

                * `PRODUCTION`: For stable versions of your applications.
                * `PRESTABLE`: For testing purposes. The prestable environment is similar to the production environment and likewise covered by an SLA, but it is the first to get new features, improvements, and bug fixes. In the prestable environment, you can test new versions for compatibility with your application.

            * `config_spec`: ClickHouse® cluster configuration. For a detailed description of the parameters, see the [ClusterService/Restore](../api-ref/grpc/Cluster/restore.md) call description.
            * `host_specs`: Array of settings for the new hosts. Each array element contains the configuration for a single host and has the following structure:

                * `type`: Host type.
                * `zone_id`: Availability zone.
                * `subnet_id`: Subnet ID.
                * `shard_name`: Shard name.
                * `assign_public_ip`: Internet access to the host via a public IP address, `true` or `false`.

            * `shard_specs`: Array of settings of the shards to restore:

              * `name`: Shard name. The value must match the shard name in the source cluster.
              * `config_spec.clickhouse.weight`: Shard weight. The minimum value is `0`.

              To restore a single cluster shard, only specify the parameters for the shard to restore.

              To restore the whole cluster, you may skip this parameter.

              You can set a separate configuration for each shard you restore.

            * `folder_id`: ID of the folder where you want to create your cluster.
            * `network_id`: ID of the network where you want to deploy your cluster.
            * `service_account_id`: Service account ID.
            * `security_group_ids`: Array of security group IDs.
            * `deletion_protection`: Option to manage cluster protection against accidental deletion.

                Even with cluster deletion protection enabled, one can still delete a user or database or connect manually and delete the database contents.

            * `partial_restore`: Settings for restoring individual databases and tables:

                * `include_patterns`: List of databases and tables to restore, e.g., `["db1.table1", "db2.*", "db3.table*"]`.
                * `exclude_patterns`: List of databases and tables to exclude from restoring, e.g., `["db2.table*", "db3.table3"]`.

                If tables are specified by mask in the `include_patterns` parameter, you can use the `exclude_patterns` parameter to exclude specific tables within that mask. You can restore a database except for a certain table, e.g., `include_patterns: dbname1.*` and `exclude_patterns: dbname1.bad_table`.

            You can get the cluster ID and backup ID with the [list of backups in the folder](#list-backups).

        1. Run this query:

            ```bash
            grpcurl \
                -format json \
                -import-path ~/cloudapi/ \
                -import-path ~/cloudapi/third_party/googleapis/ \
                -proto ~/cloudapi/yandex/cloud/mdb/clickhouse/v1/cluster_service.proto \
                -rpc-header "Authorization: Bearer $IAM_TOKEN" \
                -d @ \
                mdb.api.cloud.yandex.net:443 \
                yandex.cloud.mdb.clickhouse.v1.ClusterService.Restore \
                < body.json
            ```

    1. View the [server response](../api-ref/grpc/Cluster/restore.md#yandex.cloud.operation.Operation) to make sure your request was successful.

{% endlist %}

## Getting a list of backups {#list-backups}

{% list tabs group=instructions %}

- Management console {#console}

  To get a list of cluster backups:
  1. In the [management console](https://console.yandex.cloud), select the folder containing the cluster.
  1. Navigate to **Managed Service for&nbsp;ClickHouse**.
  1. Click the name of your cluster and select the **Backups** tab.

  To get a list of all backups in your folder:
  1. In the [management console](https://console.yandex.cloud), select the folder containing the cluster.
  1. Navigate to **Managed Service for&nbsp;ClickHouse**.
  1. In the left-hand panel, select ![image](../../_assets/console-icons/archive.svg) **Backups**.

  These lists contain the following information:

  * Backup ID.
  * Source shard names.
  * Backup size.
  * Backup type: `Automated` or `Manual`.
  * Backup start time (UTC).
  * Backup end time (UTC).

- CLI {#cli}

  If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../cli/quickstart.md#install).

  The folder used by default is the one specified when [creating](../../cli/operations/profile/profile-create.md) the CLI profile. To change the default folder, use the `yc config set folder-id <folder_ID>` command. You can also specify a different folder for any command using `--folder-name` or `--folder-id`. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.

  To get a list of ClickHouse® cluster backups available in the default folder, run this command:

  ```bash
  yc managed-clickhouse backup list
  ```

  ```text
  +----------------------+---------------------+----------------------+---------------------+-------------+-------+-----------+
  |            ID        |     CREATED AT      |  SOURCE CLUSTER ID   |     STARTED AT      | SHARD NAMES | SIZE  |   TYPE    |
  +----------------------+---------------------+----------------------+---------------------+-------------+-------+-----------+
  | mdb29m1kk9v2******** | 2023-12-08 00:09:17 | c9qud5etkq19******** | 2023-12-08 00:08:06 | shard1      | 30 KB | AUTOMATED |
  | mdb9sds0ast2******** | 2023-12-07 08:17:04 | c9qud5etkq19******** | 2023-12-07 08:15:54 | shard1      | 30 KB | MANUAL    |
  +----------------------+---------------------+----------------------+---------------------+-------------+-------+-----------+
  ```

  The table in the command output contains the following information:

  * Backup ID.
  * Backup end time (UTC).
  * ID of the backed up cluster.
  * Backup start time (UTC).
  * Source shard names.
  * Backup size.
  * Backup type: `AUTOMATED` or `MANUAL`.

- REST API {#api}

    1. [Get an IAM token for API authentication](../api-ref/authentication.md) and put it into an environment variable:

        ```bash
        export IAM_TOKEN="<IAM_token>"
        ```

    1. To get a list of ClickHouse® cluster backups:

        1. Call the [Cluster.ListBackups](../api-ref/Cluster/listBackups.md) method, e.g., via the following [cURL](https://curl.se/) request:

            ```bash
            curl \
                --request GET \
                --header "Authorization: Bearer $IAM_TOKEN" \
                --url 'https://mdb.api.cloud.yandex.net/managed-clickhouse/v1/clusters/<cluster_ID>/backups'
            ```

            You can request the cluster ID with the [list of clusters in the folder](cluster-list.md#list-clusters).

        1. View the [server response](../api-ref/Cluster/listBackups.md#responses) to make sure your request was successful.

    1. To get a list of backups for all ClickHouse® clusters in a folder:

        1. Call the [Backup.List](../api-ref/Backup/list.md) method, e.g., via the following [cURL](https://curl.se/) request:

            ```bash
            curl \
                --request GET \
                --header "Authorization: Bearer $IAM_TOKEN" \
                --url 'https://mdb.api.cloud.yandex.net/managed-clickhouse/v1/backups' \
                --url-query folderId=<folder_ID>
            ```

            
            You can get the folder ID with the [list of folders in the cloud](../../resource-manager/operations/folder/get-id.md).


        1. Check the [server response](../api-ref/Backup/list.md#responses) to make sure your request was successful.

- gRPC API {#grpc-api}

    1. [Get an IAM token for API authentication](../api-ref/authentication.md) and put it into an environment variable:

        ```bash
        export IAM_TOKEN="<IAM_token>"
        ```

    1. Clone the [cloudapi](https://github.com/yandex-cloud/cloudapi) repository:
       
       ```bash
       cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi
       ```
       
       Below, we assume that the repository contents reside in the `~/cloudapi/` directory.

    1. To get a list of ClickHouse® cluster backups:

        1. Call the [ClusterService.ListBackups](../api-ref/grpc/Cluster/listBackups.md) method, e.g., via the following [gRPCurl](https://github.com/fullstorydev/grpcurl) request:

            ```bash
            grpcurl \
                -format json \
                -import-path ~/cloudapi/ \
                -import-path ~/cloudapi/third_party/googleapis/ \
                -proto ~/cloudapi/yandex/cloud/mdb/clickhouse/v1/cluster_service.proto \
                -rpc-header "Authorization: Bearer $IAM_TOKEN" \
                -d '{
                        "cluster_id": "<cluster_ID>"
                    }' \
                mdb.api.cloud.yandex.net:443 \
                yandex.cloud.mdb.clickhouse.v1.ClusterService.ListBackups
            ```

            You can request the cluster ID with the [list of clusters in the folder](cluster-list.md#list-clusters).

        1. View the [server response](../api-ref/grpc/Cluster/listBackups.md#yandex.cloud.mdb.clickhouse.v1.ListClusterBackupsResponse) to make sure your request was successful.

    1. To get a list of backups for all ClickHouse® clusters in a folder:

        1. Call the [BackupService.List](../api-ref/grpc/Backup/list.md) method, e.g., via the following [gRPCurl](https://github.com/fullstorydev/grpcurl) request:

            ```bash
            grpcurl \
                -format json \
                -import-path ~/cloudapi/ \
                -import-path ~/cloudapi/third_party/googleapis/ \
                -proto ~/cloudapi/yandex/cloud/mdb/clickhouse/v1/backup_service.proto \
                -rpc-header "Authorization: Bearer $IAM_TOKEN" \
                -d '{
                        "folder_id": "<folder_ID>"
                    }' \
                mdb.api.cloud.yandex.net:443 \
                yandex.cloud.mdb.clickhouse.v1.BackupService.List
            ```

            
            You can get the folder ID with the [list of folders in the cloud](../../resource-manager/operations/folder/get-id.md).


        1. Check the [server response](../api-ref/grpc/Backup/list.md#yandex.cloud.mdb.clickhouse.v1.ListBackupsResponse) to make sure your request was successful.

{% endlist %}

## Getting backup information {#get-backup}

{% list tabs group=instructions %}

- Management console {#console}

  To get backup details for an existing cluster:
  1. In the [management console](https://console.yandex.cloud), select the folder containing the cluster.
  1. Navigate to **Managed Service for&nbsp;ClickHouse**.
  1. Click the name of your cluster and select the **Backups** tab.

  To get backup details for a previously deleted cluster:
  1. In the [management console](https://console.yandex.cloud), select the folder where the cluster used to reside.
  1. Navigate to **Managed Service for&nbsp;ClickHouse**.
  1. In the left-hand panel, select ![image](../../_assets/console-icons/archive.svg) **Backups**.

- CLI {#cli}

  If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../cli/quickstart.md#install).

  The folder used by default is the one specified when [creating](../../cli/operations/profile/profile-create.md) the CLI profile. To change the default folder, use the `yc config set folder-id <folder_ID>` command. You can also specify a different folder for any command using `--folder-name` or `--folder-id`. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.

  To get information about a ClickHouse® cluster backup, run this command:

  ```bash
  yc managed-clickhouse backup get <cluster_ID>:<backup_ID>
  ```

  You can get the cluster ID and backup ID with the [list of backups](#list-backups).

- REST API {#api}

    1. [Get an IAM token for API authentication](../api-ref/authentication.md) and put it into an environment variable:

        ```bash
        export IAM_TOKEN="<IAM_token>"
        ```

    1. Call the [Backup.Get](../api-ref/Backup/get.md) method, e.g., via the following [cURL](https://curl.se/) request:

        ```bash
        curl \
            --request GET \
            --header "Authorization: Bearer $IAM_TOKEN" \
            --url 'https://mdb.api.cloud.yandex.net/managed-clickhouse/v1/backups/<cluster_ID>:<backup_ID>'
        ```

        You can get the cluster ID and backup ID with the [list of backups](#list-backups).

    1. View the [server response](../api-ref/Backup/get.md#responses) to make sure your request was successful.

- gRPC API {#grpc-api}

    1. [Get an IAM token for API authentication](../api-ref/authentication.md) and put it into an environment variable:

        ```bash
        export IAM_TOKEN="<IAM_token>"
        ```

    1. Clone the [cloudapi](https://github.com/yandex-cloud/cloudapi) repository:
       
       ```bash
       cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi
       ```
       
       Below, we assume that the repository contents reside in the `~/cloudapi/` directory.

    1. Call the [BackupService.Get](../api-ref/grpc/Backup/get.md) method, e.g., via the following [gRPCurl](https://github.com/fullstorydev/grpcurl) request:

        ```bash
        grpcurl \
            -format json \
            -import-path ~/cloudapi/ \
            -import-path ~/cloudapi/third_party/googleapis/ \
            -proto ~/cloudapi/yandex/cloud/mdb/clickhouse/v1/backup_service.proto \
            -rpc-header "Authorization: Bearer $IAM_TOKEN" \
            -d '{
                    "backup_id": "<cluster_ID>:<backup_ID>"
                }' \
            mdb.api.cloud.yandex.net:443 \
            yandex.cloud.mdb.clickhouse.v1.BackupService.Get
        ```

        You can get the cluster ID and backup ID with the [list of backups](#list-backups).

    1. View the [server response](../api-ref/grpc/Backup/get.md#yandex.cloud.mdb.clickhouse.v1.Backup) to make sure your request was successful.

{% endlist %}

## Setting the backup start time {#set-backup-window}

{% list tabs group=instructions %}

- Management console {#console}

  In the [management console](https://console.yandex.cloud), you can set the backup start time when [creating](cluster-create.md) or [updating a cluster](update.md).

- CLI {#cli}

  If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../cli/quickstart.md#install).

  The folder used by default is the one specified when [creating](../../cli/operations/profile/profile-create.md) the CLI profile. To change the default folder, use the `yc config set folder-id <folder_ID>` command. You can also specify a different folder for any command using `--folder-name` or `--folder-id`. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.

  To set the backup start time, provide the appropriate value in `HH:MM:SS` format in the `--backup-window-start` argument of the `cluster update` command:

  ```bash
  yc managed-clickhouse cluster update <cluster_name_or_ID> \
     --backup-window-start=<backup_start_time>
  ```

  You can get the cluster ID and name with the [list of clusters in the folder](cluster-list.md#list-clusters).

- REST API {#api}

    1. [Get an IAM token for API authentication](../api-ref/authentication.md) and put it into an environment variable:

        ```bash
        export IAM_TOKEN="<IAM_token>"
        ```

    1. Call the [Cluster.Update](../api-ref/Cluster/update.md) method, e.g., via the following [cURL](https://curl.se/) request:

        {% note warning %}
        
        The API method will assign default values to all the parameters of the object you are modifying unless you explicitly provide them in your request. To avoid this, list the settings you want to change in the `updateMask` parameter as a single comma-separated string.
        
        {% endnote %}

        ```bash
        curl \
            --request PATCH \
            --header "Authorization: Bearer $IAM_TOKEN" \
            --header "Content-Type: application/json" \
            --url 'https://mdb.api.cloud.yandex.net/managed-clickhouse/v1/clusters/<cluster_ID>' \
            --data '{
                      "updateMask": "configSpec.backupWindowStart",
                      "configSpec": {
                        "backupWindowStart": {
                          "hours": "<hours>",
                          "minutes": "<minutes>",
                          "seconds": "<seconds>",
                          "nanos": "<nanoseconds>"
                        }
                      }
                    }'
        ```

        Where:

        * `updateMask`: Comma-separated string of settings to update.

            Here, we only specified a single setting, `configSpec.backupWindowStart`.

        * `configSpec.backupWindowStart`: Backup start time (UTC):
          
          * `hours`: Hours in 24-hour format
          * `minutes`: Minutes
          * `seconds`: Seconds
          * `nanos`: Nanoseconds

        You can request the cluster ID with the [list of clusters in the folder](cluster-list.md#list-clusters).

    1. View the [server response](../api-ref/Cluster/update.md#responses) to make sure your request was successful.

- gRPC API {#grpc-api}

    1. [Get an IAM token for API authentication](../api-ref/authentication.md) and put it into an environment variable:

        ```bash
        export IAM_TOKEN="<IAM_token>"
        ```

    1. Clone the [cloudapi](https://github.com/yandex-cloud/cloudapi) repository:
       
       ```bash
       cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi
       ```
       
       Below, we assume that the repository contents reside in the `~/cloudapi/` directory.

    1. Call the [ClusterService.Update](../api-ref/grpc/Cluster/update.md) method, e.g., via the following [gRPCurl](https://github.com/fullstorydev/grpcurl) request:

        {% note warning %}
        
        The API method will assign default values to all the parameters of the object you are modifying unless you explicitly provide them in your request. To avoid this, list the settings you want to change in the `update_mask` parameter as an array of `paths[]` strings.
        
        {% cut "Format for listing settings" %}
        
        ```yaml
        "update_mask": {
            "paths": [
                "<setting_1>",
                "<setting_2>",
                ...
                "<setting_N>"
            ]
        }
        ```
        
        {% endcut %}
        
        {% endnote %}

        ```bash
        grpcurl \
            -format json \
            -import-path ~/cloudapi/ \
            -import-path ~/cloudapi/third_party/googleapis/ \
            -proto ~/cloudapi/yandex/cloud/mdb/clickhouse/v1/cluster_service.proto \
            -rpc-header "Authorization: Bearer $IAM_TOKEN" \
            -d '{
                  "cluster_id": "<cluster_ID>",
                  "update_mask": {
                    "paths": [
                      "config_spec.backup_window_start"
                    ]
                  },
                  "config_spec": {
                    "backup_window_start": {
                      "hours": "<hours>",
                      "minutes": "<minutes>",
                      "seconds": "<seconds>",
                      "nanos": "<nanoseconds>"
                    }
                  }
                }' \
            mdb.api.cloud.yandex.net:443 \
            yandex.cloud.mdb.clickhouse.v1.ClusterService.Update
        ```

        Where:

        * `update_mask`: List of settings to update as an array of strings (`paths[]`).

            Here, we only specified a single setting, `config_spec.backup_window_start`.

        * `config_spec.backup_window_start`: Backup start time (UTC):
          
          * `hours`: Hours in 24-hour format
          * `minutes`: Minutes
          * `seconds`: Seconds
          * `nanos`: Nanoseconds

        You can get the cluster ID with the [list of clusters in the folder](cluster-list.md#list-clusters).

    1. Check the [server response](../api-ref/grpc/Cluster/update.md#yandex.cloud.operation.Operation) to make sure your request was successful.

{% endlist %}

## Setting a retention period for automatic backups {#set-backup-retain}

{% list tabs group=instructions %}

- Management console {#console}
  
  You can set the retention period for automatic backups when you [create](cluster-create.md) or [update](update.md) the cluster via the [management console](https://console.yandex.cloud).
  
- CLI {#cli}

  If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../cli/quickstart.md#install).

  The folder used by default is the one specified when [creating](../../cli/operations/profile/profile-create.md) the CLI profile. To change the default folder, use the `yc config set folder-id <folder_ID>` command. You can also specify a different folder for any command using `--folder-name` or `--folder-id`. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.

  To set a retention period for automatic backups, provide the required value in `HH:MM:SS` format in the `--backup-retain-period-days` argument of the `cluster update` command:

  ```bash
  yc managed-clickhouse cluster update <cluster_name_or_ID> \
     --backup-retain-period-days=<automatic_backup_retention_period_in_days>
  ```
  
  You can get the cluster ID and name with the [list of clusters in the folder](cluster-list.md#list-clusters).

- REST API {#api}

  1. [Get an IAM token for API authentication](../api-ref/authentication.md) and put it into an environment variable:

      ```bash
      export IAM_TOKEN="<IAM_token>"
      ```

  1. Call the [Cluster.Update](../api-ref/Cluster/update.md) method, e.g., via the following [cURL](https://curl.se/) request:

      {% note warning %}
      
      The API method will assign default values to all the parameters of the object you are modifying unless you explicitly provide them in your request. To avoid this, list the settings you want to change in the `updateMask` parameter as a single comma-separated string.
      
      {% endnote %}

      ```bash
      curl \
          --request PATCH \
          --header "Authorization: Bearer $IAM_TOKEN" \
          --header "Content-Type: application/json" \
          --url 'https://mdb.api.cloud.yandex.net/managed-clickhouse/v1/clusters/<cluster_ID>' \
          --data '{
                    "updateMask": "configSpec.backupRetainPeriodDays",
                    "configSpec": {
                      "backupRetainPeriodDays": <number_of_days>
                    }
                  }'
      ```

      Where:

      * `updateMask`: Comma-separated string of settings to update.

        Here, we only specified a single setting, `configSpec.backupRetainPeriodDays`.

      * `configSpec.backupRetainPeriodDays`: New automatic backup retention period, in days.

      You can request the cluster ID with the [list of clusters in the folder](cluster-list.md#list-clusters).

  1. View the [server response](../api-ref/Cluster/update.md#yandex.cloud.operation.Operation) to make sure your request was successful.

- gRPC API {#grpc-api}

  1. [Get an IAM token for API authentication](../api-ref/authentication.md) and put it into an environment variable:

      ```bash
      export IAM_TOKEN="<IAM_token>"
      ```

  1. Clone the [cloudapi](https://github.com/yandex-cloud/cloudapi) repository:
     
     ```bash
     cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi
     ```
     
     Below, we assume that the repository contents reside in the `~/cloudapi/` directory.
  1. Call the [ClusterService.Update](../api-ref/grpc/Cluster/update.md) method, e.g., via the following [gRPCurl](https://github.com/fullstorydev/grpcurl) request:

      {% note warning %}
      
      The API method will assign default values to all the parameters of the object you are modifying unless you explicitly provide them in your request. To avoid this, list the settings you want to change in the `update_mask` parameter as an array of `paths[]` strings.
      
      {% cut "Format for listing settings" %}
      
      ```yaml
      "update_mask": {
          "paths": [
              "<setting_1>",
              "<setting_2>",
              ...
              "<setting_N>"
          ]
      }
      ```
      
      {% endcut %}
      
      {% endnote %}

      ```bash
      grpcurl \
          -format json \
          -import-path ~/cloudapi/ \
          -import-path ~/cloudapi/third_party/googleapis/ \
          -proto ~/cloudapi/yandex/cloud/mdb/clickhouse/v1/cluster_service.proto \
          -rpc-header "Authorization: Bearer $IAM_TOKEN" \
          -d '{
                  "cluster_id": "<cluster_ID>",
                  "update_mask": {
                    "paths": [
                      "config_spec.backup_retain_period_days"
                    ]
                  },
                  "config_spec": {
                    "backup_retain_period_days": <number_of_days>
                  }
                }' \
          mdb.api.cloud.yandex.net:443 \
          yandex.cloud.mdb.clickhouse.v1.ClusterService.Update
      ```

      Where:

      * `update_mask`: List of settings to update as an array of strings (`paths[]`).

        Here, we only specified a single setting, `config_spec.backup_retain_period_days`.

      * `config_spec.backup_retain_period_days`: New automatic backup retention period, in days.

      You can request the cluster ID with the [list of clusters in the folder](cluster-list.md#list-clusters).

  1. Check the [server response](../api-ref/grpc/Cluster/update.md#yandex.cloud.operation.Operation) to make sure your request was successful.

{% endlist %}

## Deleting a backup {#delete-backup}

{% note warning %}

You can only delete manual backups.

{% endnote %}

{% list tabs group=instructions %}

- Management console {#console}

  1. In the [management console](https://console.yandex.cloud), select the folder containing the cluster.
  1. Navigate to **Managed Service for&nbsp;ClickHouse**.
  1. Click the name of your cluster and select the **Backups** tab.
  1. Click ![image](../../_assets/console-icons/ellipsis.svg) for the backup in question and select **Delete backup**.

- CLI {#cli}
  
  If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../cli/quickstart.md#install).
  
  The folder used by default is the one specified when [creating](../../cli/operations/profile/profile-create.md) the CLI profile. To change the default folder, use the `yc config set folder-id <folder_ID>` command. You can also specify a different folder for any command using `--folder-name` or `--folder-id`. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.
  
  To delete a cluster backup:
  
  1. View the description of the CLI command for deleting a ClickHouse® cluster backup:
  
      ```bash
      yc managed-clickhouse backup delete --help
      ```
  
  1. Send the following request to delete a backup, specifying the backup ID:
  
      ```bash
      yc managed-clickhouse backup delete <cluster_ID>:<backup_ID>
      ```

      You can get the cluster ID and backup ID with the [list of backups](#list-backups).

- REST API {#api}

  1. [Get an IAM token for API authentication](../api-ref/authentication.md) and put it into an environment variable:

     ```bash
     export IAM_TOKEN="<IAM_token>"
     ```

  1. Call the [Backup.Delete](../api-ref/Backup/delete.md) method, e.g., via the following [cURL](https://curl.se/) request:

     ```bash
     curl \
       --request DELETE \
       --header "Authorization: Bearer $IAM_TOKEN" \
       --url 'https://mdb.api.cloud.yandex.net/managed-clickhouse/v1/backups/<cluster_ID>:<backup_ID>'
     ```

     You can get the cluster ID and backup ID with the [list of backups](#list-backups).

  1. View the [server response](../api-ref/Backup/delete.md#yandex.cloud.operation.Operation) to make sure your request was successful.

- gRPC API {#grpc-api}

  1. [Get an IAM token for API authentication](../api-ref/authentication.md) and put it into an environment variable:

     ```bash
     export IAM_TOKEN="<IAM_token>"
     ```

  1. Clone the [cloudapi](https://github.com/yandex-cloud/cloudapi) repository:
     
     ```bash
     cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi
     ```
     
     Below, we assume that the repository contents reside in the `~/cloudapi/` directory.
  1. Call the [BackupService.Delete](../api-ref/grpc/Backup/delete.md) method, e.g., via the following [gRPCurl](https://github.com/fullstorydev/grpcurl) request:

     ```bash
     grpcurl \
       -format json \
       -import-path ~/cloudapi/ \
       -import-path ~/cloudapi/third_party/googleapis/ \
       -proto ~/cloudapi/yandex/cloud/mdb/clickhouse/v1/backup_service.proto \
       -rpc-header "Authorization: Bearer $IAM_TOKEN" \
       -d '{
             "backup_id": "<cluster_ID>:<backup_ID>"
           }' \
       mdb.api.cloud.yandex.net:443 \
       yandex.cloud.mdb.clickhouse.v1.BackupService.Delete
     ```

     You can get the cluster ID and backup ID with the [list of backups](#list-backups).

  1. View the [server response](../api-ref/grpc/Backup/delete.md#yandex.cloud.operation.Operation) to make sure your request was successful.

{% endlist %}  

_ClickHouse® is a registered trademark of [ClickHouse, Inc](https://clickhouse.com)._