Skip to main content
This guide walks you through connecting a PostgreSQL database to Vizdom, browsing your schema, and creating a dataset you can use in visualizations.

​
Prerequisites

  • A Vizdom workspace with Editor or Admin permissions
  • PostgreSQL database credentials (host, port, database name, username, password)
  • Network access from Vizdom’s servers to your database (see the IP allowlisting warning below)
Vizdom connects to your database from a fixed set of IP addresses. Before proceeding, add Vizdom’s egress IPs to your database firewall allowlist. You can find the current IP list under Settings → Data Sources → Vizdom IP Addresses.

​
Connect a PostgreSQL database

1

Open Data Sources

In the left sidebar, click Settings, then select Data Sources. Click Add New in the top-right corner.
2

Choose a connector

Select PostgreSQL from the list of available connectors. Vizdom also supports MySQL, Redshift, BigQuery, Snowflake, and more — the connection flow is similar for each.
3

Enter connection details

Fill in the connection form with your database credentials:
FieldExample value
Hostdb.example.com
Port5432
Databaseanalytics_prod
Usernamevizdom_readonly
Password(your password)
Enable SSL if your database requires encrypted connections (recommended for production databases).
Create a dedicated read-only database user for Vizdom. This limits exposure if credentials are ever compromised and prevents accidental writes. A minimal grant looks like:
CREATE USER vizdom_readonly WITH PASSWORD 'your_password';
GRANT CONNECT ON DATABASE analytics_prod TO vizdom_readonly;
GRANT USAGE ON SCHEMA public TO vizdom_readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO vizdom_readonly;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO vizdom_readonly;
4

Test the connection

Click Test Connection. Vizdom attempts to connect to your database and returns one of:
  • Connection successful — your credentials and network access are correct.
  • Connection failed — check the error message. Common causes are listed in the troubleshooting tips below.
Do not save the data source until the test passes.
5

Save the data source

Give your connection a descriptive name (for example, Production Analytics DB) and click Save. The data source now appears in your Data Sources list.
6

Browse the schema

Click your new data source to open the schema browser. Vizdom introspects your database and displays:
  • Tables and views in the left panel
  • Columns, data types, and nullable flags when you expand a table
  • A row count estimate for each table
Use the search bar at the top to filter by table or column name.
7

Create a dataset

Click New Dataset in the schema browser toolbar. You can build a dataset in two ways:Table selector — select a table from the dropdown and optionally filter rows. Best for simple, full-table access.SQL query — write a custom query for joins, aggregations, or transformations. For example:
SELECT
  date_trunc('day', created_at) AS day,
  country,
  COUNT(*) AS signups,
  SUM(revenue_usd) AS revenue
FROM orders
WHERE created_at >= NOW() - INTERVAL '90 days'
GROUP BY 1, 2
ORDER BY 1 DESC;
Click Run to preview the results, then click Save Dataset and give it a name (for example, Signups & Revenue – Last 90 Days).

​
Troubleshooting common connection issues

Connection timed out Your database is not reachable from Vizdom’s servers. Verify that your firewall allowlist includes Vizdom’s egress IPs and that the host and port are correct. Authentication failed Double-check the username and password. Passwords are case-sensitive. If you recently rotated credentials, update them in Settings → Data Sources → Edit. SSL required / SSL not supported Toggle the SSL option to match your database’s requirement. If your database uses a self-signed certificate, upload the CA certificate in the Advanced section of the connection form. Schema not visible after connecting The database user may lack USAGE on the schema or SELECT on the tables. Re-run the permission grants in the tip above, then click Refresh Schema in the schema browser. Query times out Vizdom enforces a 30-second query timeout on dataset previews. Add an index on columns used in WHERE and GROUP BY clauses, or narrow the date range in your query.