> ## Documentation Index
> Fetch the complete documentation index at: https://clisma.poorquality.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# clisma.hcl

> Define environments and migration settings in clisma.hcl

Clisma uses an HCL config file to define environments and migration settings.

The root blocks are:

* `env "name"` for a database environment
* `variable "name"` for user-defined inputs

## Minimum config

```hcl theme={null}
env "local" {
  url = "http://default:password@localhost:8123/mydb"

  migrations {
    dir = "migrations"
  }
}
```

## env "name"

```hcl theme={null}

env "production" {
  url = "http://default:password@localhost:8123/mydb"

  tls {
    ca_file = "certs/ca.pem"
  }

  migrations {
    dir = "migrations"

    table {
      name = "schema_migrations"

      is_replicated = true

      # Optional: force a specific cluster for ON CLUSTER.
      cluster_name = "dwh"

      # If replication_path is set, is_replicated can be omitted.
      replication_path = "/clickhouse/tables/{cluster}/schema_migrations"
    }

    vars = {
      ttl_days = 30
    }
  }
}
```

Fields:

* `url` (string) Connection string. Supports `env("NAME")`.
* `exclude` (list\<string>, optional) Patterns to ignore.
* `migrations` (block) Migration settings.
* `tls` (block, optional) TLS certificate settings for custom CA and mTLS:
  * `ca_file` (string, required if `tls` is set) Path to CA certificate in PEM format.
  * `cert_file` (string, optional) Client certificate in PEM format.
  * `key_file` (string, optional) Client key in PEM format. Must be provided together with `cert_file`.

## migrations

* `dir` (string) Path to migrations directory.
* `table` (block, optional) Tracking table settings.
  * `table.name` (string, optional) Custom tracking table.
  * `table.is_replicated` (bool, optional, default `false`) Use replicated tracking table with `ON CLUSTER`.
  * `table.cluster_name` (string, optional) Cluster name override for `ON CLUSTER`. Useful when multiple clusters exist.
  * `table.replication_path` (string, optional) Replication path for the tracking table. If set, replicated mode is enabled even when `table.is_replicated` is omitted.
* `vars` (object, optional) Variables for Handlebars templates.

## variable "name"

```hcl theme={null}
variable "ttl_days" {
  type = string
  default = "30"
  description = "Default TTL"
}
```