Connecting ClickHouse to Bicycle

Learn how to create a read-only user, retrieve connection details, and connect your ClickHouse database to Bicycle.

Requirements

To follow the steps in this guide, you'll need:

Permission to create connectors in Bicycle
A ClickHouse Cloud service or self-hosted ClickHouse instance Bicycle can reach over HTTPS
ClickHouse permissions to create a database user and grant read access, or an existing user with SELECT on the target database
If your ClickHouse host restricts access by IP address, allow Bicycle network access before connecting

Official ClickHouse documentation

Prepare ClickHouse access

Create a dedicated read-only user for Bicycle. Do not use personal ClickHouse credentials for production connections.

Retrieve ClickHouse connection details

In ClickHouse Cloud, open the service Bicycle should connect to.
Click Connect in the side navigation.
Copy the connection details:
- Host — hostname only (for example, abc123.eastus2.azure.clickhouse.cloud). Do not include https://.
- Port — typically 8443 for HTTPS
- Database — typically default
- Username — often default in ClickHouse Cloud
- Password

note

If you paste a host value that includes https://, Bicycle strips the protocol prefix automatically.

Create a user and grant read access

Run the following in ClickHouse. Replace placeholders with values from your environment.

Create Bicycle user and grant read access
CREATE USER IF NOT EXISTS bicycle_user IDENTIFIED WITH sha256_password BY '<secure_password>';

GRANT SELECT ON your_database.* TO bicycle_user;

GRANT SELECT ON INFORMATION_SCHEMA.SCHEMATA TO bicycle_user;
GRANT SELECT ON INFORMATION_SCHEMA.TABLES TO bicycle_user;

Allowlist Bicycle network access

If your ClickHouse service is only reachable from specific IP addresses or network rules, work with your ClickHouse administrator to allow inbound traffic before you create the connection in Bicycle. Bicycle does not configure IP allowlists or validate network access during connection setup — blocked network access appears as a failed Test connection.

For ClickHouse Cloud, add the IPs in your service access settings. For self-hosted ClickHouse, update firewall or security group rules on the host.

Contact your Bicycle administrator for the IP addresses to allowlist. Bicycle does not display these addresses in the Connectors UI.

Setup in Bicycle

Open Connectors and select ClickHouse

In Bicycle, go to Connectors. Find ClickHouse and click + Connect.

Choose Username + Password

Enter a connection name that identifies the environment, such as ClickHouse Production. Select Username + Password as the Connector method, then click Next.

Add ClickHouse connection details

On the Add details step, fill in the ClickHouse connection fields.

HostRequired

ClickHouse hostname only, without the https:// prefix (for example, abc123.eastus2.azure.clickhouse.cloud)

PortDefault: 8443

ClickHouse port. Defaults to 8443 if omitted

DatabaseRequired

Database Bicycle should connect to (for example, default)

Table Pattern

Optional regex used to filter discovered table names, for example orders_.*

Use SSL

Encrypts the connection to ClickHouse. Enabled by default; ClickHouse Cloud requires TLS

UsernameRequired

ClickHouse username (for example, bicycle_user)

PasswordRequired

Password for the ClickHouse user

Example values

Host: abc123.eastus2.azure.clickhouse.cloud
Port: 8443
Database: default
Table Pattern: orders_.*
Use SSL: enabled (default)
Username: bicycle_user

Test the connection

Click Test connection. When the test succeeds, you will see Ready to add this connection.

Add the connection

Click Add connection. When the connection is created successfully, you will see a confirmation with the connection name, ID, and method (Username + Password). Click Close to return to the Connectors page.

Troubleshooting

If Test connection fails, check the following.

Error or symptom	Likely cause	Fix
`Host is required`	The Host field is empty	Enter the ClickHouse hostname from the Connect dialog
`Invalid host format...`	The host contains unsupported characters	Use the hostname only — no `https://`, path, or port in the Host field
`Database is required`	The Database field is empty	Enter the target database name (for example, `default`)
`Username/password authentication is required`	Username or Password is missing	Enter both fields from your ClickHouse credentials
Failed to connect to ClickHouse	Wrong host or port, TLS disabled, blocked network access, or invalid credentials	Confirm host, port, and Use SSL settings; verify IP allowlist rules; test the username and password in ClickHouse
Connection succeeds but no tables are discovered	Missing `SELECT` grants on the database or `INFORMATION_SCHEMA`	Run the grant SQL for the target database, `INFORMATION_SCHEMA.SCHEMATA`, and `INFORMATION_SCHEMA.TABLES`

Requirements​

Prepare ClickHouse access​