Skip to main content
Skip to main content
Edit this page

Constraints on Settings

Overview​

In ClickHouse, "constraints" on settings refer to limitations and rules which you can assign to settings. These constraints can be applied to maintain stability, security and predictable behavior of your database.

Defining constraints​

Constraints on settings can be defined in the profiles section of the user.xml configuration file. They prohibit users from changing some settings using the SET statement.

Constraints are defined as follows:

If the user tries to violate the constraints, an exception is thrown and the setting remains unchanged.

Types of constraints​

There are a few types of constraints supported in ClickHouse:

  • min
  • max
  • readonly (with alias const)
  • changeable_in_readonly

The min and max constraints specify upper and lower boundaries for a numeric setting and can be used in combination with each other.

The readonly or const constraint specifies that the user cannot change the corresponding setting at all.

The changeable_in_readonly constraint type allows users to change the setting within the min/max range even if the readonly setting is set to 1, otherwise settings are not allowed to be changed in readonly=1 mode.

note

changeable_in_readonly is supported only if settings_constraints_replace_previous is enabled:

Multiple constraint profiles​

If there are multiple profiles active for a user, then constraints are merged. The Merge process depends on settings_constraints_replace_previous:

  • true (recommended): constraints for the same setting are replaced during merge, such that the last constraint is used and all previous ones are ignored. This includes fields that are not set in new constraint.
  • false (default): constraints for the same setting are merged in a way that every unset type of constraint is taken from the previous profile and every set type of constraint is replaced by the value from the new profile.

Read-only mode​

Read-only mode is enabled by the readonly setting which is not to be confused with the readonly constraint type:

  • readonly=0: No read-only restrictions.
  • readonly=1: Only read queries are allowed and settings cannot be changed unless changeable_in_readonly is set.
  • readonly=2: Only read queries are allowed, but settings can be changed, except for readonly setting itself.

Example​

Let users.xml include the following lines:

The following queries will all throw exceptions:

note

The default profile is handled uniquely: all the constraints defined for the default profile become the default constraints, so they restrict all the users until they're overridden explicitly for those users.

Constraints on MergeTree settings​

It is possible to set constraints for merge tree settings. These constraints are applied when a table with the MergeTree engine is created or its storage settings are altered.

The name of merge tree setting must be prepended by merge_tree_ prefix when referenced in the <constraints> section.

Example​

You can forbid creating new tables with explicitly specified storage_policy