Skip to main content
ClickHouse is available as a source connector. MantrixFlow connects over the HTTP transport using the same SQL-first pipeline workflow used by relational sources. Discovered schemas and tables are previewed, staged, transformed with saved SQL models, and delivered to a supported destination.

​
Required access

Use a dedicated read-only database user. Source privileges should not include CREATE, DROP, ALTER, INSERT, or DELETE.
Grant SELECT only on the schemas and tables the workspace needs. Use a secret manager for the real password. Do not commit it to source control.

​
Connection fields

For ClickHouse Cloud, copy the host, username, password, and database from the cloud console and select Secure / TLS. The HTTP port defaults to 8443 and the native port defaults to 9440 automatically.

​
Create the connection

  1. Open Connections.
  2. Click + New Connection.
  3. Set the role to Source.
  4. Choose ClickHouse.
  5. Fill the connection fields.
  6. Click Test Connection.
  7. Save only after the test succeeds.
If the database uses an IP allowlist or private network, follow Private database access before testing.

​
Discover and preview

After creating a pipeline:
  1. Open the pipeline Source tab.
  2. Click Discover catalog.
  3. Enable each required database.table stream.
  4. Choose its sync mode and cursor when applicable.
  5. Preview representative rows and confirm field types.
  6. Click Save stream settings.
System schemas such as system and INFORMATION_SCHEMA are filtered out of discovery. The default database is treated as a regular user database and is preserved. Selected streams receive stable staging names such as default__events.

​
Full Table mode

Use Full Table for the first run, small reference tables, or deliberate snapshots. A run reads every selected source row visible to the source user.

​
Incremental mode

Use Incremental for growing tables with a stable cursor:
  • updated_at for inserts and updates;
  • created_at for append-only tables; or
  • a monotonically increasing identifier.
The cursor should be populated, indexed, and updated whenever a row changes. Use a stable primary key such as id for Upsert delivery.
MantrixFlow stores checkpoint state only after a successful run. Failed runs do not advance the saved checkpoint.

​
Type compatibility

The ClickHouse path supports common analytical types, including:
  • UInt*, Int*, Float*, Decimal*
  • String, FixedString, LowCardinality(String)
  • Date, DateTime, DateTime64(precision, timezone)
  • UUID, IPv4, IPv6
  • Enum8, Enum16
  • Nullable(...), Array(...), Map(...), Tuple(...), Nested(...)
  • JSON and Object where the engine version supports them
Use a stable primary or unique key for Upsert delivery. For high-precision Decimal and DateTime64 values, prefer the existing destination’s type-compatibility table to avoid lossy conversions.

​
Source reference

The source uses the official clickhouse-connect driver with its clickhousedb SQLAlchemy dialect over the HTTP transport. The destination-side uses the native dlt ClickHouse destination, which supports merge, replace, JSONL/Parquet loading, and the clickhouse_adapter for table-engine hints. The connector does not rely on FINAL rewrites. For ReplacingMergeTree tables, physical duplicate versions may exist until merges occur; treat duplicates as a normal property of the engine and resolve on the destination side when needed.

​
Sample source table

​
Troubleshooting

  • Connection refused: verify host, HTTP port, network allowlist, and firewall rules.
  • Authentication failed: verify username, password, and database name.
  • TLS connection failure: check the Secure / TLS toggle and the HTTP port. For self-hosted ClickHouse on TLS, ensure the certificate is trusted by the ELT runtime.
  • No tables discovered: grant SELECT on the schema and tables. System schemas are filtered out by design.
  • Preview fails: check table permissions and unsupported custom types.
  • Incremental rows missing: confirm the cursor changes on updates and is not null.
  • Duplicate destination rows: use a stable primary key and Upsert delivery.
For a list of pairings validated by the platform, see the ClickHouse source and destination connector reference.