Before You Start
To connect a database, you need:
- Database hostname or IP address -- the server where your database runs
- Port number -- PostgreSQL defaults to 5432, MySQL to 3306
- Database name -- the specific database you want to analyze
- Username and password -- credentials with at least read access
- Network access -- clariBI's servers must be able to reach your database
Firewall and Network Requirements
If your database is behind a firewall, you need to allow inbound connections from clariBI's IP ranges. Contact support for the current IP list.
Connecting PostgreSQL
Step 1: Open the Connection Wizard
Navigate to Data Sources in the sidebar and click Add Source. Select PostgreSQL from the database section.
Step 2: Enter Connection Details
| Field | Description | Example |
|---|---|---|
| Display Name | A friendly name for this source | "Production Analytics DB" |
| Host | Server hostname or IP | db.example.com |
| Port | PostgreSQL port | 5432 |
| Database | Database name | analytics |
| Username | Database user | claribi_reader |
| Password | User password | (hidden) |
Step 3: Configure SSL
For production databases, SSL is strongly recommended. Toggle Use SSL to on. You can provide:
- SSL Mode --
require(encrypts the connection),verify-ca(also verifies the server certificate), orverify-full(also verifies the hostname) - CA Certificate -- upload your certificate authority file if using
verify-caorverify-full
Step 4: Test and Save
Click Test Connection. clariBI attempts to connect, run a simple query, and report back. If successful, you see a green checkmark and the database version. Click Connect.
Recommended User Permissions
Create a dedicated read-only user for clariBI:
CREATE USER claribi_reader WITH PASSWORD 'your_secure_password';
GRANT CONNECT ON DATABASE analytics TO claribi_reader;
GRANT USAGE ON SCHEMA public TO claribi_reader;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO claribi_reader;
ALTER DEFAULT PRIVILEGES IN SCHEMA public
GRANT SELECT ON TABLES TO claribi_reader;
This follows the principle of least privilege -- clariBI only needs read access.
Connecting MySQL
Step 1: Select MySQL
Click Add Source and select MySQL.
Step 2: Enter Connection Details
| Field | Description | Example |
|---|---|---|
| Display Name | Friendly name | "Customer Database" |
| Host | Server hostname or IP | mysql.example.com |
| Port | MySQL port | 3306 |
| Database | Database name | customers |
| Username | Database user | claribi_reader |
| Password | User password | (hidden) |
Step 3: Configure SSL
Toggle Use SSL if your MySQL server requires encrypted connections. Upload the CA certificate if needed.
Step 4: Test and Save
Click Test Connection, verify the result, and click Connect.
Recommended User Permissions
CREATE USER 'claribi_reader'@'%' IDENTIFIED BY 'your_secure_password';
GRANT SELECT ON customers.* TO 'claribi_reader'@'%';
FLUSH PRIVILEGES;
If you want to restrict the connection to clariBI's IP addresses specifically, replace '%' with the IP range provided by clariBI support.
Connecting to Cloud-Hosted Databases
AWS RDS
For Amazon RDS instances:
- Open the RDS console and find your instance endpoint (e.g.,
mydb.abc123.us-east-1.rds.amazonaws.com). - Add clariBI's IP addresses to the RDS security group's inbound rules (port 5432 for PostgreSQL, 3306 for MySQL).
- Use the endpoint as the host in clariBI's connection form.
Google Cloud SQL
For Google Cloud SQL instances, you can either:
- Add clariBI's IPs to the instance's Authorized Networks
- Use the Cloud SQL Proxy via an SSH tunnel
Sync Configuration
After connecting any database, you can configure automatic syncing:
| Frequency | When to Use |
|---|---|
| Manual | Data changes rarely; you prefer to sync on demand |
| Hourly | Data changes frequently throughout the day |
| Daily | Data is updated overnight via ETL processes |
| Weekly | Data is refreshed weekly |
| Custom Cron | You need a specific schedule (e.g., every 6 hours) |
Configure sync frequency in the data source settings page after the initial connection.
Schema and Table Selection
By default, clariBI introspects all accessible tables in the connected database. If your database has many tables, you can:
- Select specific schemas to include
- Select specific tables within those schemas
- Exclude large tables that are not relevant to analysis
- Preview table data by clicking the eye icon next to any table name
This reduces sync time and keeps your data source focused.
Performance Tips
- Create a read replica for analytics queries if your production database is under heavy load. Point clariBI at the replica instead of the primary.
- Use views or materialized views to pre-join and pre-aggregate data. This reduces the data transferred during sync and speeds up analysis.
- Index columns you frequently filter on (dates, categories, foreign keys). While clariBI only reads data, good indexes make read queries faster.
- Schedule syncs during off-peak hours if your database is under heavy write load during business hours.
Troubleshooting
Connection Refused
The database server is not accepting connections on the specified host and port. Verify the hostname, port, and firewall rules. Ensure the database service is running.
Authentication Failed
The username or password is incorrect, or the user does not have permission to connect to the specified database. Double-check credentials and database-level permissions.
SSL Handshake Failure
The SSL configuration does not match the server's requirements. If the server uses a self-signed certificate, make sure you have uploaded the CA certificate or enabled the trust option.
Timeout
The connection attempt took too long. This usually means a firewall is silently dropping packets. Verify that the clariBI IP addresses are allowed through your firewall.
For a complete list of error messages and fixes, see Data Source Errors.