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

# Updating ClickHouse® cluster settings

After creating a cluster, you can:

* [Change the service account settings](#change-service-account).
* [Change the host class](#change-resource-preset).
* [Change the disk type and expand the storage capacity](#change-disk-size).
* [Enable the coordination service](#coordination).
* [Enable user and database management via SQL](#SQL-management).
* [Change additional cluster settings](#change-additional-settings).
* [Move the cluster](#move-cluster) to another folder.
* [Change cluster security groups](#change-sg-set).
* [Change the hybrid storage settings](#change-hybrid-storage).

Learn more about other cluster updates:

* [Setting up maintenance](cluster-maintenance.md).
* [Migrating a cluster to a different availability zone](host-migration.md).
* [Configuring ClickHouse® servers](change-server-level-settings.md) as described in [this ClickHouse® article](https://clickhouse.com/docs/enen/operations/server-configuration-parameters/settings).
* [Changing ClickHouse® settings at the query level](change-query-level-settings.md).


## Changing the service account settings {#change-service-account}


To attach a service account to a Managed Service for ClickHouse® cluster, [assign](../../iam/operations/roles/grant.md) the [iam.serviceAccounts.user](../../iam/security/index.md#iam-serviceAccounts-user) role or higher to your Yandex Cloud account.


{% note warning %}

If the cluster already uses a service account to access objects from Object Storage, then changing it to a different service account may make these objects unavailable and interrupt the cluster operation. Before changing the service account settings, make sure that the cluster doesn't use the objects in question.

{% endnote %}

{% list tabs group=instructions %}

- Management console {#console}

    To change the service account settings:

    1. In the [management console](https://console.yandex.cloud), select the folder containing the cluster.
    1. Navigate to **Managed Service for ClickHouse**.
    1. Select your cluster and click **Edit** in the top panel.
    1. Under **Service settings**, select your service account from the list or [create a new one](../../iam/operations/sa/create.md). For more information about setting up a service account, see [Configuring access to Object Storage from a ClickHouse® cluster](s3-access.md).

{% endlist %}


## Changing the host class {#change-resource-preset}

{% note info %}

You cannot use ZooKeeper hosts in clusters with ClickHouse® Keeper support. For more information, see [Coordination services](../concepts/coordination-system.md).

{% endnote %}

When changing the host class:

* A single-host cluster will be unavailable for a few minutes and all database connections will be dropped.
* In a multi-host cluster, hosts will be stopped and updated one by one. When stopped, a host will be unavailable for a few minutes.
* A cluster with local SSD storage may be unavailable for an extended period, as data migration to another physical server may be required.
* Using a [special FQDN](connect/fqdn.md#auto) does not guarantee a stable database connection: user sessions may be terminated.

We recommend changing the host class only when your cluster has no active workload.

You can also [change the host class for an individual shard](shards.md#shard-update).

The host class affects the RAM amount ClickHouse® can use. For more information, see [Memory management](../concepts/memory-management.md).

The minimum number of cores per ZooKeeper host depends on the total number of cores on ClickHouse® hosts. For more information, see [Coordination services](../concepts/coordination-system.md#zk).

{% 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. Select your cluster and click **Edit** in the top panel.
  1. To change the ClickHouse® host class, select the platform, VM type, and required host class under **Resources**.
  1. To change the ZooKeeper host class, select the platform, VM type, and required ZooKeeper host class under **ZooKeeper host class**.
  1. Click **Save changes**.

- 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 change the cluster’s [host class](../concepts/instance-types.md):

  1. View the description of the CLI command for updating a cluster:

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

  1. Get the list of available host classes. The `ZONE IDS` column lists the availability zones where you can select the appropriate class:

     
     ```bash
     yc managed-clickhouse resource-preset list

     +-----------+--------------------------------+-------+----------+
     |    ID     |            ZONE IDS            | CORES |  MEMORY  |
     +-----------+--------------------------------+-------+----------+
     | s1.micro  | ru-central1-a, ru-central1-b,  |     2 | 8.0 GB   |
     |           | ru-central1-d                  |       |          |
     | ...                                                           |
     +-----------+--------------------------------+-------+----------+
     ```


  1. Specify the relevant class in the cluster update command:

     ```bash
     yc managed-clickhouse cluster update <cluster_name_or_ID> \
        --clickhouse-resource-preset=<class_ID>
     ```

     Managed Service for ClickHouse® will start updating the host class for your cluster.

  1. To change the class of a ZooKeeper host, provide the value you need in the `--zookeeper-resource-preset` parameter.


- Terraform {#tf}

    1. Open the current Terraform configuration file with the infrastructure plan.

        For more on how to create such a file, see the [Creating a cluster](cluster-create.md) section.

    1. In the Managed Service for ClickHouse® cluster description, change the `resource_preset_id` value in the `clickhouse.resources` and `zookeeper.resources` sections for ClickHouse® and ZooKeeper hosts, respectively:

        ```hcl
        resource "yandex_mdb_clickhouse_cluster_v2" "<cluster_name>" {
          ...
          clickhouse = {
            resources = {
              resource_preset_id = "<ClickHouse®_host_class>"
              ...
            }
          }
          zookeeper = {
            resources = {
              resource_preset_id = "<ZooKeeper_host_class>"
              ...
            }
          }
        }
        ```

    1. Make sure the settings are correct.

        1. In the command line, navigate to the directory that contains the current Terraform configuration files defining the infrastructure.
        1. Run this command:
        
           ```bash
           terraform validate
           ```
        
           Terraform will show any errors found in your configuration files.

    1. Confirm resource changes.

        1. Run this command to view the planned changes:
        
           ```bash
           terraform plan
           ```
        
           If you described the configuration correctly, the terminal will display a list of the resources to update and their parameters. This is a verification step that does not apply changes to your resources.
        
        1. If everything looks correct, apply the changes:
           1. Run this command:
        
              ```bash
              terraform apply
              ```
        
           1. Confirm updating the resources.
           1. Wait for the operation to complete.

    For more information, see [this Terraform provider guide](../../terraform/resources/mdb_clickhouse_cluster.md).

    {% note warning "Timeouts" %}
    
    The Terraform provider sets the following timeouts for Managed Service for ClickHouse® cluster operations:
    
    * Creating a cluster, including by restoring from a backup: 60 minutes.
    * Updating a cluster: 90 minutes.
    * Deleting a cluster: 30 minutes.
    
    Operations exceeding the timeout are aborted.
    
    {% cut "How to change these limits" %}
    
    Add the `timeouts` section to your cluster description, such as the following:
    
    ```hcl
    resource "yandex_mdb_clickhouse_cluster_v2" "<cluster_name>" {
      ...
      timeouts = {
        create = "1h30m" # 1 hour 30 minutes
        update = "2h"    # 2 hours
        delete = "30m"   # 30 minutes
      }
    }
    ```
    
    {% endcut %}
    
    {% endnote %}


- 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. Get the list of available host classes:

        1. Call the [ResourcePreset.List](../api-ref/ResourcePreset/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/resourcePresets'
            ```

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

    1. Change the host class as appropriate:

        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.clickhouse.resources.resourcePresetId,configSpec.zookeeper.resources.resourcePresetId",
                          "configSpec": {
                            "clickhouse": {
                              "resources": {
                                "resourcePresetId": "<ClickHouse®_host_class_ID>"
                              }
                            },
                            "zookeeper": {
                              "resources": {
                                "resourcePresetId": "<ZooKeeper_host_class_ID>"
                              }
                            }
                          }
                        }'
            ```

            Where:

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

                Specify the relevant parameters:
                * `configSpec.clickhouse.resources.resourcePresetId`: To change the ClickHouse® host class.
                * `configSpec.zookeeper.resources.resourcePresetId`: To change the ZooKeeper host class.

                In our request example, we are changing the host class for both ClickHouse® and ZooKeeper hosts.

            * `configSpec.clickhouse.resources.resourcePresetId`: ClickHouse® host class ID.
            * `configSpec.zookeeper.resources.resourcePresetId`: ZooKeeper host class ID.

            You can get the cluster ID with the [list of clusters in the folder](cluster-list.md#list-clusters). Earlier, you already obtained the list of available host classes with their IDs.

        1. Check 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. Get the list of available host classes:

        1. Call the [ResourcePresetService.List](../api-ref/grpc/ResourcePreset/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/resource_preset_service.proto \
                -rpc-header "Authorization: Bearer $IAM_TOKEN" \
                mdb.api.cloud.yandex.net:443 \
                yandex.cloud.mdb.clickhouse.v1.ResourcePresetService.List
            ```

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

    1. Change the host class as appropriate:

        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.clickhouse.resources.resource_preset_id",
                          "config_spec.zookeeper.resources.resource_preset_id"
                        ]
                      },
                      "config_spec": {
                        "clickhouse": {
                          "resources": {
                            "resource_preset_id": "<ClickHouse®_host_class_ID>"
                          }
                        },
                        "zookeeper": {
                          "resources": {
                            "resource_preset_id": "<ZooKeeper_host_class_ID>"
                          }
                        }
                      }
                    }' \
                mdb.api.cloud.yandex.net:443 \
                yandex.cloud.mdb.clickhouse.v1.ClusterService.Update
            ```

            Where:

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

                Specify the relevant parameters:
                * `config_spec.clickhouse.resources.resource_preset_id`: To change the ClickHouse® host class.
                * `config_spec.zookeeper.resources.resource_preset_id`: To change the ZooKeeper host class.

                In our request example, we are changing the host class for both ClickHouse® and ZooKeeper hosts.

            * `config_spec.clickhouse.resources.resource_preset_id`: ClickHouse® host class ID.
            * `config_spec.zookeeper.resources.resource_preset_id`: ZooKeeper host class ID.

            You can get the cluster ID with the [list of clusters in the folder](cluster-list.md#list-clusters). Earlier, you already obtained the list of available host classes with their IDs.

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

{% endlist %}

## Changing the disk type and increasing the storage size {#change-disk-size}

{% note info %}

You cannot use ZooKeeper hosts in clusters with ClickHouse® Keeper support. For more information, see [Coordination services](../concepts/coordination-system.md).

{% endnote %}

Make sure the cloud has enough quota to increase the storage size. Open the cloud's [Quotas](https://console.yandex.cloud/cloud?section=quotas) page and check the **HDD storage capacity** and **SSD storage capacity** lines under **Managed Databases** to make sure there is available quota for storage space.

{% note warning %}

When you change the disk type, the cluster hosts get recreated. The system automatically saves the replicated tables data. The non-replicated tables data will be lost. If you need to preserve data in non-replicated tables, [convert it to replicated](https://clickhouse.com/docs/enen/sql-reference/statements/attach#attach-mergetree-table-as-replicatedmergetree) before you change the disk type.

{% endnote %}

When changing the disk type or storage size, a cluster with local SSD storage may be unavailable for an extended period, as data migration to another physical server may be required.

You can also [change the disk type and storage size for an individual shard](shards.md#shard-update).

{% list tabs group=instructions %}

- Management console {#console}

  To change the disk type and expand the storage size for a 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. Select your cluster and click **Edit** in the top panel.
  1. To change the disk type and increase the storage size for your ClickHouse® hosts, select the appropriate values under **Storage size**.
  1. To change the disk type and increase the storage size for your ClickHouse® Keeper or ZooKeeper hosts, select the appropriate values under **ZooKeeper storage size** or **ClickHouse Keeper storage size**, respectively.
  1. Click **Save changes**.
  1. If you have changed the disk type for ClickHouse® hosts:
      1. In the window that opens, view the number of non-replicated tables in the **Non-replicated MergeTree tables** chart and their size in **Size of non-replicated MergeTree tables**. The data in non-replicated tables will be lost. If you need to keep it, [convert](https://clickhouse.com/docs/enen/sql-reference/statements/attach#attach-mergetree-table-as-replicatedmergetree) your non-replicated tables to replicated ones before changing the disk type.
      1. Confirm resource changes.

- 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 change the disk type and expand the storage size for a cluster:

  1. View the description of the CLI command for updating a cluster:

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

  1. Run the update cluster command, specifying the required [disk type](../concepts/storage.md) and storage size:

     ```bash
     yc managed-clickhouse cluster update <cluster_name_or_ID> \
       --clickhouse-disk-size <storage_size_in_GB> \
       --clickhouse-disk-type <disk_type> \
       --allow-host-recreation
     ```

     When changing the disk type, the `--allow-host-recreation` parameter is required to allow your cluster to recreate the hosts.

          
     The new storage size must be at least as large as the `disk_size` in the cluster properties.


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

  1. To change the disk type and increase the storage size for your ZooKeeper hosts, provide the appropriate values in the `--zookeeper-disk-size` and `--zookeeper-disk-type` parameters.


- Terraform {#tf}

  {% note info %}

  Terraform cannot change the disk type.

  {% endnote %}

  To increase the storage size:

    1. Open the current Terraform configuration file with the infrastructure plan.

        For more on how to create such a file, see the [Creating a cluster](cluster-create.md) section.

    1. In the Managed Service for ClickHouse® cluster description, change the `disk_size` value in the `zookeeper.resources` or `clickhouse.resources` section for ClickHouse® and ZooKeeper hosts, respectively:

        ```hcl
        resource "yandex_mdb_clickhouse_cluster_v2" "<cluster_name>" {
          ...
          clickhouse = {
            resources = {
              disk_size = <storage_size_in_GB>
              ...
            }
          }
          zookeeper = {
            resources = {
              disk_size = <storage_size_in_GB>
              ...
            }
          }
        }
        ```

    1. Make sure the settings are correct.

        1. In the command line, navigate to the directory that contains the current Terraform configuration files defining the infrastructure.
        1. Run this command:
        
           ```bash
           terraform validate
           ```
        
           Terraform will show any errors found in your configuration files.

    1. Confirm resource changes.

        1. Run this command to view the planned changes:
        
           ```bash
           terraform plan
           ```
        
           If you described the configuration correctly, the terminal will display a list of the resources to update and their parameters. This is a verification step that does not apply changes to your resources.
        
        1. If everything looks correct, apply the changes:
           1. Run this command:
        
              ```bash
              terraform apply
              ```
        
           1. Confirm updating the resources.
           1. Wait for the operation to complete.

    For more information, see [this Terraform provider guide](../../terraform/resources/mdb_clickhouse_cluster.md).

    {% note warning "Timeouts" %}
    
    The Terraform provider sets the following timeouts for Managed Service for ClickHouse® cluster operations:
    
    * Creating a cluster, including by restoring from a backup: 60 minutes.
    * Updating a cluster: 90 minutes.
    * Deleting a cluster: 30 minutes.
    
    Operations exceeding the timeout are aborted.
    
    {% cut "How to change these limits" %}
    
    Add the `timeouts` section to your cluster description, such as the following:
    
    ```hcl
    resource "yandex_mdb_clickhouse_cluster_v2" "<cluster_name>" {
      ...
      timeouts = {
        create = "1h30m" # 1 hour 30 minutes
        update = "2h"    # 2 hours
        delete = "30m"   # 30 minutes
      }
    }
    ```
    
    {% endcut %}
    
    {% endnote %}


- 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.clickhouse.resources.diskSize,configSpec.clickhouse.resources.diskTypeId,configSpec.zookeeper.resources.diskSize,configSpec.zookeeper.resources.diskTypeId,allowHostRecreation",
                      "configSpec": {
                        "clickhouse": {
                          "resources": {
                            "diskSize": "<storage_size_in_bytes>",
                            "diskTypeId": "<disk_type>"
                          }
                        },
                        "zookeeper": {
                          "resources": {
                            "diskSize": "<storage_size_in_bytes>",
                            "diskTypeId": "<disk_type>"
                          }
                        }
                      },
                      "allowHostRecreation": "true"
                    }'
        ```

        Where:

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

            Specify the relevant parameters:

            * `configSpec.clickhouse.resources.diskSize,configSpec.clickhouse.resources.diskTypeId`: To change the disk type and increase the storage size for your ClickHouse® hosts.
            * `configSpec.zookeeper.resources.diskSize,configSpec.zookeeper.resources.diskTypeId`: To change the disk type and increase the storage size for your ZooKeeper hosts.

            In our request example, we are resizing the storage and updating the disk type for both ClickHouse® and ZooKeeper hosts.

        * `configSpec.clickhouse.resources.diskSize`: ClickHouse® host storage size, in bytes.
        * `configSpec.clickhouse.resources.diskTypeId`: [Disk type](../concepts/storage.md) of ClickHouse® hosts.
        * `configSpec.zookeeper.resources.diskSize`: ZooKeeper host storage size, in bytes.
        * `configSpec.zookeeper.resources.diskTypeId`: Disk type of ZooKeeper hosts.
        * `allowHostRecreation`: Allows your cluster to recreate the hosts (this parameter is required when changing the disk type).

        You can get 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.clickhouse.resources.disk_size",
                      "config_spec.clickhouse.resources.disk_type_id",
                      "config_spec.zookeeper.resources.disk_size",
                      "config_spec.zookeeper.resources.disk_type_id",
                      "allow_host_recreation"
                    ]
                  },
                  "config_spec": {
                    "clickhouse": {
                      "resources": {
                        "disk_size": "<storage_size_in_bytes>",
                        "disk_type_id": "<disk_type>"
                      }
                    },
                    "zookeeper": {
                      "resources": {
                        "disk_size": "<storage_size_in_bytes>",
                        "disk_type_id": "<disk_type>"
                      }
                    }
                  },
                  "allow_host_recreation": "true"
                }' \
            mdb.api.cloud.yandex.net:443 \
            yandex.cloud.mdb.clickhouse.v1.ClusterService.Update
        ```

        Where:

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

            Specify the relevant parameters:

            * `config_spec.clickhouse.resources.disk_size`: To expand the storage of ClickHouse® hosts.
            * `config_spec.clickhouse.resources.disk_type_id`: To change the disk type for ClickHouse® hosts.
            * `config_spec.zookeeper.resources.disk_size`: To expand the storage of ZooKeeper hosts.
            * `config_spec.zookeeper.resources.disk_type_id`: To change the disk type for ZooKeeper hosts.

            In our request example, we are resizing the storage and updating the disk type for both ClickHouse® and ZooKeeper hosts.

        * `config_spec.clickhouse.resources.disk_size`: ClickHouse® host storage size, in bytes.
        * `config_spec.clickhouse.resources.disk_type_id`: [Disk type](../concepts/storage.md) of ClickHouse® hosts.
        * `config_spec.zookeeper.resources.disk_size`: ZooKeeper host storage size, in bytes.
        * `config_spec.zookeeper.resources.disk_type_id`: Disk type of ZooKeeper hosts.
        * `allow_host_recreation`: Allows your cluster to recreate the hosts (this parameter is required when changing the disk type).

        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 %}

## Enabling the coordination service {#coordination}

You can turn on the ClickHouse® Keeper or ZooKeeper [coordination service](#enable-coordination) if it has not been set. You can [change the settings](#change-coordination) of the active coordination service.

### Turning on the coordination service {#enable-coordination}

{% note warning %}

The ClickHouse® Keeper and ZooKeeper hosts are counted towards the cloud [resource quota](https://console.yandex.cloud/cloud?section=quotas) and [cluster cost calculation](../pricing.md).

{% endnote %}

{% list tabs group=instructions %}

- Management console {#console}

  1. In the [management console](https://console.yandex.cloud), navigate to the folder dashboard and select **Managed Service for&nbsp;ClickHouse**.
  1. Click the cluster name and navigate to the **Hosts** tab.
  1. Click **Set up coordinator service** in the top-right corner of the page.
  1. Under **Main settings**, select the [coordination service](../concepts/coordination-system.md).
  1. Configure the following settings depending on the service you selected:

      * For the **ZooKeeper (on separate hosts)** coordination service:

        * Under **ZooKeeper host class**, select the platform, VM type, and [host class](../concepts/instance-types.md).
        * Under **ZooKeeper storage size**, select the [disk type](../concepts/storage.md) and storage size. Optionally, configure [automatic increase of storage size](../concepts/storage.md#autoscaling) for ZooKeeper.

        * Under **ZooKeeper hosts**:

          * Optionally, change the settings of the automatically added ZooKeeper hosts.

            To change the host settings, click ![pencil](../../_assets/console-icons/pencil.svg) next to the host and specify the following:

            * **Availability zone**: Select the [availability zone](../../overview/concepts/geo-scope.md).
            * **Subnet**: Select the [subnet](../../vpc/concepts/network.md#subnet) in the selected availability zone.

          * To convert non-replicated tables to [replicated](../concepts/replication.md#replicated-tables) ones, enable **Convert non-replicated tables**.

            This will automatically convert non-replicated tables [MergeTree](https://clickhouse.com/docs/enen/engines/table-engines/mergetree-family/mergetree) tables to [ReplicatedMergeTree](https://clickhouse.com/docs/enen/engines/table-engines/mergetree-family/replication)-based replicated ones.

            Once this option is enabled, you cannot disable it.

      * For the **ClickHouse Keeper (on separate hosts)** coordination service:

        * Under **Clickhouse Keeper host class**, select the platform, VM type, and [host class](../concepts/instance-types.md).
        * Under **ClickHouse Keeper storage size**, select the [disk type](../concepts/storage.md) and storage size. Optionally, configure [automatic increase of storage size](../concepts/storage.md#autoscaling) for ClickHouse® Keeper.
        * Under **Clickhouse Keeper hosts**:

          * Optionally, change the settings of the automatically added ClickHouse® Keeper hosts as appropriate.

            To change the host settings, click ![pencil](../../_assets/console-icons/pencil.svg) next to the host and specify the following:

            * **Availability zone**: Select the [availability zone](../../overview/concepts/geo-scope.md).
            * **Subnet**: Select the [subnet](../../vpc/concepts/network.md#subnet) in the selected availability zone.

          * To convert non-replicated tables to [replicated](../concepts/replication.md#replicated-tables) ones, enable **Convert non-replicated tables**.

            This will automatically convert non-replicated tables [MergeTree](https://clickhouse.com/docs/enen/engines/table-engines/mergetree-family/mergetree) tables to [ReplicatedMergeTree](https://clickhouse.com/docs/enen/engines/table-engines/mergetree-family/replication)-based replicated ones.

            Once this option is enabled, you cannot disable it.

  1. Click **Save changes**.

{% endlist %}

### Changing the settings of the active coordination service {#change-coordination}

{% list tabs group=instructions %}

- Management console {#console}

  1. In the [management console](https://console.yandex.cloud), navigate to the folder dashboard and select **Managed Service for&nbsp;ClickHouse**.
  1. Select your cluster and click **Edit** in the top panel.
  1. Configure the following settings depending on the coordination service you selected:

      * For the **ClickHouse Keeper (on separate hosts)** coordination service:

        * Under **Clickhouse Keeper host class**, select the platform, VM type, and [host class](../concepts/instance-types.md).
        * Under **ClickHouse Keeper storage size**, select the [disk type](../concepts/storage.md) and storage size. Optionally, configure [automatic increase of storage size](../concepts/storage.md#autoscaling) for ClickHouse® Keeper.

      * For the **ZooKeeper (on separate hosts)** coordination service:

        * Under **ZooKeeper host class**, select the platform, VM type, and [host class](../concepts/instance-types.md).
        * Under **ZooKeeper storage size**, select the [disk type](../concepts/storage.md) and storage size. Optionally, configure [automatic increase of storage size](../concepts/storage.md#autoscaling) for ZooKeeper.

  1. Click **Save changes**.

{% endlist %}

## Enabling user and database management via SQL {#SQL-management}

In Managed Service for ClickHouse®, you can manage cluster [users](../concepts/user-access-rights.md#sql-user-management) and [databases](databases.md#sql-database-management) via SQL.

{% note alert %}

This disables user and database management through the native Yandex Cloud interfaces, such as the management console, CLI, Terraform, and API.

You cannot disable settings for user or database management via SQL once they are enabled.

{% 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. Select your cluster and click **Edit** in the top panel.
  1. To [manage users via SQL](../concepts/user-access-rights.md#sql-user-management), enable **DBMS settings** under **User management via SQL** and specify the `admin` password.
  1. To [manage databases via SQL](databases.md#sql-database-management), enable **DBMS settings** and **User management via SQL** under **Managing databases via SQL** and specify the `admin` password.
  1. Click **Save changes**.

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

    1. To enable [user management via SQL](../concepts/user-access-rights.md#sql-user-management):

        * Set `--enable-sql-user-management` to `true`.
        * Set a password for `admin` in the `--admin-password` parameter.

        ```bash
        yc managed-clickhouse cluster update <cluster_name_or_ID> \
           ...
           --enable-sql-user-management true \
           --admin-password "<admin_user_password>"
        ```

    1. To enable [database management via SQL](databases.md#sql-database-management):

        * Set `--enable-sql-user-management` and `--enable-sql-database-management` to `true`.
        * Set a password for `admin` in the `--admin-password` parameter.

        ```bash
        yc managed-clickhouse cluster update <cluster_name_or_ID> \
           ...
           --enable-sql-user-management true \
           --enable-sql-database-management true \
           --admin-password "<admin_password>"
        ```


- Terraform {#tf}

    1. Open the current Terraform configuration file with the infrastructure plan.

        For more on how to create such a file, see the [Creating a cluster](cluster-create.md) section.

    1. To enable [user management via SQL](../concepts/user-access-rights.md#sql-user-management), add the `sql_user_management` field set to `true` and the `admin_password` field with the `admin` user's password to the cluster description:
       
       ```hcl
       resource "yandex_mdb_clickhouse_cluster_v2" "<cluster_name>" {
         name                = "<cluster_name>"
         ...
         admin_password      = "<admin_user_password>"
         sql_user_management = true
         ...
       }
       ```

    1. To enable [database management via SQL](databases.md#sql-database-management), add to the cluster description the `sql_user_management` and `sql_database_management` fields set to `true` and the `admin_password` field with the `admin` user password:
       
       ```hcl
       resource "yandex_mdb_clickhouse_cluster_v2" "<cluster_name>" {
         name                    = "<cluster_name>"
         ...
         admin_password          = "<admin_user_password>"
         sql_database_management = true
         sql_user_management     = true
         ...
       }
       ```

    1. Make sure the settings are correct.

        1. In the command line, navigate to the directory that contains the current Terraform configuration files defining the infrastructure.
        1. Run this command:
        
           ```bash
           terraform validate
           ```
        
           Terraform will show any errors found in your configuration files.

    1. Confirm resource changes.

        1. Run this command to view the planned changes:
        
           ```bash
           terraform plan
           ```
        
           If you described the configuration correctly, the terminal will display a list of the resources to update and their parameters. This is a verification step that does not apply changes to your resources.
        
        1. If everything looks correct, apply the changes:
           1. Run this command:
        
              ```bash
              terraform apply
              ```
        
           1. Confirm updating the resources.
           1. Wait for the operation to complete.

    For more information, see [this Terraform provider guide](../../terraform/resources/mdb_clickhouse_cluster.md).

    {% note warning "Timeouts" %}
    
    The Terraform provider sets the following timeouts for Managed Service for ClickHouse® cluster operations:
    
    * Creating a cluster, including by restoring from a backup: 60 minutes.
    * Updating a cluster: 90 minutes.
    * Deleting a cluster: 30 minutes.
    
    Operations exceeding the timeout are aborted.
    
    {% cut "How to change these limits" %}
    
    Add the `timeouts` section to your cluster description, such as the following:
    
    ```hcl
    resource "yandex_mdb_clickhouse_cluster_v2" "<cluster_name>" {
      ...
      timeouts = {
        create = "1h30m" # 1 hour 30 minutes
        update = "2h"    # 2 hours
        delete = "30m"   # 30 minutes
      }
    }
    ```
    
    {% endcut %}
    
    {% endnote %}


- 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.adminPassword,configSpec.sqlUserManagement,configSpec.sqlDatabaseManagement",
                      "configSpec": {
                        "adminPassword": "<admin_user_password>",
                        "sqlUserManagement": <user_management_via_SQL>,
                        "sqlDatabaseManagement": <database_management_via_SQL>
                      }
                    }'
        ```

        Where:

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

            Specify the relevant parameters:

            * `configSpec.adminPassword`: Password of the `admin` account used for management.
            * `configSpec.sqlUserManagement`: To enable user management via SQL.
            * `configSpec.sqlDatabaseManagement`: To enable database management via SQL.

            In our request example, both user and database management via SQL are enabled.

        * `configSpec.adminPassword`: `admin` password.
        * `configSpec.sqlUserManagement`: User management via SQL, `true` or `false`.
        * `configSpec.sqlDatabaseManagement`: Database management via SQL, `true` or `false`. For that, you also need to enable user management via SQL.

        You can get 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.admin_password",
                      "config_spec.sql_user_management",
                      "config_spec.sql_database_management"
                    ]
                  },
                  "config_spec": {
                    "admin_password": "<admin_user_password>",
                    "sql_user_management": <user_management_via_SQL>,
                    "sql_database_management": <database_management_via_SQL>
                  }
                }' \
            mdb.api.cloud.yandex.net:443 \
            yandex.cloud.mdb.clickhouse.v1.ClusterService.Update
        ```

        Where:

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

            Specify the relevant parameters:

            * `config_spec.admin_password`: Password of the `admin` account used for management.
            * `config_spec.sql_user_management`: To enable user management via SQL.
            * `config_spec.sql_database_management`: To enable database management via SQL.

            In our request example, both user and database management via SQL are enabled.

        * `config_spec.admin_password`: `admin` user password.
        * `config_spec.sql_user_management`: User management via SQL, `true` or `false`.
        * `config_spec.sql_database_management`: Database management via SQL, `true` or `false`. For that, you also need to enable user management via SQL.

        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 %}

## Configuring advanced cluster settings {#change-additional-settings}

{% 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. Select your cluster and click **Edit** in the top panel.
  1. Under **Storage size**:

     * Optionally, configure [automatic increase of storage size](../concepts/storage.md#autoscaling) for ClickHouse®:

       * In the **Increase size** field, select one or both thresholds:
         * **In the maintenance window when full at more than**: Scheduled expansion threshold. When reached, the storage expands during the next [maintenance window](../concepts/maintenance.md#maintenance-window).
           
           For a scheduled expansion, you need to set up a [maintenance window](../concepts/maintenance.md#maintenance-window) schedule.
       
         * **Immediately when full at more than**: Immediate expansion threshold. When reached, the storage expands immediately.
       * Specify a threshold value (as a percentage of the total storage size). If you select both thresholds, make sure the immediate expansion threshold is not less than the scheduled one.
       * Set **Maximum storage size**.

       The automatic storage size increase settings for ClickHouse® apply to all existing shards. New shards will use the settings of the oldest shard.

  1. Under **Service settings**, change the following additional cluster settings:

     * **Backup start time (UTC)**: Time interval during which the cluster backup starts. Time is specified in 24-hour UTC format. The default time is `22:00 - 23:00` UTC.
     
     * **Retention period for automatic backups, days**: Retention period for automatic backups, in days. Backups are automatically deleted once their retention period expires. The default is 7 days. For more information, see [Backups](../concepts/backup.md#storage).
     
         Changing the retention period affects both new and existing automatic backups. For example, the initial retention period was 7 days, and the remaining lifetime of a single automatic backup is 1 day. If the retention period increases to 9 days, the remaining lifetime for this backup will now be 3 days.
     
     * **Maintenance**: [Maintenance](../concepts/maintenance.md) window settings:
     
        * To enable maintenance at any time, select **At any time** (default).
        * To specify the preferred maintenance start time, select **By schedule** and specify the day of the week and the UTC time interval. For example, you can choose a time when the cluster is least loaded.
        
        Both active and stopped clusters are subject to maintenance. Maintenance operations include DBMS updates, patches, etc.
     
     
     * **Service account**: Account user programs can use to manage the cluster. For more information, see [this guide](../security.md).
     
     * **Disk encryption**: This option enables disk encryption with a [custom KMS key](../../kms/concepts/key.md). Set a key in one of the following ways:
     
        * To [create](../../kms/operations/key.md#create) a new key, click **Create**.
     
        * To use a previously created key, select it in the **KMS key** field.
     
        Learn more about disk encryption in [Storage](../concepts/storage.md#disk-encryption).
     
     
     * **DataLens access**: This option enables you to analyze cluster data in [Yandex DataLens](../../datalens/concepts/index.md).
     
     
     * **WebSQL access**: This option enables you to [run SQL queries](web-sql-query.md) against cluster databases from the Yandex Cloud management console using Yandex WebSQL.
     
     
     
     
     * **Access from Metrica and AppMetrica**: This option enables you to [import data from AppMetrica](https://appmetrica.yandex.ru/docs/en/common/cloud) to a cluster.
     
     * **Serverless access**: Enable this option to allow cluster access from [Yandex Cloud Functions](../../functions/concepts/index.md). Learn more about access setup in [this Cloud Functions guide](../../functions/operations/database-connection.md).
     
     
     * **Yandex Query access**: Enable this option to allow cluster access from [Yandex Query](../../query/concepts/index.md). This feature is at the [Preview](../../overview/concepts/launch-stages.md) stage.
     
     * **Deletion protection**: Manages 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.

  1. Click **Save changes**.

- 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 change advanced cluster settings:

    1. View the description of the CLI command for updating a cluster:

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

    1. Run the following command with the list of settings you want to update:

        
        ```bash
        yc managed-clickhouse cluster update <cluster_name_or_ID> \
           --backup-window-start <backup_start_time> \
           --backup-retain-period-days <automatic_backup_retention_period> \
           --datalens-access=<true_or_false> \
           --metrika-access=<true_or_false> \
           --serverless-access=<true_or_false> \
           --websql-access=<true_or_false> \
           --yandexquery-access=<true_or_false> \
           --deletion-protection \
           --disk-size-autoscaling clickhouse-disk-size-limit=<maximum_storage_size_in_GB>,`
                                  `clickhouse-planned-usage-threshold=<scheduled_expansion_threshold_in_percent>,`
                                  `clickhouse-emergency-usage-threshold=<immediate_expansion_threshold_in_percent>,`
                                  `zookeeper-disk-size-limit=<maximum_storage_size_in_GB>,`
                                  `zookeeper-planned-usage-threshold=<scheduled_expansion_threshold_in_percent>,`
                                  `zookeeper-emergency-usage-threshold=<immediate_expansion_threshold_in_percent> \
           --maintenance-window type=<maintenance_type>,`
                               `day=<day_of_week>,`
                               `hour=<hour>
        ```


    You can update the following settings:

    * `--backup-window-start`: The cluster backup start time, set in UTC format `HH:MM:SS`. If the time is not set, the backup will start at 22:00 UTC.

    * `--backup-retain-period-days`: Automatic backup retention period, in days.

    * `--datalens-access`: Enables access from DataLens. The default value is `false`. For more information about setting up a connection, see [Connecting from DataLens](datalens-connect.md).

    
    * `--metrika-access`: Enables [data import from AppMetrica to your cluster](https://appmetrica.yandex.com/docs/common/cloud/about.html). The default value is `false`.

    * `--serverless-access`: Enables access to the cluster from [Yandex Cloud Functions](../../functions/concepts/index.md). The default value is `false`. For more information on configuring access, see [Cloud Functions guides](../../functions/operations/database-connection.md).


    * `--websql-access`: Enables [SQL queries](web-sql-query.md) against cluster databases from the Yandex Cloud management console using Yandex WebSQL. The default value is `false`.


    * `--yandexquery-access=true`: Enables access to the cluster from [Yandex Query](../../query/concepts/index.md). This feature is at the [Preview](../../overview/concepts/launch-stages.md) stage. The default value is `false`.

    * `--deletion-protection`: Cluster protection from accidental deletion, `true` or `false`.

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

    * `--disk-size-autoscaling`: Automatic storage expansion settings:
        
        * `clickhouse-disk-size-limit`: Maximum ClickHouse® storage size, in GB.
        
        * `clickhouse-planned-usage-threshold`: ClickHouse® storage utilization threshold to trigger an increase during the next maintenance window, in percent. The default value is `0` (auto increase disabled).
        
          The valid values range from `0` to `100`.
        
        * `clickhouse-emergency-usage-threshold`: Utilization threshold for the ClickHouse® storage capacity, in percent, to trigger an immediate increase. The default value is `0` (auto increase disabled).
        
          The valid values range from `0` to `100`.
        
        * `zookeeper-disk-size-limit`: Maximum ZooKeeper storage size, in GB.
        
        * `zookeeper-planned-usage-threshold`: ZooKeeper storage utilization threshold to trigger an increase during the next maintenance window, in percent. The default value is `0` (auto increase disabled).
        
          The valid values range from `0` to `100`.
        
        * `zookeeper-emergency-usage-threshold`: Utilization threshold for the ZooKeeper storage capacity, in percent, to trigger an immediate increase. The default value is `0` (auto increase disabled).
        
          The valid values range from `0` to `100`.
        
        {% note warning %}
        
        * If you specify both thresholds for ClickHouse®, `clickhouse-emergency-usage-threshold` must not be less than `clickhouse-planned-usage-threshold`.
        
        * If you specify both thresholds for ZooKeeper, `zookeeper-emergency-usage-threshold` must not be less than `zookeeper-planned-usage-threshold`.
        
        * When using `clickhouse-planned-usage-threshold` and `zookeeper-planned-usage-threshold`, make sure to set up a [maintenance window](../concepts/maintenance.md).
        
        {% endnote %}
    
    * `--maintenance-window`: [Maintenance window](../concepts/maintenance.md) settings (including for stopped clusters), where `type` is the maintenance type:

        * `anytime`: Any time (default).
        * `weekly`: On a schedule. For this value, also specify the following:
            * `day`: Day of week, i.e., `MON`, `TUE`, `WED`, `THU`, `FRI`, `SAT`, or `SUN`.
            * `hour`: Sequence number of UTC hour interval, from `1` to `24`.
        
              > For example, `1` stands for the interval from `00:00` to `01:00`, and `5`, from `04:00` to `05:00`.

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


- Terraform {#tf}

    1. Open the current Terraform configuration file with the infrastructure plan.

        For more on how to create such a file, see the [Creating a cluster](cluster-create.md) section.

    1. To change the backup start time, add the `backup_window_start` section to the Managed Service for ClickHouse® cluster description:

        ```hcl
        resource "yandex_mdb_clickhouse_cluster_v2" "<cluster_name>" {
          ...
          backup_window_start = {
            hours   = <backup_start_hour>
            minutes = <backup_start_minute>
          }
          ...
        }
        ```

    1. To enable cluster access from other services and allow [running SQL queries from the management console](web-sql-query.md) using Yandex WebSQL, edit the values of the appropriate fields in the `access` section:

        ```hcl
        resource "yandex_mdb_clickhouse_cluster_v2" "<cluster_name>" {
          ...
          access = {
            data_lens    = <access_from_DataLens>
            metrika      = <access_from_Metrica_and_AppMetrica>
            serverless   = <access_from_Cloud_Functions>
            web_sql      = <run_SQL_queries_from_management_console>
            yandex_query = <access_from_Yandex_Query>
          }
          ...
        }
        ```

        Where:

        * `data_lens`: Access from DataLens, `true` or `false`.
        * `metrika`: Access from Yandex Metrica and AppMetrica, `true` or `false`.
        * `serverless`: Access from Cloud Functions, `true` or `false`.
        * `yandex_query`: Access from Yandex Query, `true` or `false`.
        * `web_sql`: Running SQL queries from the management console, `true` or `false`.

    1. To set up the [maintenance window](../concepts/maintenance.md) that will also apply to stopped clusters, add the `maintenance_window` section to the cluster description:
       
       ```hcl
       resource "yandex_mdb_clickhouse_cluster_v2" "<cluster_name>" {
         ...
         maintenance_window {
           type = "<maintenance_type>"
           day  = "<day_of_week>"
           hour = <hour>
         }
         ...
       }
       ```
       
       Where:
       
       * `type`: Maintenance type. The possible values include:
           * `ANYTIME`: Any time.
           * `WEEKLY`: On a schedule.
       * `day`: Day of week for the `WEEKLY` type, i.e., `MON`, `TUE`, `WED`, `THU`, `FRI`, `SAT`, or `SUN`.
       * `hour`: Sequence number of UTC hour interval for the `WEEKLY` type, from `1` to `24`.
       
         > For example, `1` stands for the interval from `00:00` to `01:00`, and `5`, from `04:00` to `05:00`.

    1. To activate cluster protection against accidental deletion by a user of your cloud, add the `deletion_protection` field set to `true` to the cluster description:

        ```hcl
        resource "yandex_mdb_clickhouse_cluster_v2" "<cluster_name>" {
          ...
          deletion_protection = <cluster_deletion_protection>
        }
        ```

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

    1. Make sure the settings are correct.

        1. In the command line, navigate to the directory that contains the current Terraform configuration files defining the infrastructure.
        1. Run this command:
        
           ```bash
           terraform validate
           ```
        
           Terraform will show any errors found in your configuration files.

    1. Confirm resource changes.

        1. Run this command to view the planned changes:
        
           ```bash
           terraform plan
           ```
        
           If you described the configuration correctly, the terminal will display a list of the resources to update and their parameters. This is a verification step that does not apply changes to your resources.
        
        1. If everything looks correct, apply the changes:
           1. Run this command:
        
              ```bash
              terraform apply
              ```
        
           1. Confirm updating the resources.
           1. Wait for the operation to complete.

    For more information, see [this Terraform provider guide](../../terraform/resources/mdb_clickhouse_cluster.md).

    {% note warning "Timeouts" %}
    
    The Terraform provider sets the following timeouts for Managed Service for ClickHouse® cluster operations:
    
    * Creating a cluster, including by restoring from a backup: 60 minutes.
    * Updating a cluster: 90 minutes.
    * Deleting a cluster: 30 minutes.
    
    Operations exceeding the timeout are aborted.
    
    {% cut "How to change these limits" %}
    
    Add the `timeouts` section to your cluster description, such as the following:
    
    ```hcl
    resource "yandex_mdb_clickhouse_cluster_v2" "<cluster_name>" {
      ...
      timeouts = {
        create = "1h30m" # 1 hour 30 minutes
        update = "2h"    # 2 hours
        delete = "30m"   # 30 minutes
      }
    }
    ```
    
    {% endcut %}
    
    {% endnote %}


- 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 %}

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

            
            ```json
            {
              "updateMask": "<list_of_settings_to_update>",
              "configSpec": {
                "backupWindowStart": {
                  "hours": "<hours>",
                  "minutes": "<minutes>",
                  "seconds": "<seconds>",
                  "nanos": "<nanoseconds>"
                },
                "clickhouse": {
                  "diskSizeAutoscaling": {
                    "plannedUsageThreshold": "<scheduled_expansion_threshold_in_percent>",
                    "emergencyUsageThreshold": "<immediate_expansion_threshold_in_percent>",
                    "diskSizeLimit": "<maximum_storage_size_in_bytes>"
                  }
                },
                "zookeeper": {
                  "diskSizeAutoscaling": {
                    "plannedUsageThreshold": "<scheduled_expansion_threshold_in_percent>",
                    "emergencyUsageThreshold": "<immediate_expansion_threshold_in_percent>",
                    "diskSizeLimit": "<maximum_storage_size_in_bytes>"
                  }
                },
                "access": {
                  "dataLens": <access_from_DataLens>,
                  "webSql": <run_SQL_queries>,
                  "metrika": <import_data_from_AppMetrica>,
                  "serverless": <access_from_Yandex Cloud Functions>,
                  "dataTransfer": <access_from_Yandex Data Transfer>,
                  "yandexQuery": <access_from_Yandex Query>
                }    
              },
              "maintenanceWindow": {
                "anytime": {},
                "weeklyMaintenanceWindow": {
                  "day": "<day_of_week>",
                  "hour": "<hour_UTC>"
                }
              },
              "deletionProtection": <cluster_deletion_protection>
            }
            ```


            Where:

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

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

            * `configSpec.access`: Settings enabling cluster access from other services and [running SQL queries from the management console](web-sql-query.md) using Yandex WebSQL:

                * `dataLens`: Enable access from DataLens, `true` or `false`. The default value is `false`. For more information about setting up a connection, see [Connecting from DataLens](datalens-connect.md).
                
                * `webSql`: Enable [SQL queries](web-sql-query.md) against cluster databases from the Yandex Cloud management console using Yandex WebSQL, `true` or `false`. The default value is `false`.
                
                
                * `metrika`: Enable [data import from AppMetrica to your cluster](https://appmetrica.yandex.com/docs/common/cloud/about.html), `true` or `false`. The default value is `false`.
                
                * `serverless`: Enable access to the cluster from [Yandex Cloud Functions](../../functions/concepts/index.md), `true` or `false`. The default value is `false`. Learn more about access setup in [this Cloud Functions guide](../../functions/operations/database-connection.md).
                
                * `dataTransfer`: Enable access to the cluster from [Yandex Data Transfer](../../data-transfer/concepts/index.md) in Serverless mode, `true` or `false`. The default value is `false`.
                
                    This will enable you to connect to Yandex Data Transfer running in Kubernetes via a special network to make other operations, e.g., transfer launch and deactivation, run faster.
                
                
                * `yandexQuery`: Enable access to the cluster from [Yandex Query](../../query/concepts/index.md), `true` or `false`. This feature is at the [Preview](../../overview/concepts/launch-stages.md) stage. The default value is `false`.

            * `configSpec.clickhouse.diskSizeAutoscaling`: Automatic storage size increase settings for ClickHouse®:
            
                * `plannedUsageThreshold`: Utilization threshold for the ClickHouse® storage capacity, in percent, to trigger an increase during the next maintenance window. The default value is `0` (auto increase disabled).
                
                  The valid values range from `0` to `100`.
                
                * `emergencyUsageThreshold`: Utilization threshold for the ClickHouse® storage capacity, in percent, to trigger an immediate increase. The default value is `0` (auto increase disabled).
                
                  The valid values range from `0` to `100`.
                
                * `diskSizeLimit`: Maximum ClickHouse® storage size, in bytes.
                
                {% note warning %}
                
                * If you specify both thresholds, `emergencyUsageThreshold` must not be less than `plannedUsageThreshold`.
                
                * When using `plannedUsageThreshold`, make sure to set up a [maintenance window](../concepts/maintenance.md).
                
                {% endnote %}
                
                The automatic storage expansion settings for ClickHouse® apply to all existing shards. If you add a new shard, it will use the settings of the oldest shard. These values are not saved in the ClickHouse® configuration.
                
                To view information about a specific shard, including automatic storage size increase settings, use the [Cluster.GetShard](../api-ref/Cluster/getShard.md) method and provide the cluster ID and shard name in the request.
                
                You can get the cluster ID with the [list of clusters](cluster-list.md#list-clusters) in the folder.
                
                You can get the shard name with the [list of shards](shards.md#list-shards) in the cluster.
            
            * `configSpec.zookeeper.diskSizeAutoscaling`: Automatic storage expansion settings for ZooKeeper:
                      
                * `plannedUsageThreshold`: Utilization threshold for the ZooKeeper storage capacity, in percent, to trigger an increase during the next maintenance window. The default value is `0` (auto increase disabled).
                                      
                  The valid values range from `0` to `100`.
                                      
                * `emergencyUsageThreshold`: Utilization threshold for the ZooKeeper storage capacity, in percent, to trigger an immediate increase. The default value is `0` (auto increase disabled).
                                      
                  The valid values range from `0` to `100`.
                                      
                * `diskSizeLimit`: Maximum ZooKeeper storage size, in bytes.
                                      
                {% note warning %}
                                      
                * If you specify both thresholds, `emergencyUsageThreshold` must not be less than `plannedUsageThreshold`.
                                      
                * When using `plannedUsageThreshold`, make sure to set up a [maintenance window](../concepts/maintenance.md).
                                      
                {% endnote %}
            
            * `maintenanceWindow`: [Maintenance](../concepts/maintenance.md) window settings, including for stopped clusters. Select one of these options:

                * `anytime`: At any time (default).
                * `weeklyMaintenanceWindow`: On schedule:
                    * `day`: Day of week in `DDD` format, i.e., `MON`, `TUE`, `WED`, `THU`, `FRI`, `SAT`, or `SUN`.
                    * `hour`: Time of day (UTC) in `HH` format, from `1` to `24`.

            * `deletionProtection`: Cluster protection against accidental deletion, `true` or `false`. The default value is `false`.

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

        1. Run this query:

            ```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 '@body.json'
            ```

            You can get 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 %}

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

            
            ```json
            {
              "cluster_id": "<cluster_ID>",
              "update_mask": {
                "paths": [
                  <list_of_settings_to_update>
                ]
              },
              "config_spec": {
                "backup_window_start": {
                  "hours": "<hours>",
                  "minutes": "<minutes>",
                  "seconds": "<seconds>",
                  "nanos": "<nanoseconds>"
                },
                "clickhouse": {
                  "disk_size_autoscaling": {
                    "planned_usage_threshold": "<scheduled_expansion_threshold_in_percent>",
                    "emergency_usage_threshold": "<immediate_expansion_threshold_in_percent>",
                    "disk_size_limit": "<maximum_storage_size_in_bytes>"
                  }
                },
                "zookeeper": {
                  "disk_size_autoscaling": {
                    "planned_usage_threshold": "<scheduled_expansion_threshold_in_percent>",
                    "emergency_usage_threshold": "<immediate_expansion_threshold_in_percent>",
                    "disk_size_limit": "<maximum_storage_size_in_bytes>"
                  }
                },
                "access": {
                  "data_lens": <access_from_DataLens>,
                  "web_sql": <run_SQL_queries>,
                  "metrika": <import_data_from_AppMetrica>,
                  "serverless": <access_from_Yandex Cloud Functions>,
                  "data_transfer": <access_from_Yandex Data Transfer>,
                  "yandex_query": <access_from_Yandex Query>
                }
              },
              "maintenance_window": {
                "anytime": {},
                "weekly_maintenance_window": {
                  "day": "<day_of_week>",
                  "hour": "<hour_UTC>"
                }
              },
              "deletion_protection": <cluster_deletion_protection>
            }
            ```


            Where:

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

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

            * `config_spec.access`: Settings enabling cluster access from other services and [running SQL queries from the management console](web-sql-query.md) using Yandex WebSQL:

                * `data_lens`: Enable access from DataLens, `true` or `false`. The default value is `false`. For more information about setting up a connection, see [Connecting from DataLens](datalens-connect.md).
                
                * `web_sql`: Enable [SQL queries](web-sql-query.md) against cluster databases from the Yandex Cloud management console using Yandex WebSQL, `true` or `false`. The default value is `false`.
                
                
                * `metrika`: Enable [data import from AppMetrica to your cluster](https://appmetrica.yandex.com/docs/common/cloud/about.html), `true` or `false`. The default value is `false`.
                
                * `serverless`: Enable access to the cluster from [Yandex Cloud Functions](../../functions/concepts/index.md), `true` or `false`. The default value is `false`. Learn more about access setup in [this Cloud Functions guide](../../functions/operations/database-connection.md).
                
                * `data_transfer`: Enable access to the cluster from [Yandex Data Transfer](../../data-transfer/concepts/index.md) in Serverless mode, `true` or `false`. The default value is `false`.
                
                    This will enable you to connect to Yandex Data Transfer running in Kubernetes via a special network to make other operations, e.g., transfer launch and deactivation, run faster.
                
                
                * `yandex_query`: Enable access to the cluster from [Yandex Query](../../query/concepts/index.md), `true` or `false`. This feature is at the [Preview](../../overview/concepts/launch-stages.md) stage. The default value is `false`.

            * `config_spec.clickhouse.disk_size_autoscaling`: Automatic storage expansion settings for ClickHouse®:
            
                * `planned_usage_threshold`: Utilization threshold for the ClickHouse® storage capacity, in percent, to trigger an expansion during the next maintenance window. The default value is `0` (auto increasing disabled).
                                      
                  The valid values range from `0` to `100`.
                                      
                * `emergency_usage_threshold`: Utilization threshold for the ClickHouse® storage capacity, in percent, to trigger an immediate expansion. The default value is `0` (auto increasing disabled).
                                      
                  The valid values range from `0` to `100`.
                                      
                * `disk_size_limit`: Maximum ClickHouse® storage size, in bytes.
                                      
                {% note warning %}
                                      
                * If you specify both thresholds, `emergency_usage_threshold` must not be less than `planned_usage_threshold`.
                                      
                * When using `planned_usage_threshold`, make sure to set up a [maintenance window](../concepts/maintenance.md).
                                      
                {% endnote %}
                                      
                The automatic storage size increase settings for ClickHouse® apply to all existing shards. If you add a new shard, it will use the settings of the oldest shard. These values are not saved in the ClickHouse® configuration.
                                      
                To view information about a specific shard, including automatic storage expansion settings, use the [ClusterService.GetShard](../api-ref/grpc/Cluster/getShard.md) method and provide the cluster ID and shard name in the request.
                                      
                You can get the cluster ID with the [list of clusters](cluster-list.md#list-clusters) in the folder.
                
                You can get the shard name with the [list of shards](shards.md#list-shards) in the cluster.

            * `config_spec.zookeeper.disk_size_autoscaling`: Automatic storage expansion settings for ZooKeeper:
                      
                * `planned_usage_threshold`: Utilization threshold for the ZooKeeper storage capacity, in percent, to trigger an increase during the next maintenance window. The default value is `0` (auto increase disabled).
                                      
                  The valid values range from `0` to `100`.
                                      
                * `emergency_usage_threshold`: Utilization threshold for the ZooKeeper storage capacity, in percent, to trigger an immediate increase. The default value is `0` (auto increase disabled).
                                      
                  The valid values range from `0` to `100`.
                                      
                * `disk_size_limit`: Maximum ZooKeeper storage size, in bytes.
                                      
                {% note warning %}
                                      
                * If you specify both thresholds, `emergency_usage_threshold` must not be less than `planned_usage_threshold`.
                                      
                * When using `planned_usage_threshold`, make sure to set up a [maintenance window](../concepts/maintenance.md).
                                      
                {% endnote %}

            * `maintenance_window`: [Maintenance](../concepts/maintenance.md) window settings, applying to both running and stopped clusters. Select one of these options:

                * `anytime`: At any time (default).
                * `weekly_maintenance_window`: On schedule:
                    * `day`: Day of week in `DDD` format, i.e., `MON`, `TUE`, `WED`, `THU`, `FRI`, `SAT`, or `SUN`.
                    * `hour`: Time of day (UTC) in `HH` format, from `1` to `24`.

            * `deletion_protection`: Cluster protection against accidental deletion, `true` or `false`. The default value is `false`.

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

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

        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.Update \
              < body.json
            ```

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

{% endlist %}


### Connection Manager {#conn-man}

If you cluster has no integration with Connection Manager, enable **Use Connection Manager**. You can only do it in the [management console](https://console.yandex.cloud).

The following resources will be created for each database user:

* [Connection Manager connection](../../metadata-hub/concepts/connection-manager.md) containing database connection details.

* [Yandex Lockbox secret](../../metadata-hub/concepts/secret.md) containing the user password. Yandex Lockbox provides secure storage for passwords.

  The connection and secret will be created for each new database user. To view all connections, open the **Connections** tab on the cluster page.

  You need the `connection-manager.viewer` role to view the connection details. You can [use Connection Manager](../../metadata-hub/operations/connection-access.md) to configure access to connections.

  {% note info %}

  Connection Manager and any secrets created with it are free of charge.

  {% endnote %}


## Moving a cluster {#move-cluster}

{% 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 ![image](../../_assets/console-icons/ellipsis.svg) next to the cluster you want to move.
    1. Select **Move**.
    1. Select the folder you want to move your cluster to.
    1. Click **Move**.

- 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 move a cluster:

    1. View the description of the CLI command for moving a cluster:

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

    1. Specify the destination folder in the cluster move command:

        ```bash
        yc managed-clickhouse cluster move <cluster_name_or_ID> \
           --destination-folder-name=<destination_folder_name>
        ```

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


- Terraform {#tf}

    1. Open the current Terraform configuration file with the infrastructure plan.

        For more on how to create this file, see [Creating a cluster](cluster-create.md).

    1. In the Managed Service for ClickHouse® cluster description, add or update the `folder_id` argument:

        ```hcl
        resource "yandex_mdb_clickhouse_cluster_v2" "<cluster_name>" {
          ...
          folder_id = "<destination_folder_ID>"
        }
        ```

    1. Make sure the settings are correct.

        1. In the command line, navigate to the directory that contains the current Terraform configuration files defining the infrastructure.
        1. Run this command:
        
           ```bash
           terraform validate
           ```
        
           Terraform will show any errors found in your configuration files.

    1. Confirm resource changes.

        1. Run this command to view the planned changes:
        
           ```bash
           terraform plan
           ```
        
           If you described the configuration correctly, the terminal will display a list of the resources to update and their parameters. This is a verification step that does not apply changes to your resources.
        
        1. If everything looks correct, apply the changes:
           1. Run this command:
        
              ```bash
              terraform apply
              ```
        
           1. Confirm updating the resources.
           1. Wait for the operation to complete.

    For more information, see [this Terraform provider guide](../../terraform/resources/mdb_clickhouse_cluster.md).

    {% note warning "Timeouts" %}
    
    The Terraform provider sets the following timeouts for Managed Service for ClickHouse® cluster operations:
    
    * Creating a cluster, including by restoring from a backup: 60 minutes.
    * Updating a cluster: 90 minutes.
    * Deleting a cluster: 30 minutes.
    
    Operations exceeding the timeout are aborted.
    
    {% cut "How to change these limits" %}
    
    Add the `timeouts` section to your cluster description, such as the following:
    
    ```hcl
    resource "yandex_mdb_clickhouse_cluster_v2" "<cluster_name>" {
      ...
      timeouts = {
        create = "1h30m" # 1 hour 30 minutes
        update = "2h"    # 2 hours
        delete = "30m"   # 30 minutes
      }
    }
    ```
    
    {% endcut %}
    
    {% endnote %}


- 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.Move](../api-ref/Cluster/move.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>:move' \
            --data '{
                      "destinationFolderId": "<destination_folder_ID>"
                    }'
        ```

        Where `destinationFolderId` is the ID of the destination folder to move your cluster to. You can get this ID with the [list of folders in the cloud](../../resource-manager/operations/folder/get-id.md).

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

    1. View the [server response](../api-ref/Cluster/move.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.Move](../api-ref/grpc/Cluster/move.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>",
                  "destination_folder_id": "<destination_folder_ID>"
                }' \
            mdb.api.cloud.yandex.net:443 \
            yandex.cloud.mdb.clickhouse.v1.ClusterService.Move
        ```

        Where `destination_folder_id` is the ID of the destination folder to move your cluster to. You can get this ID with the [list of folders in the cloud](../../resource-manager/operations/folder/get-id.md).

        You can get 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/move.md#yandex.cloud.operation.Operation) to make sure your request was successful.

{% endlist %}


## Updating security groups {#change-sg-set}

{% 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. Select your cluster and click **Edit** in the top panel.
  1. Under **Network settings**, select the security groups for cluster network traffic.

- 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 change the list of [security groups](../concepts/network.md#security-groups) for your cluster:

  1. View the description of the CLI command for updating a cluster:

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

  1. Specify the security groups in the cluster update command:

      ```bash
      yc managed-clickhouse cluster update <cluster_name> \
         --security-group-ids <list_of_security_group_IDs>
      ```

- Terraform {#tf}

    1. Open the current Terraform configuration file with the infrastructure plan.

        For more on how to create such a file, see the [Creating a cluster](cluster-create.md) section.

    1. Edit the `security_group_ids` value in the cluster description:

        ```hcl
        resource "yandex_mdb_clickhouse_cluster_v2" "<cluster_name>" {
          ...
          security_group_ids = [ <list_of_cluster_security_group_IDs> ]
        }
        ```

    1. Make sure the settings are correct.

        1. In the command line, navigate to the directory that contains the current Terraform configuration files defining the infrastructure.
        1. Run this command:
        
           ```bash
           terraform validate
           ```
        
           Terraform will show any errors found in your configuration files.

    1. Confirm resource changes.

        1. Run this command to view the planned changes:
        
           ```bash
           terraform plan
           ```
        
           If you described the configuration correctly, the terminal will display a list of the resources to update and their parameters. This is a verification step that does not apply changes to your resources.
        
        1. If everything looks correct, apply the changes:
           1. Run this command:
        
              ```bash
              terraform apply
              ```
        
           1. Confirm updating the resources.
           1. Wait for the operation to complete.

    For more information, see [this Terraform provider guide](../../terraform/resources/mdb_clickhouse_cluster.md).

    {% note warning "Timeouts" %}
    
    The Terraform provider sets the following timeouts for Managed Service for ClickHouse® cluster operations:
    
    * Creating a cluster, including by restoring from a backup: 60 minutes.
    * Updating a cluster: 90 minutes.
    * Deleting a cluster: 30 minutes.
    
    Operations exceeding the timeout are aborted.
    
    {% cut "How to change these limits" %}
    
    Add the `timeouts` section to your cluster description, such as the following:
    
    ```hcl
    resource "yandex_mdb_clickhouse_cluster_v2" "<cluster_name>" {
      ...
      timeouts = {
        create = "1h30m" # 1 hour 30 minutes
        update = "2h"    # 2 hours
        delete = "30m"   # 30 minutes
      }
    }
    ```
    
    {% endcut %}
    
    {% endnote %}


- 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": "securityGroupIds",
                      "securityGroupIds": [
                        <list_of_security_group_IDs>
                      ]
                    }'
        ```

        Where:

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

            Here, we only specified a single setting, `securityGroupIds`.

        * `securityGroupIds`: Array of strings. Each string is a security group ID.

            {% note warning %}

            The list of security groups assigned to the cluster will be completely overwritten by the list provided in the `securityGroupIds` parameter.

            Before running your request, make sure the list includes all the required security group IDs, including existing ones.

            {% endnote %}

        You can get 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": [
                      "security_group_ids"
                    ]
                  },
                  "security_group_ids": [
                    <list_of_security_group_IDs>
                  ]
                }' \
            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, `security_group_ids`.

        * `security_group_ids`: Array of strings. Each string is a security group ID.

            {% note warning %}

            The list of security groups assigned to the cluster will be completely overwritten by the list provided in the `security_group_ids` parameter.

            Before running your request, make sure the list includes all the required security group IDs, including existing ones.

            {% endnote %}

        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 %}

{% note warning %}

You may need to additionally [configure security groups](connect/index.md#configuring-security-groups) to connect to the cluster.

{% endnote %}


## Changing the hybrid storage settings {#change-hybrid-storage}

{% list tabs group=instructions %}

- 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 change the [hybrid storage settings](../concepts/storage.md#hybrid-storage-settings):

  1. View the description of the CLI command for updating a cluster:

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

  1. If hybrid storage is disabled in your cluster, enable it:

      ```bash
      yc managed-clickhouse cluster update <cluster_name_or_ID> \
          --cloud-storage=true
      ```

      {% note info %}
      
      Once hybrid storage is enabled, you cannot disable it.
      
      {% endnote %}

  1. Provide the list of settings to update:

      ```bash
      yc managed-clickhouse cluster update <cluster_name_or_ID> \
          --cloud-storage-data-cache=<file_storage> \
          --cloud-storage-data-cache-max-size=<memory_size_in_bytes> \
          --cloud-storage-move-factor=<share_of_free_space> \
          --cloud-storage-prefer-not-to-merge=<merging_data_parts>
      ```

      You can update the following settings:

      * `--cloud-storage-data-cache`: Enables caching files in the cluster storage. The default value is `true` (enabled).
      * `--cloud-storage-data-cache-max-size`: Sets the maximum cache size, in bytes, allocated in the cluster storage. If no value is set, the maximum cache size defaults to half the size of the cluster storage.
      * `--cloud-storage-move-factor`: Sets the minimum percentage of free space in the cluster storage. If your free space percentage is below this value, the data will be moved to Yandex Object Storage. The minimum value is `0`, the maximum value is `1`, and the default value is `0.01`.
      * `--cloud-storage-prefer-not-to-merge`: Disables [merging of data parts](https://clickhouse.com/docs/enen/engines/table-engines/mergetree-family/custom-partitioning-key) in cluster and object storages. To disable merges, set the parameter to `true` or provide it with no value. To keep merges enabled, set the parameter to `false` or do not provide it in the CLI command when creating a cluster.

- 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": "<list_of_settings_to_update>",
                      "configSpec": {
                        "cloudStorage": {
                          "enabled": <hybrid_storage_use>,
                          "moveFactor": "<share_of_free_space>",
                          "dataCacheEnabled": <temporary_file_storage>,
                          "dataCacheMaxSize": "<maximum_memory_for_file_storage>",
                          "preferNotToMerge": <disabling_data_part_merging>
                        }
                      }
                    }'
        ```

        Where:

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

        * `configSpec.cloudStorage`: Hybrid storage settings:

            * `enabled`: Enable hybrid storage in the cluster if it is disabled, `true` or `false`. The default value is `false` (disabled).
            
                {% note info %}
                
                Once hybrid storage is enabled, you cannot disable it.
                
                {% endnote %}
            
            * `moveFactor`: Minimum percentage of free space in the cluster storage. If your free space percentage is below this value, the data will be moved to Yandex Object Storage.
            
                The minimum value is `0`, the maximum value is `1`, and the default value is `0.01`.
            
            * `dataCacheEnabled`: Enable caching files in the cluster storage, `true` or `false`.
            
                The default value is `true` (enabled).
            
            * `dataCacheMaxSize`: Maximum cache size, in bytes, allocated in the cluster storage.
                
                If no value is set, the maximum cache size defaults to half the size of the cluster storage.
            
            * `preferNotToMerge`: Disable [merging of data parts](https://clickhouse.com/docs/enen/engines/table-engines/mergetree-family/custom-partitioning-key) in the cluster and object storage, `true` or `false`.
            
                To disable merging, set to `true`. To leave merging enabled, set to `false`.

        You can get 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": [
                      <list_of_settings_to_update>
                    ]
                  },
                  "config_spec": {
                    "cloud_storage": {
                      "enabled": <hybrid_storage_use>,
                      "move_factor": "<share_of_free_space>",
                      "data_cache_enabled": <temporary_file_storage>,
                      "data_cache_max_size": "<maximum_memory_for_file_storage>",
                      "prefer_not_to_merge": <disabling_data_part_merging>
                    }
                  }
                }' \
            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[]`).

        * `config_spec.cloud_storage`: Hybrid storage settings:

            * `enabled`: Enable hybrid storage in the cluster if it is disabled, `true` or `false`. The default value is `false` (disabled).
            
                {% note info %}
                
                Once hybrid storage is enabled, you cannot disable it.
                
                {% endnote %}
            
            * `move_factor`: Minimum percentage of free space in the cluster storage. If your free space percentage is below this value, the data will be moved to Yandex Object Storage.
            
                The minimum value is `0`, the maximum value is `1`, and the default value is `0.01`.
            
            * `data_cache_enabled`: Enable caching files in the cluster storage, `true` or `false`.
            
                The default value is `true` (enabled).
            
            * `data_cache_max_size`: Maximum cache size, in bytes, allocated in the cluster storage.
            
                If no value is set, the maximum cache size defaults to half the size of the cluster storage.
            
            * `prefer_not_to_merge`: Disable [merging of data parts](https://clickhouse.com/docs/enen/engines/table-engines/mergetree-family/custom-partitioning-key) in the cluster and object storage, `true` or `false`.
            
                To disable merging, set to `true`. To leave merging enabled, set to `false`.

        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 %}

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