Skip to main content
Connect Supaboard to a ClickHouse database for direct querying, schema discovery, and AI-powered analysis.

​
Before you connect

Network access — Supaboard connects from a fixed set of egress IPs. Add them to your ClickHouse server or ClickHouse Cloud service’s IP allow-list before attempting a connection. The current IP list is shown inside the connector form under Whitelist IPs. Database user permissions — The user you provide needs at minimum:
  • SELECT privilege on the target database and tables
See Recommended database user permissions for the exact SQL.

​
Connection fields

FieldDefaultRequiredDescription
Display Name—YesLabel shown in the Supaboard UI
HostlocalhostYesHostname or IP of your ClickHouse server
Port9000YesClickHouse native TCP port (see note below)
Username—NoClickHouse user; defaults to default if left blank
Password—NoPassword for the ClickHouse user
Database—YesDatabase name to connect to
Port note — Supaboard connects over the native TCP protocol on port 9000. This is different from the HTTP interface (port 8123) and the HTTPS interface (port 8443). ClickHouse Cloud uses port 9440 for secure native TCP — check your Cloud service details if 9000 does not connect.

​
Finding your connection details

​
ClickHouse Cloud

  1. Open clickhouse.cloud and select your service.
  2. On the service detail page, go to Connect.
  3. Select Native as the connection method.
  4. Copy the Host (format: xxxxx.clickhouse.cloud) and Port (typically 9440 for secure native TCP on ClickHouse Cloud).
  5. Use the default user or a custom user you have created.
  6. Under Security → IP Access List, add each Supaboard egress IP to allow connections.
ClickHouse Cloud uses port 9440 (TLS-enabled native TCP), not 9000. Update the Port field accordingly.
Documentation: ClickHouse Cloud connection details · IP access list

​
Self-hosted ClickHouse

  1. Your Host is the server’s IP address or hostname.
  2. The default native TCP Port is 9000.
  3. Check /etc/clickhouse-server/config.xml (or config.d/) for any custom port configuration.
  4. Ensure the server’s firewall allows inbound TCP on port 9000 from Supaboard egress IPs.
Documentation: ClickHouse server configuration · Access control and account management

​
Recommended database user permissions

-- Create a read-only user
CREATE USER supaboard IDENTIFIED BY 'strong_password_here';

-- Grant SELECT on a specific database
GRANT SELECT ON your_database.* TO supaboard;

-- Optionally allow database discovery
GRANT SHOW DATABASES ON *.* TO supaboard;
GRANT SHOW TABLES ON your_database.* TO supaboard;
Replace your_database with the target database name. For multiple databases, repeat the GRANT SELECT line for each one.

​
Troubleshooting

ErrorLikely causeFix
Connection refusedWrong host/port or firewall blockingVerify host and port; add Supaboard IPs to the allow-list
Authentication failedWrong username or passwordVerify credentials; confirm user exists with SELECT name FROM system.users
Database X doesn't existDatabase name typoCheck with SHOW DATABASES
Code 516: supaboard: Authentication failedUser exists but wrong passwordReset the user password: ALTER USER supaboard IDENTIFIED BY 'new_password'
Timeout on port 9000ClickHouse Cloud uses port 9440Update Port to 9440 for ClickHouse Cloud services
Last modified on March 11, 2026