Updating ClickHouse® cluster settings

If you do not have the Yandex Cloud command line interface yet, install and initialize it.

The folder specified in the CLI profile is used by default. 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 update cluster CLI command:

   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 with an infrastructure plan.

   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 blocks 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. Using the command line, navigate to the folder that contains the up-to-date Terraform configuration files with an infrastructure plan.

   2. Run the command:

      terraform validate
      

      If there are errors in the configuration files, Terraform will point to them.

4. Confirm updating the resources.

   1. Run the command to view planned changes:

      terraform plan
      

      If the resource configuration descriptions are correct, the terminal will display a list of the resources to modify and their parameters. This is a test step. No resources are updated.

   2. If you are happy with the planned changes, apply them:

      1. Run the command:

         terraform apply
         

      2. Confirm the update of 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
  }
}

To change the host class, use the update REST API method for the Cluster resource or the ClusterService/Update gRPC API call and provide the following in the request:

• Cluster ID in the clusterId parameter. To find out the cluster ID, get a list of clusters in the folder.

• Required values in the configSpec.clickhouse.resources.resourcePresetId parameter (configSpec.zookeeper.resources.resourcePresetId for ZooKeeper).

  To request a list of supported values, use the list method for the ResourcePreset resources.

• List of settings to update in the updateMask parameter.

If you do not have the Yandex Cloud command line interface yet, install and initialize it.

The folder specified in the CLI profile is used by default. 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 update cluster CLI command:

   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 with an infrastructure plan.

   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 blocks 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. Using the command line, navigate to the folder that contains the up-to-date Terraform configuration files with an infrastructure plan.

   2. Run the command:

      terraform validate
      

      If there are errors in the configuration files, Terraform will point to them.

4. Confirm updating the resources.

   1. Run the command to view planned changes:

      terraform plan
      

      If the resource configuration descriptions are correct, the terminal will display a list of the resources to modify and their parameters. This is a test step. No resources are updated.

   2. If you are happy with the planned changes, apply them:

      1. Run the command:

         terraform apply
         

      2. Confirm the update of 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
  }
}

To increase the storage size, use the update REST API method for the Cluster resource or the ClusterService/Update gRPC API call and provide the following in the request:

• Cluster ID in the clusterId parameter. To find out the cluster ID, get a list of clusters in the folder.
• Required size of the ClickHouse® host storage in the configSpec.clickhouse.resources.diskSize parameter.
• Required size of the ZooKeeper host storage in the configSpec.zookeeper.resources.diskSize parameter.
• List of cluster configuration fields to update in the updateMask parameter.

If you do not have the Yandex Cloud command line interface yet, install and initialize it.

The folder specified in the CLI profile is used by default. 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 with an infrastructure plan.

   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. Using the command line, navigate to the folder that contains the up-to-date Terraform configuration files with an infrastructure plan.

   2. Run the command:

      terraform validate
      

      If there are errors in the configuration files, Terraform will point to them.

5. Confirm updating the resources.

   1. Run the command to view planned changes:

      terraform plan
      

      If the resource configuration descriptions are correct, the terminal will display a list of the resources to modify and their parameters. This is a test step. No resources are updated.

   2. If you are happy with the planned changes, apply them:

      1. Run the command:

         terraform apply
         

      2. Confirm the update of 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
  }
}

To enable user and database management via SQL, use the update REST API method for the Cluster resource or the ClusterService/Update gRPC API call and provide the appropriate values in the configSpec.clickhouse.config request parameter:

• sqlUserManagement: Set to true to enable user management through SQL.
• sqlDatabaseManagement: Set to true to enable database management through SQL. For that, you also need to enable user management through SQL.
• adminPassword: Set a password for the admin account used for management.

If you do not have the Yandex Cloud command line interface yet, install and initialize it.

The folder specified in the CLI profile is used by default. 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 update cluster CLI command:

   yc managed-clickhouse cluster update --help
   

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

   yc managed-clickhouse cluster update <cluster_name_or_ID> \
      --backup-window-start <backup_start_time> \
      --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.

• --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: Protection of the cluster, its databases, and users against accidental deletion.

  Enabled deletion protection will not prevent a manual connection with the purpose to delete 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 a list of clusters in the folder.

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

   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 cluster access from other services and allow running SQL queries from the management console using Yandex WebSQL, change 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>
   }
   

   Enabled deletion protection will not prevent a manual connection with the purpose to delete database contents.

6. Make sure the settings are correct.

   1. Using the command line, navigate to the folder that contains the up-to-date Terraform configuration files with an infrastructure plan.

   2. Run the command:

      terraform validate
      

      If there are errors in the configuration files, Terraform will point to them.

7. Confirm updating the resources.

   1. Run the command to view planned changes:

      terraform plan
      

      If the resource configuration descriptions are correct, the terminal will display a list of the resources to modify and their parameters. This is a test step. No resources are updated.

   2. If you are happy with the planned changes, apply them:

      1. Run the command:

         terraform apply
         

      2. Confirm the update of 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
  }
}

To change additional cluster settings, use the update REST API method for the Cluster resource or the ClusterService/Update gRPC API call and provide the following in the request:

• Cluster ID in the clusterId parameter. To find out the cluster ID, get a list of clusters in the folder.

• Settings for access from other services and access to SQL queries from the management console using Yandex WebSQL in the configSpec.access parameter.

• Backup window settings in the configSpec.backupWindowStart parameter.

• Maintenance window settings (including for disabled clusters) in the maintenanceWindow parameter.

• Cluster deletion protection settings in the deletionProtection parameter.

  Enabled deletion protection will not prevent a manual connection with the purpose to delete database contents.

• List of cluster configuration fields to update in the updateMask parameter.

If you do not have the Yandex Cloud command line interface yet, install and initialize it.

The folder specified in the CLI profile is used by default. 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 a list of clusters in the folder.

To move a cluster, use the move REST API method for the Cluster resource or the ClusterService/Move gRPC API call and provide the following in the request:

• Cluster ID in the clusterId parameter. To find out the cluster ID, get a list of clusters in the folder.
• ID of the destination folder in the destinationFolderId parameter.

If you do not have the Yandex Cloud command line interface yet, install and initialize it.

The folder specified in the CLI profile is used by default. 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 update cluster CLI command:

   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 with an infrastructure plan.

   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. Using the command line, navigate to the folder that contains the up-to-date Terraform configuration files with an infrastructure plan.

   2. Run the command:

      terraform validate
      

      If there are errors in the configuration files, Terraform will point to them.

4. Confirm updating the resources.

   1. Run the command to view planned changes:

      terraform plan
      

      If the resource configuration descriptions are correct, the terminal will display a list of the resources to modify and their parameters. This is a test step. No resources are updated.

   2. If you are happy with the planned changes, apply them:

      1. Run the command:

         terraform apply
         

      2. Confirm the update of 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
  }
}

To update security groups, use the update REST API method for the Cluster resource or the ClusterService/Update gRPC API call and provide the following in the request:

• Cluster ID in the clusterId parameter. To find out the cluster ID, get a list of clusters in the folder.
• List of security group IDs in the securityGroupIds parameter.
• List of settings to update in the updateMask parameter.

To change hybrid storage settings, use the update REST API method for the Cluster resource or the ClusterService/Update gRPC API call and provide the following in the request:

• Cluster ID in the clusterId parameter. To find out the cluster ID, get a list of clusters in the folder.

• true value in the configSpec.cloudStorage.enabled parameter if hybrid storage is not enabled.

  Note

  Once enabled, hybrid storage cannot be disabled.

• The hybrid storage settings in the configSpec.cloudStorage parameters:

  • configSpec.cloudStorage.dataCacheEnabled: Allows you to cache files in cluster storage. This setting is enabled by default (set to true).
  • configSpec.cloudStorage.dataCacheMaxSize: Sets the maximum cache size (in bytes) allocated in cluster storage for files. The default value is 1073741824 (1 GB).
  • configSpec.cloudStorage.moveFactor: Sets the minimum share of free space in cluster storage. If the actual value is less than this setting value, the data is moved to Yandex Object Storage. The minimum value is 0, the maximum one is 1, and the default one is 0.01.
  • configSpec.cloudStorage.preferNotToMerge: Disables data part merges in cluster and object storage. To disable merges, set it to true. To keep merges enabled, set the parameter to false or do not provide it in your API request when creating a cluster.

• List of settings to update in the updateMask parameter.