Configure ClickHouse as a Mage destination to write tabular data into a ClickHouse database using the SQLAlchemy driver.


Configuration Parameters

Provide the following parameters to use ClickHouse as a destination:

KeyDescriptionExample ValueRequired
sqlalchemy_urlSQLAlchemy connection string used to connect to ClickHouse. Includes host, user, password, etc.clickhouse://default:@localhost/default
table_name(Optional) Name of the destination table to write data into. If omitted, the stream name will be used.abc123

SQLAlchemy URL Format

The sqlalchemy_url should follow this structure:

clickhouse://<username>:<password>@<host>:<port>/<database>

Examples:

  • Without password (using default database):
    clickhouse://default:@localhost/default

  • With credentials:
    clickhouse://user:pass123@127.0.0.1:9000/analytics_db

Ensure the database exists in ClickHouse before running the Mage pipeline.


Requirements

  • The ClickHouse database must be reachable from the Mage environment.
  • Mage requires the clickhouse-connect Python package to be installed.
  • The target table should match the schema or allow dynamic schema creation depending on your setup.

FAQs

Can I use a secure connection?

Yes. To use HTTPS or TLS-secured connections, ensure your SQLAlchemy URL includes the appropriate protocol and port, and that your ClickHouse server supports it.

What happens if table_name is not provided?

Mage will automatically use the stream name as the destination table name.