Connect a source
Connect PostgreSQL, MySQL or ClickHouse through a read-only user, choose what OpenDash learns, and keep the connection safe.
A source is a database OpenDash reads. Owners and admins connect sources under Data → Connect source.
| Database | Supported versions |
|---|---|
| PostgreSQL | 12 and later, including Neon, Supabase, Amazon RDS and Cloud SQL |
| MySQL | 8.4 and later |
| ClickHouse | 24.3 and later |
Snowflake and BigQuery are on the way.
Connect
Create a read-only user
OpenDash only needs to read. Run this on your database as an admin (replace the password and database name):
-- PostgreSQL
CREATE ROLE opendash_reader LOGIN PASSWORD '…';
GRANT CONNECT ON DATABASE your_database TO opendash_reader;
GRANT USAGE ON SCHEMA public TO opendash_reader;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO opendash_reader;
ALTER DEFAULT PRIVILEGES IN SCHEMA public
GRANT SELECT ON TABLES TO opendash_reader;-- MySQL
CREATE USER 'opendash_reader'@'%' IDENTIFIED BY '…';
GRANT SELECT ON your_database.* TO 'opendash_reader'@'%';-- ClickHouse
CREATE USER opendash_reader IDENTIFIED BY '…'
SETTINGS readonly = 2;
GRANT SELECT ON your_database.* TO opendash_reader;The connect form shows the same SQL with your database name filled in.
Let OpenDash reach the database
Only OpenDash's workers connect to your databases. Allow their address through your firewall. Self-hosted instances can reach private addresses; on a hosted instance, the connect form lists the outbound IPs to allowlist.
Test the connection
Fill in the form and choose Test connection. The check connects as your user and tells you what it can do:
- This user can change data: you can still Connect anyway, but a read-only user is safer. Every query runs in a read-only session regardless.
- This user can't be connected: it reaches beyond the data, and there is no override.
Choose what OpenDash learns
Pick the tables that matter (ten are ticked to start). Picked tables are profiled on every sync. The others are known by name and profiled the first time a question reads them.
Syncs
A sync reads the schema, profiles the tables you picked, and reads how your team queries the database. Choose Daily, Every 6 hours, or Off (sync on demand with Sync now) on the source's Settings tab.
Under Query limits you can set how many queries run in parallel, the statement timeout, and the maximum rows a query may read.
TLS
New sources verify the server's certificate (verify-full) by default: it must chain to a trusted CA and name the host you typed.
| Mode | What it does |
|---|---|
verify-full | Encrypted, and proves which server answered. If your own CA signed the certificate, paste it on the form; OpenDash trusts only it for that source. |
require | Encrypted, but any server answering at this address is accepted. Use only on a private network. |
disable | Everything in clear text. Use only on a private network. |
ClickHouse connects over HTTPS on port 8443 by default.
ClickHouse notes
- Prefer
readonly = 2for OpenDash's user: it can't write, but can take the per-query limits OpenDash sets. - A user with
readonly = 1can't take any per-query setting, so OpenDash accepts it only when the server already enforces what OpenDash would: a time limit of at most 60 seconds that throws, the analyzer on, and UTC. If the server hasjoin_use_nulls = 0, outer joins are refused on that source.
Personal data
Columns OpenDash recognises as personal data can be counted and filtered, but their values are never returned: not in answers, and not in the records behind a number.
Sample data
- Sample company: seed it with
OPENDASH_SEED_DEMO=true(self-hosted) orpnpm demo:seed(development), then connect it like any database. It shows a Sample data chip, and Remove sample data takes it away. - Playground: Use the playground on the connect form connects ClickHouse's public playground (
play.clickhouse.com, userexplorer, no password).