Connect PostgreSQL to clariBI: a complete walkthrough

If your product or orders live in PostgreSQL, connecting it to clariBI lets you build dashboards on those tables and ask questions about them in plain English, next to data from your other tools. This walkthrough covers every step: a read-only database user, network access, the connection form, what a sync actually copies, and the errors people run into most.

The database connections documentation gives the short version. The same steps apply, with small differences, to MySQL (and MariaDB), SQL Server (including Azure SQL) and Oracle. The database connection article has the user-creation SQL for each of them.

How the connection works

Three facts shape everything below:

• clariBI connects from its own servers over the internet. Your database has to accept connections from outside your network. Hosts that are, or resolve to, private, local or internal addresses (such as 10.x, 192.168.x or 127.0.0.1) are refused.
• It only reads. clariBI runs a single SELECT (or WITH ... SELECT) statement at a time; anything containing write keywords, stacked statements or comments is refused. A read-only user makes that true at the database level too.
• It copies tables in on each sync. Each table becomes a dataset inside the data source, up to a row cap per table that depends on your plan (details below). Dashboards and answers are computed from that copy, not by querying your database live.

Before you start

Have these ready:

• Host: a public host name or IP address, for example db.example.com
• Port: optional; PostgreSQL's default 5432 is used if you leave it empty
• Database name, for example analytics
• Username and password for a read-only user (next step)
• Schema (optional): public is used if you leave it empty
• Tables to sync (optional): if you leave this empty, clariBI reads every table the user can see in the schema

Step 1: create a read-only user

Do not connect a BI tool with your application's credentials. Create a user that can read and nothing else. Connect as an admin and run:

CREATE USER claribi_reader WITH PASSWORD 'a-long-random-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;

Replace analytics and public with your database and schema. The last line makes tables created later readable too.

It is also worth capping how long any query from this user can run, so a heavy sync never competes with your application for long:

ALTER USER claribi_reader SET statement_timeout = '60s';

Step 2: open network access

Amazon RDS

Use the instance endpoint (for example mydb.abc123.us-east-1.rds.amazonaws.com) as the host. The instance must be publicly accessible, and its security group needs an inbound rule allowing PostgreSQL on port 5432.

Google Cloud SQL

Enable the instance's public IP and add an authorized network that allows the connection.

Other managed hosts

Supabase and Neon give you a direct connection host, port, database and user in their dashboards; use those. Both are also available as MCP apps in clariBI, which may suit you better than a raw database connection.

Your own server

• Set listen_addresses in postgresql.conf so PostgreSQL listens on the public interface, not only localhost.
• Add a line to pg_hba.conf that allows claribi_reader to connect to your database from outside with scram-sha-256 authentication.
• Open port 5432 in your firewall.
• Reload or restart PostgreSQL.

About IP allowlists

clariBI does not publish a fixed list of outgoing IP addresses. If your firewall can only allow specific IPs, contact support before you rely on one.

Step 3: add the connection in clariBI

1. Click Data Sources in the sidebar. This opens Settings > Integrations. Click Add Data Source.
2. Choose the Databases category, then PostgreSQL.
3. Fill in the form:

1. Click Test Connection. If the host cannot be reached, the attempt gives up after 15 seconds instead of hanging.
2. Click Create Data Source.

The password is encrypted before it is stored. There is no SSL setting in the form; PostgreSQL's standard client behaviour is to use an encrypted connection when the server offers one.

Step 4: what gets synced

clariBI syncs straight away. Each table becomes a dataset, and clariBI builds an automatic dashboard for the source, as it does for every source. Once the first sync finishes you can build dashboards and ask questions.

Each sync copies up to your plan's row cap per table. The cap is 1,000 rows for every data source your plan allows:

If a table is bigger than that, do not sync the raw table. Create a view that aggregates it (daily totals by product instead of individual order lines, for example) and list the view under Tables to sync. That keeps syncs small and puts the full history within the cap. Our SQL guide for business analysts covers GROUP BY and date truncation if you need a refresher.

Step 5: keep it current

There is no incremental sync: each sync reads the listed tables again. clariBI syncs the database when its data is more than a day old and a question, report or dashboard refresh needs it. To sync right away, click Sync now on the source's dashboard, or open the source in Settings > Integrations and click Sync Data. Edit Setup in the same panel changes the host, password or tables without deleting the source or its data.

Step 6: ask your first questions

With the data synced, open Ask clariBI (Trial, Starter, Professional and Enterprise) and try something specific:

• "How many orders were placed each week for the last 12 weeks?"
• "Which 10 customers had the highest order value this quarter?"
• "What share of orders used a discount code, by month?"

Use your column names when a word is ambiguous: "count of distinct customer_id" is clearer than "customers". The first question guide explains sessions and data source selection.

Troubleshooting

Connection refused or timeout. The server is not reachable on that host and port. Check the host name, the port, and that the security group or firewall allows outside connections.

Host refused as private or internal. The host is, or resolves to, a private address. Use the public endpoint.

Authentication failed. Wrong password, or the user may not connect from outside. Check pg_hba.conf and the GRANT CONNECT line. PostgreSQL user names are case-sensitive if they were created in quotes.

Connected, but no tables. The user lacks USAGE on the schema or SELECT on the tables, or the tables are in another schema. Grant on that schema and enter it in the Schema field.

Some rows missing. Check the row cap for your plan. Sync an aggregated view instead of the raw table.

The data source errors article lists other messages and their fixes.

Good habits

• Always use a read-only user.
• Point clariBI at a read replica if the primary database is busy.
• Use views to join and pre-aggregate, and index the columns they filter on, such as dates.
• Change the user's password periodically and update it with Edit Setup.

Next, connect the app that holds the other half of the story, such as Stripe for payments or Google Analytics for traffic, and ask a question that needs both. The PostgreSQL integration page lists what else works well alongside it.