Updating ClickHouse® cluster settings

If you do not have the Yandex Cloud CLI yet, install and initialize it.

The folder specified when creating the CLI profile is used by default. To change the default folder, use the yc config set folder-id <folder_ID> command. You can specify a different folder using the --folder-name or --folder-id parameter.

To change the host class for the cluster:

1. View the description of the CLI command to update the cluster:

   yc managed-clickhouse cluster update --help
   

2. Request a list of available host classes (the ZONE IDS column specifies the availability zones where you can select the appropriate class):

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

3. Specify the class in the update cluster command:

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

   Managed Service for ClickHouse® will run the update host class command for the cluster.

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

1. Open the current Terraform configuration file that defines your infrastructure.

   For more information about creating this file, see Creating clusters.

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

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

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

   2. Run this command:

      terraform validate
      

      Terraform will show any errors found in your configuration files.

4. Confirm updating the resources.

   1. Run this command to view the planned changes:

      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.

   2. If everything looks correct, apply the changes:

      1. Run this command:

         terraform apply
         

      2. Confirm updating the resources.

      3. Wait for the operation to complete.

For more information, see the Terraform provider documentation.

resource "yandex_mdb_clickhouse_cluster" "<cluster_name>" {
  ...
  timeouts {
    create = "1h30m" # 1 hour 30 minutes
    update = "2h"    # 2 hours
    delete = "30m"   # 30 minutes
  }
}

1. Get an IAM token for API authentication and put it into the environment variable:

   export IAM_TOKEN="<IAM_token>"
   

2. Request a list of available host classes:

   1. Use the ResourcePreset.List method and send the following request, e.g., via cURL:

      curl \
          --request GET \
          --header "Authorization: Bearer $IAM_TOKEN" \
          --url 'https://mdb.api.cloud.yandex.net/managed-clickhouse/v1/resourcePresets'
      

   2. View the server response to make sure the request was successful.

3. Change the host class as appropriate:

   1. Use the Cluster.Update method and send the following request, e.g., via cURL:

      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.

      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: List of parameters to update as a single string, separated by commas.

        Specify the relevant parameters:

        • configSpec.clickhouse.resources.resourcePresetId: To change the ClickHouse® host class.
        • configSpec.zookeeper.resources.resourcePresetId: To change the ZooKeeper host class.

        Both ClickHouse® and ZooKeeper host classes are changed in the request example.

      • configSpec.clickhouse.resources.resourcePresetId: ClickHouse® host class ID.

      • configSpec.zookeeper.resources.resourcePresetId: ZooKeeper host class ID.

      You can request the cluster ID with the list of clusters in the folder. The list of available host classes with their IDs came to you earlier.

   2. View the server response to make sure the request was successful.

1. Get an IAM token for API authentication and put it into the environment variable:

   export IAM_TOKEN="<IAM_token>"
   

2. Clone the cloudapi repository:

   cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi
   

   Below, we assume the repository contents are stored in the ~/cloudapi/ directory.

3. Request a list of available host classes:

   1. Use the ResourcePresetService/List call and send the following request, e.g., via gRPCurl:

      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
      

   2. View the server response to make sure the request was successful.

4. Change the host class as appropriate:

   1. Use the ClusterService.Update call and send the following request, e.g., via gRPCurl:

      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.

      Format for listing settings

      "update_mask": {
          "paths": [
              "<setting_1>",
              "<setting_2>",
              ...
              "<setting_N>"
          ]
      }
      

      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 parameters to update as an array of paths[] strings.

        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.

        Both ClickHouse® and ZooKeeper host classes are changed in the request example.

      • config_spec.clickhouse.resources.resource_preset_id: ClickHouse® host class ID.

      • config_spec.zookeeper.resources.resource_preset_id: ZooKeeper host class ID.

      You can request the cluster ID with the list of clusters in the folder. The list of available host classes with their IDs came to you earlier.

   2. View the server response to make sure the request was successful.

If you do not have the Yandex Cloud CLI yet, install and initialize it.

The folder specified when creating the CLI profile is used by default. To change the default folder, use the yc config set folder-id <folder_ID> command. You can specify a different folder using the --folder-name or --folder-id parameter.

To increase the cluster storage size:

1. View the description of the CLI command to update the cluster:

   yc managed-clickhouse cluster update --help
   

2. Specify the required storage in the cluster update command (it must be at least as large as disk_size in the cluster properties):

   yc managed-clickhouse cluster update <cluster_name_or_ID> \
     --clickhouse-disk-size <storage_size_in_GB>
   

3. To increase the storage capacity of ZooKeeper hosts, provide the value you need in the --zookeeper-disk-size parameter.

To increase storage size:

1. Open the current Terraform configuration file that defines your infrastructure.

   For more information about creating this file, see Creating clusters.

2. In the Managed Service for ClickHouse® cluster description, change the value of the disk_size parameter in the clickhouse.resources and zookeeper.resources sections for ClickHouse® and ZooKeeper hosts, respectively:

   resource "yandex_mdb_clickhouse_cluster" "<cluster_name>" {
     ...
     clickhouse {
       resources {
         disk_size = <storage_size_in_GB>
         ...
       }
     }
     zookeeper {
       resources {
         disk_size = <storage_size_in_GB>
         ...
       }
     }
   }
   

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

   2. Run this command:

      terraform validate
      

      Terraform will show any errors found in your configuration files.

4. Confirm updating the resources.

   1. Run this command to view the planned changes:

      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.

   2. If everything looks correct, apply the changes:

      1. Run this command:

         terraform apply
         

      2. Confirm updating the resources.

      3. Wait for the operation to complete.

For more information, see the Terraform provider documentation.

resource "yandex_mdb_clickhouse_cluster" "<cluster_name>" {
  ...
  timeouts {
    create = "1h30m" # 1 hour 30 minutes
    update = "2h"    # 2 hours
    delete = "30m"   # 30 minutes
  }
}

1. Get an IAM token for API authentication and put it into the environment variable:

   export IAM_TOKEN="<IAM_token>"
   

2. Use the Cluster.Update method and send the following request, e.g., via cURL:

   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.

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

   Where:

   • updateMask: List of parameters to update as a single string, separated by commas.

     Specify the relevant parameters:

     • configSpec.clickhouse.resources.diskSize: If you need to increase ClickHouse® host storage size.
     • configSpec.zookeeper.resources.diskSize: If you need to increase ZooKeeper host storage size.

     Both ClickHouse® and ZooKeeper host storage sizes are increased in the request example.

   • configSpec.clickhouse.resources.diskSize: ClickHouse® host storage size in bytes.

   • configSpec.zookeeper.resources.diskSize: ZooKeeper host storage size in bytes.

   You can request the cluster ID with the list of clusters in the folder.

3. View the server response to make sure the request was successful.

1. Get an IAM token for API authentication and put it into the environment variable:

   export IAM_TOKEN="<IAM_token>"
   

2. Clone the cloudapi repository:

   cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi
   

   Below, we assume the repository contents are stored in the ~/cloudapi/ directory.

3. Use the ClusterService.Update call and send the following request, e.g., via gRPCurl:

   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.

   Format for listing settings

   "update_mask": {
       "paths": [
           "<setting_1>",
           "<setting_2>",
           ...
           "<setting_N>"
       ]
   }
   

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

   Where:

   • update_mask: List of parameters to update as an array of paths[] strings.

     Specify the relevant parameters:

     • config_spec.clickhouse.resources.disk_size: If you need to increase ClickHouse® host storage size.
     • config_spec.zookeeper.resources.disk_size: If you need to increase ZooKeeper host storage size.

     Both ClickHouse® and ZooKeeper host storage sizes are increased in the request example.

   • config_spec.clickhouse.resources.disk_size: ClickHouse® host storage size in bytes.

   • config_spec.zookeeper.resources.disk_size: ZooKeeper host storage size in bytes.

   You can request the cluster ID with the list of clusters in the folder.

4. View the server response to make sure the request was successful.

If you do not have the Yandex Cloud CLI yet, install and initialize it.

The folder specified when creating the CLI profile is used by default. To change the default folder, use the yc config set folder-id <folder_ID> command. You can specify a different folder using the --folder-name or --folder-id parameter.

1. To enable SQL user management:

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

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

2. To enable SQL database management:

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

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

1. Open the current Terraform configuration file that defines your infrastructure.

   For more information about creating this file, see Creating clusters.

2. To enable user management via SQL, expand the cluster description to include a sql_user_management field set to true and an admin_password field containing the password for the admin account:

   resource "yandex_mdb_clickhouse_cluster" "<cluster_name>" {
     name                = "<cluster_name>"
     ...
     admin_password      = "<admin_password>"
     sql_user_management = true
     ...
   }
   

3. To enable database management via SQL, expand the cluster description to include a sql_user_management field and a sql_database_management field, both set to true, as well as the admin_password field containing the password for the admin account:

   resource "yandex_mdb_clickhouse_cluster" "<cluster_name>" {
     name                    = "<cluster_name>"
     ...
     admin_password          = "<admin_password>"
     sql_database_management = true
     sql_user_management     = true
     ...
   }
   

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

   2. Run this command:

      terraform validate
      

      Terraform will show any errors found in your configuration files.

5. Confirm updating the resources.

   1. Run this command to view the planned changes:

      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.

   2. If everything looks correct, apply the changes:

      1. Run this command:

         terraform apply
         

      2. Confirm updating the resources.

      3. Wait for the operation to complete.

For more information, see the Terraform provider documentation.

resource "yandex_mdb_clickhouse_cluster" "<cluster_name>" {
  ...
  timeouts {
    create = "1h30m" # 1 hour 30 minutes
    update = "2h"    # 2 hours
    delete = "30m"   # 30 minutes
  }
}

1. Get an IAM token for API authentication and put it into the environment variable:

   export IAM_TOKEN="<IAM_token>"
   

2. Use the Cluster.Update method and send the following request, e.g., via cURL:

   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.

   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: List of parameters to update as a single string, separated by commas.

     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.

     Both user and database management via SQL are enabled in the request example.

   • configSpec.adminPassword: admin user 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 through SQL.

   You can request the cluster ID with the list of clusters in the folder.

3. View the server response to make sure the request was successful.

1. Get an IAM token for API authentication and put it into the environment variable:

   export IAM_TOKEN="<IAM_token>"
   

2. Clone the cloudapi repository:

   cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi
   

   Below, we assume the repository contents are stored in the ~/cloudapi/ directory.

3. Use the ClusterService.Update call and send the following request, e.g., via gRPCurl:

   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.

   Format for listing settings

   "update_mask": {
       "paths": [
           "<setting_1>",
           "<setting_2>",
           ...
           "<setting_N>"
       ]
   }
   

   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 parameters to update as an array of paths[] strings.

     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.

     Both user and database management via SQL are enabled in the request example.

   • 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 through SQL.

   You can request the cluster ID with the list of clusters in the folder.

4. View the server response to make sure the request was successful.

If you do not have the Yandex Cloud CLI yet, install and initialize it.

The folder specified when creating the CLI profile is used by default. To change the default folder, use the yc config set folder-id <folder_ID> command. You can specify a different folder using the --folder-name or --folder-id parameter.

To change additional cluster settings:

1. View the description of the CLI command to update the cluster:

   yc managed-clickhouse cluster update --help
   

2. Run the following command with the list of settings to update:

   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 \
      --maintenance-window type=<maintenance_type>,`
                          `day=<day_of_week>,`
                          `hour=<hour>
   

You can change 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.

• --metrika-access: Enables data import from AppMetrica to your cluster. The default value is false.

• --serverless-access: Enables cluster access from Yandex Cloud Functions. The default value is false. For more information about setting up access, see the Cloud Functions documentation.

• --websql-access: Enables SQL queries against cluster databases from the Yandex Cloud management console using Yandex WebSQL. The default value is false.

• --yandexquery-access=true: Enables cluster access from Yandex Query. This feature is at the Preview stage.Default value: 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.

• --maintenance-window: Maintenance window settings (including for disabled clusters), where type is the maintenance type:

  • anytime (default): Any time.
  • weekly: On a schedule. If setting this value, specify the day of week and the hour:
    • day: Day of week in DDD format: MON, TUE, WED, THU, FRI, SAT, or SUN.
    • hour: Hour (UTC) in HH format: 1 to 24.

You can get the cluster ID and name with the list of clusters in the folder.

1. Open the current Terraform configuration file that defines your infrastructure.

   For more information about creating this file, see Creating clusters.

2. To change the backup start time, add a backup_window_start block to the Managed Service for ClickHouse® cluster description:

   resource "yandex_mdb_clickhouse_cluster" "<cluster_name>" {
     ...
     backup_window_start {
       hours   = <backup_start_hour>
       minutes = <backup_start_minute>
     }
     ...
   }
   

3. To enable access to the cluster from other services and allow running SQL queries from the management console using Yandex WebSQL, edit the values of the appropriate fields in the access section:

   resource "yandex_mdb_clickhouse_cluster" "<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: Execution of SQL queries from the management console, true or false.

4. To set up the maintenance window (for disabled clusters as well), add the maintenance_window block to the cluster description:

   resource "yandex_mdb_clickhouse_cluster" "<cluster_name>" {
     ...
     maintenance_window {
       type = <maintenance_type>
       day  = <day_of_week>
       hour = <hour>
     }
     ...
   }
   

   Where:

   • type: Maintenance type. The possible values include:
     • anytime: Anytime.
     • weekly: By schedule.
   • day: Day of the week for the weekly type in DDD format, e.g., MON.
   • hour: Hour of the day for the weekly type in the HH format, e.g., 21.

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

   resource "yandex_mdb_clickhouse_cluster" "<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.

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

   2. Run this command:

      terraform validate
      

      Terraform will show any errors found in your configuration files.

7. Confirm updating the resources.

   1. Run this command to view the planned changes:

      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.

   2. If everything looks correct, apply the changes:

      1. Run this command:

         terraform apply
         

      2. Confirm updating the resources.

      3. Wait for the operation to complete.

For more information, see the Terraform provider documentation.

resource "yandex_mdb_clickhouse_cluster" "<cluster_name>" {
  ...
  timeouts {
    create = "1h30m" # 1 hour 30 minutes
    update = "2h"    # 2 hours
    delete = "30m"   # 30 minutes
  }
}

1. Get an IAM token for API authentication and put it into the environment variable:

   export IAM_TOKEN="<IAM_token>"
   

2. Use the Cluster.Update method and send the following request, e.g., via cURL:

   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.

   1. Create a file named body.json and add the following contents to it:

      {
        "updateMask": "<list_of_settings_to_update>",
        "configSpec": {
          "backupWindowStart": {
            "hours": "<hours>",
            "minutes": "<minutes>",
            "seconds": "<seconds>",
            "nanos": "<nanoseconds>"
          },
          "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: List of parameters to update as a single string, separated by commas.

      • configSpec.backupWindowStart: Backup start time (UTC):

        • hours: Hours in 24-hour format
        • minutes: Minutes
        • seconds: Seconds
        • nanos: Nanoseconds

      • configSpec.access: Settings enabling access to the cluster from other services and SQL queries from the management console 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.

        • webSql: Enables SQL queries against cluster databases from the Yandex Cloud management console using Yandex WebSQL, true or false. The default value is false.

        • metrika: Enables data import from AppMetrica to your cluster: true or false. The default value is false.

        • serverless: Enable access to the cluster from Yandex Cloud Functions, true or false. The default value is false. For more information about setting up access, see the Cloud Functions documentation.

        • dataTransfer: Enable access to the cluster from Yandex Data Transfer 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. As a result, other operations, e.g., transfer launch and deactivation, will run faster.

        • yandexQuery: Enable access to the cluster from Yandex Query, true or false. This feature is at the Preview stage.Default value: false.

      • maintenanceWindow: Maintenance window settings (including for disabled clusters). Select one of the options:

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

      • deletionProtection: Cluster protection from 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.

   2. Run this request:

      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 request the cluster ID with the list of clusters in the folder.

3. View the server response to make sure the request was successful.

1. Get an IAM token for API authentication and put it into the environment variable:

   export IAM_TOKEN="<IAM_token>"
   

2. Clone the cloudapi repository:

   cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi
   

   Below, we assume the repository contents are stored in the ~/cloudapi/ directory.

3. Use the ClusterService.Update call and send the following request, e.g., via gRPCurl:

   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.

   Format for listing settings

   "update_mask": {
       "paths": [
           "<setting_1>",
           "<setting_2>",
           ...
           "<setting_N>"
       ]
   }
   

   1. Create a file named body.json and add the following contents to it:

      {
        "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>"
          },
          "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 parameters to update as an array of paths[] strings.

      • 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 access to the cluster from other services and SQL queries from the management console 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.

        • web_sql: Enables SQL queries against cluster databases from the Yandex Cloud management console using Yandex WebSQL: true or false. The default value is false.

        • metrika: Enables data import from AppMetrica to your cluster: true or false. The default value is false.

        • serverless: Enable access to the cluster from Yandex Cloud Functions, true or false. The default value is false. For more information about setting up access, see the Cloud Functions documentation.

        • data_transfer: Enable access to the cluster from Yandex Data Transfer 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. As a result, other operations, e.g., transfer launch and deactivation, will run faster.

        • yandex_query: Enable access to the cluster from Yandex Query, true or false: true or false. This feature is at the Preview stage.Default value: false.

      • maintenance_window: Maintenance window settings (including for disabled clusters). Select one of these options:

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

      • deletion_protection: Cluster protection from 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 request the cluster ID with the list of clusters in the folder.

   2. Run this request:

      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
      

4. View the server response to make sure the request was successful.

If you do not have the Yandex Cloud CLI yet, install and initialize it.

The folder specified when creating the CLI profile is used by default. To change the default folder, use the yc config set folder-id <folder_ID> command. You can specify a different folder using the --folder-name or --folder-id parameter.

To move a cluster:

1. View the description of the CLI move cluster command:

   yc managed-clickhouse cluster move --help
   

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

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

   You can get the cluster ID with the list of clusters in the folder.

1. Open the current Terraform configuration file that defines your infrastructure.

   For more information about creating this file, see Creating clusters.

2. In the Managed Service for ClickHouse® cluster description, edit or add the folder_id parameter value:

   resource "yandex_mdb_clickhouse_cluster" "<cluster_name>" {
     ...
     folder_id = "<destination_folder_ID>"
   }
   

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

   2. Run this command:

      terraform validate
      

      Terraform will show any errors found in your configuration files.

4. Confirm updating the resources.

   1. Run this command to view the planned changes:

      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.

   2. If everything looks correct, apply the changes:

      1. Run this command:

         terraform apply
         

      2. Confirm updating the resources.

      3. Wait for the operation to complete.

For more information, see the Terraform provider documentation.

resource "yandex_mdb_clickhouse_cluster" "<cluster_name>" {
  ...
  timeouts {
    create = "1h30m" # 1 hour 30 minutes
    update = "2h"    # 2 hours
    delete = "30m"   # 30 minutes
  }
}

1. Get an IAM token for API authentication and put it into the environment variable:

   export IAM_TOKEN="<IAM_token>"
   

2. Use the Cluster.Move method and send the following request, e.g., via cURL:

   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 the cluster to. You can get this ID with the list of folders in the cloud.

   You can request the cluster ID with the list of clusters in the folder.

3. View the server response to make sure the request was successful.

1. Get an IAM token for API authentication and put it into the environment variable:

   export IAM_TOKEN="<IAM_token>"
   

2. Clone the cloudapi repository:

   cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi
   

   Below, we assume the repository contents are stored in the ~/cloudapi/ directory.

3. Use the ClusterService.Move call and send the following request, e.g., via gRPCurl:

   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 the cluster to. You can get this ID with the list of folders in the cloud.

   You can request the cluster ID with the list of clusters in the folder.

4. View the server response to make sure the request was successful.

If you do not have the Yandex Cloud CLI yet, install and initialize it.

The folder specified when creating the CLI profile is used by default. To change the default folder, use the yc config set folder-id <folder_ID> command. You can specify a different folder using the --folder-name or --folder-id parameter.

To edit the list of security groups for your cluster:

1. View the description of the CLI command to update the cluster:

   yc managed-clickhouse cluster update --help
   

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

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

1. Open the current Terraform configuration file that defines your infrastructure.

   For more information about creating this file, see Creating clusters.

2. Change the value of the security_group_ids parameter in the cluster description:

   resource "yandex_mdb_clickhouse_cluster" "<cluster_name>" {
     ...
     security_group_ids = [ <list_of_cluster_security_group_IDs> ]
   }
   

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

   2. Run this command:

      terraform validate
      

      Terraform will show any errors found in your configuration files.

4. Confirm updating the resources.

   1. Run this command to view the planned changes:

      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.

   2. If everything looks correct, apply the changes:

      1. Run this command:

         terraform apply
         

      2. Confirm updating the resources.

      3. Wait for the operation to complete.

For more information, see the Terraform provider documentation.

resource "yandex_mdb_clickhouse_cluster" "<cluster_name>" {
  ...
  timeouts {
    create = "1h30m" # 1 hour 30 minutes
    update = "2h"    # 2 hours
    delete = "30m"   # 30 minutes
  }
}

1. Get an IAM token for API authentication and put it into the environment variable:

   export IAM_TOKEN="<IAM_token>"
   

2. Use the Cluster.Update method and send the following request, e.g., via cURL:

   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.

   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: List of parameters to update as a single string, separated by commas.

     Here only one parameter is specified: securityGroupIds.

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

     Warning

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

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

   You can request the cluster ID with the list of clusters in the folder.

3. View the server response to make sure the request was successful.

1. Get an IAM token for API authentication and put it into the environment variable:

   export IAM_TOKEN="<IAM_token>"
   

2. Clone the cloudapi repository:

   cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi
   

   Below, we assume the repository contents are stored in the ~/cloudapi/ directory.

3. Use the ClusterService.Update call and send the following request, e.g., via gRPCurl:

   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.

   Format for listing settings

   "update_mask": {
       "paths": [
           "<setting_1>",
           "<setting_2>",
           ...
           "<setting_N>"
       ]
   }
   

   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 parameters to update as an array of paths[] strings.

     Here only one parameter is specified: security_group_ids.

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

     Warning

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

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

   You can request the cluster ID with the list of clusters in the folder.

4. View the server response to make sure the request was successful.

1. Get an IAM token for API authentication and put it into the environment variable:

   export IAM_TOKEN="<IAM_token>"
   

2. Use the Cluster.Update method and send the following request, e.g., via cURL:

   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.

   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_cache_size_for_file_storage>",
                     "preferNotToMerge": <disabling_merging_data_parts>
                   }
                 }
               }'
   

   Where:

   • updateMask: List of parameters to update as a single string, separated by commas.

   • configSpec.cloudStorage: Hybrid storage settings:

     • enabled: Enable hybrid storage in the cluster if it is disabled, true or false. Default value: false (disabled).

       Note

       Once enabled, hybrid storage cannot be disabled.

     • moveFactor: Minimum share of free space in cluster storage. If the minimum share is below this value, the data will be moved to Yandex Object Storage.

       Minimum value: 0; maximum value: 1; default: 0.01.

     • dataCacheEnabled: Allow temporary storage of files in cluster storage, true or false.

       Default value: true (enabled).

     • dataCacheMaxSize: Maximum cache size (in bytes) allocated in cluster storage for temporary file storage.

       Default value: 1073741824 (1 GB).

     • preferNotToMerge: Disable merging of data parts in cluster and object storage, true or false.

       To disable merging, set to true. To leave merging enabled, set to false.

   You can request the cluster ID with the list of clusters in the folder.

3. View the server response to make sure the request was successful.

1. Get an IAM token for API authentication and put it into the environment variable:

   export IAM_TOKEN="<IAM_token>"
   

2. Clone the cloudapi repository:

   cd ~/ && git clone --depth=1 https://github.com/yandex-cloud/cloudapi
   

   Below, we assume the repository contents are stored in the ~/cloudapi/ directory.

3. Use the ClusterService.Update call and send the following request, e.g., via gRPCurl:

   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.

   Format for listing settings

   "update_mask": {
       "paths": [
           "<setting_1>",
           "<setting_2>",
           ...
           "<setting_N>"
       ]
   }
   

   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_cache_size_for_file_storage>",
                 "prefer_not_to_merge": <disabling_merging_data_parts>
               }
             }
           }' \
       mdb.api.cloud.yandex.net:443 \
       yandex.cloud.mdb.clickhouse.v1.ClusterService.Update
   

   Where:

   • update_mask: List of parameters to update as an array of paths[] strings.

   • config_spec.cloud_storage: Hybrid storage settings:

     • enabled: Enable hybrid storage in the cluster if it is disabled, true or false. Default value: false (disabled).

       Note

       Once enabled, hybrid storage cannot be disabled.

     • move_factor: Minimum share of free space in cluster storage. If the minimum share is below this value, the data will be moved to Yandex Object Storage.

       Minimum value: 0; maximum value: 1; default: 0.01.

     • data_cache_enabled: Allow temporary storage of files in cluster storage, true or false.

       Default value: true (enabled).

     • data_cache_max_size: Maximum cache size (in bytes) allocated in cluster storage for temporary file storage.

       Default value: 1073741824 (1 GB).

     • prefer_not_to_merge: Disable merging of data parts in cluster and object storage, true or false.

       To disable merging, set to true. To leave merging enabled, set to false.

   You can request the cluster ID with the list of clusters in the folder.

4. View the server response to make sure the request was successful.