## How Atlan connects to ClickHouse

URL: https://docs.atlan.com/apps/connectors/database/clickhouse/concepts/how-atlan-connects-to-clickhouse

> Understand how Atlan securely connects to your ClickHouse database to extract metadata.

Atlan connects to your ClickHouse database to extract technical metadata while maintaining network security and compliance. You can choose between Direct connectivity for databases available from the internet or Self-deployed runtime for databases that must remain behind your firewall.

## Connect via direct network connection

Atlan's ClickHouse workflow establishes a direct network connection to your database from the Atlan SaaS tenant. This approach works when your ClickHouse database can accept connections from the internet.

```mermaid
sequenceDiagram
 participant User as User
 participant Atlan as Atlan SaaS Tenant
 participant ClickHouse as ClickHouse

 User->>Atlan: Provide connection details (host, port, credentials)
 Atlan->>ClickHouse: Establish direct connection (default port 8443)
 Atlan->>ClickHouse: Execute read-only queries for metadata discovery
 ClickHouse-->>Atlan: Return metadata structure (databases, tables, views)
 Atlan-->>User: Catalog results in Atlan Cloud
```

- Atlan's ClickHouse workflow connects directly to your database from the Atlan SaaS tenant over the HTTPS interface port 8443 (default).
- Your ClickHouse database accepts inbound network connections from Atlan's IP addresses, controlled through your firewall rules or network security groups.

For details on how direct connectivity works, see [Direct connectivity](https://docs.atlan.com/llms/catalog/connector-capabilities/direct-connectivity/llms.txt).

## Connect via self-deployed runtime

A runtime service deployed within your network acts as a secure bridge between Atlan Cloud and your ClickHouse database. This approach works when your ClickHouse database must remain fully isolated behind your firewall.

```mermaid
sequenceDiagram
 participant User as User
 participant Atlan as Atlan Cloud
 participant Runtime as Self-Deployed Runtime
 participant SecretStore as Secret Store
 participant ClickHouse as ClickHouse

 User->>Atlan: Configure crawler workflow (non-sensitive connection details)
 Atlan->>Runtime: Send metadata extraction request (via outbound HTTPS)
 Runtime-->>SecretStore: Request sensitive connection details (username, password)
 SecretStore-->>Runtime: Return sensitive connection details (username, password)
 Runtime->>ClickHouse: Establish local connection (default port 8443)
 Runtime->>ClickHouse: Execute read-only queries for metadata discovery
 ClickHouse-->>Runtime: Return metadata structure (databases, tables, views)
 Runtime-->>Atlan: Send metadata results (via HTTPS)
 Atlan-->>User: Catalog results in Atlan Cloud
```

- The runtime maintains an outbound HTTPS connection to Atlan Cloud (port 443) and a local network connection to your ClickHouse database (port 8443).

For details on how Self-Deployed Runtime works, see [SDR connectivity](https://docs.atlan.com/llms/catalog/connector-capabilities/sdr-connectivity/llms.txt).

## Security

Atlan extracts only structural metadata—databases, tables, views, and columns. For example, if you have a `customer_events` table with event records, Atlan discovers the table structure and column definitions, but never queries or stores the event records themselves.

- **Read-only operations**: All database queries are read-only SELECT statements on ClickHouse system tables (`system.databases`, `system.tables`, `system.columns`). The connector can't modify data, create or drop database objects, or change any configuration. The ClickHouse user permissions you grant control exactly what the connector can access.

- **Credential encryption**: ClickHouse connection credentials are encrypted at rest and in transit. In Direct connectivity, Atlan encrypts credentials before storage. In Self-deployed runtime, credentials never leave your network perimeter—the runtime retrieves them from your enterprise-managed secret vaults (AWS Secrets Manager, Azure Key Vault, GCP Secret Manager, or HashiCorp Vault) only when needed, and Atlan Cloud never receives or stores them.

- **Network isolation with Self-deployed runtime**: Your ClickHouse database gains complete network isolation from the internet. The database only accepts connections from the runtime within your local network. The runtime itself only makes outbound HTTPS connections to Atlan Cloud, which your network team can control through firewall rules.

## See also

* [Direct connectivity](https://docs.atlan.com/llms/catalog/connector-capabilities/direct-connectivity/llms.txt): How Atlan connects directly to data sources
* [SDR connectivity](https://docs.atlan.com/llms/catalog/connector-capabilities/sdr-connectivity/llms.txt): How Self-Deployed Runtime connects to data sources
* [Set up ClickHouse](https://docs.atlan.com/llms/connectors/clickhouse/set-up-clickhouse/llms.txt): Configure user accounts and permissions

---