ClickHouse: Settings Profiles

Atlas now manages ClickHouse settings profiles as first-class resources. Define named profiles at the realm level to enforce query constraints across roles and users, or attach inline settings directly to individual role and user blocks.

Settings profiles in ClickHouse group query constraints such as memory limits, thread counts, and read-only flags into reusable objects that can be applied to roles and users. Atlas now manages them declaratively alongside the rest of your ClickHouse schema.

Enabling Settings Profile Management

Settings profile management is opt-in. Add settings_profiles = true to the mode "clickhouse" block in your atlas.hcl:

env "local" {
  url = getenv("DATABASE_URL")
  dev = docker.clickhouse.dev.url
  schema {
    mode "clickhouse" {
      roles             = true
      settings_profiles = true
    }
  }
}

Named Settings Profiles

A common setup is to cap resource usage for analyst roles and enforce read-only access for everyone except admins. The settings_profile block defines realm-level profiles. Each setting child block names a constraint and accepts a value along with optional min, max, and writability attributes (CONST, READONLY, or CHANGEABLE_IN_READONLY). Profiles can inherit another profile via inherit to build layered constraints (for example, a base profile with resource caps extended by a read-only profile for analysts), and be assigned with to, to_all, or to_all_except:

role "analyst" {}
role "admin" {}

settings_profile "base_limits" {
  setting "max_memory_usage" {
    value = 10000000000
  }
  setting "max_threads" {
    value = 4
    min   = 1
    max   = 8
  }
}

settings_profile "analyst_limits" {
  inherit = [settings_profile.base_limits]
  to      = [role.analyst]
  setting "readonly" {
    value       = 1
    writability = CONST
  }
}

settings_profile "readonly_default" {
  to_all_except = [role.admin]
  setting "readonly" {
    value       = 1
    writability = CONST
  }
}

Inline Settings on Roles and Users

Service accounts and specialized roles often need one-off limits without a shared named profile. Embed a settings_profile block inside a user or role to set constraints directly, or combine inherit with additional setting blocks to extend a named profile:

user "etl" {
  auth_type = "no_password"
  settings_profile {
    setting "max_execution_time" {
      value = 3600
    }
    setting "max_memory_usage" {
      value = 20000000000
    }
  }
}

role "reporting" {
  settings_profile {
    inherit = [settings_profile.analyst_limits]
    setting "max_result_rows" {
      value = 10000
    }
  }
}