# Integrate PostgreSQL with Databox PostgreSQL is a powerful open-source relational database management system (RDBMS) known for its standards compliance, extensibility, and support for advanced data types. It is widely used across web applications, analytics pipelines, and enterprise systems, and is available as a managed service through providers such as Amazon RDS, Google Cloud SQL, Azure Database for PostgreSQL, Supabase, and Neon. Connecting PostgreSQL to Databox lets you pull data directly from your database, build custom metrics using SQL queries, and visualize business-critical figures alongside data from your other connected tools. ## Connection If you've already established a connection, you can [reuse](/add-a-data-source) it to add new data sources to your Databox account. ### Step 1: Create a read-only PostgreSQL role for Databox Databox only reads data from your database — it never writes to it. Create a dedicated PostgreSQL role with `SELECT`-only privileges on the schemas and tables you want to expose. ```sql CREATE ROLE databox WITH LOGIN PASSWORD 'your_secure_password'; GRANT CONNECT ON DATABASE your_database TO databox; GRANT USAGE ON SCHEMA public TO databox; GRANT SELECT ON ALL TABLES IN SCHEMA public TO databox; ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO databox; ``` Replace `your_database` with the name of the database you want to connect, and `your_secure_password` with a strong password. If you need to expose tables in additional schemas, repeat the `GRANT USAGE` and `GRANT SELECT` statements for each schema. Avoid the following special characters in your PostgreSQL password, as they can cause encoding issues when establishing the connection: ```, `'`, `"`, `/`, `\`, and spaces. ### Step 2: Configure PostgreSQL to accept remote connections By default, PostgreSQL listens only on `localhost` and does not accept external connections. Enabling remote access requires changes to two configuration files. **postgresql.conf** — update the `listen_addresses` setting to allow connections on non-localhost interfaces: 1. Open your PostgreSQL configuration file. The path depends on your version and distribution: - `/etc/postgresql/{version}/main/postgresql.conf` 2. Locate the `listen_addresses` directive and set it to `'*'` (all interfaces) or your server's public IP: ```ini listen_addresses = '*' ``` 3. Save the file. **pg_hba.conf** — add a host-based authentication rule to allow the Databox IP address to connect: 1. Open your client authentication configuration file: - `/etc/postgresql/{version}/main/pg_hba.conf` 2. Add the following line, which permits the `databox` role to connect to all databases from the Databox IP address using password authentication: ``` host all databox 52.4.198.118/32 scram-sha-256 ``` 3. Save the file and restart PostgreSQL to apply both changes: ```bash sudo systemctl restart postgresql ``` If you are using a managed PostgreSQL service (such as Amazon RDS for PostgreSQL, Google Cloud SQL for PostgreSQL, Azure Database for PostgreSQL, Supabase, or Neon), remote connectivity is typically enabled through the service's console or network settings rather than by editing configuration files. ### Step 3: Whitelist the Databox IP address Open port `5432/TCP` for inbound connections from the Databox IP address `52.4.198.118` on your server's firewall or network security rules. The exact steps depend on your infrastructure: - **Linux (iptables):** `iptables -A INPUT -s 52.4.198.118/32 -p tcp --dport 5432 -j ACCEPT` - **AWS RDS:** In the AWS Console, add an inbound rule to your database's security group allowing TCP on port 5432 from `52.4.198.118/32`. - **Other managed services:** Add `52.4.198.118` to your database's IP allowlist in the service's network access settings. ### Step 4: Enter your PostgreSQL connection details in Databox 1. In Databox, go to **Data Sources > + New connection**. 2. Search for **PostgreSQL** and click **Connect**. 3. Fill in the connection form: - **Data source name** — a label for this connection in Databox. - **Host** — the hostname or IP address of your PostgreSQL server. - **Port** — the port PostgreSQL listens on. The default is `5432`. - **User** — the PostgreSQL role name created in [Step 1](#step-1-create-a-read-only-postgresql-role-for-databox). - **Password** — the password for that role. - **Database name** (optional) — the specific database to connect to. Leave blank to connect at the server level. - **Timezone** — the time zone used to interpret date values in query results. Defaults to `Etc/UTC`. 4. Toggle **Use SSL/TLS** to enable encrypted connections. 5. Click **Connect**. connect ## Datasets The PostgreSQL integration supports the creation of [datasets](/understanding-datasets), which allow you to define and shape the specific data you want to use for reporting in Databox. Datasets make it easier to focus on the most relevant information, enabling you to filter, visualize, and analyze metrics across projects, teams, and clients without writing complex queries each time. ### Steps to create a dataset: 1. **Select a table**: Pick the appropriate schema within that database. 2. **Select columns**: Browse and select the specific columns (fields) from your tables or views to include in your dataset. These columns define the structure and content of your dataset. ### Optional: Write SQL For more advanced use cases, you can write a **custom SQL query** instead of selecting columns manually. This allows you to: - Join multiple tables - Apply filters and aggregations - Format or transform data before importing it into Databox Your query must return a valid tabular result to be used as a dataset. ### Additional resources - [PostgreSQL Documentation](https://www.postgresql.org/docs/) — Official PostgreSQL documentation hub covering installation, SQL syntax, server administration, security, replication, and release notes for all supported versions. - [PostgreSQL Current Version Reference](https://www.postgresql.org/docs/current/) — Complete reference for the current PostgreSQL release, including SQL commands, data types, functions, role management, and server configuration. ## Resources For comprehensive details on metrics, data availability, templates, specifications, usage guidelines, and other key information, refer to the resources listed below. Yes. Managed PostgreSQL services are supported. Make sure the database is publicly accessible and that the Databox IP address (`52.4.198.118`) is added to the service's inbound security rules or IP allowlist. For Amazon RDS for PostgreSQL, refer to the AWS documentation for configuring VPC security groups and SSL. For Supabase and Neon, enable external connectivity in the project settings and add `52.4.198.118` to the IP allowlist. Check the following in order: 1. The `listen_addresses` setting in `postgresql.conf` is set to `'*'` or includes your server's public IP 2. A matching rule exists in `pg_hba.conf` for the Databox IP address (`52.4.198.118`) and the `databox` role 3. Your firewall permits inbound TCP traffic on port `5432` from `52.4.198.118` 4. PostgreSQL was restarted after any configuration file changes `postgresql.conf` controls which network interfaces PostgreSQL listens on — without updating `listen_addresses`, the server will not accept any external TCP connections regardless of firewall rules. `pg_hba.conf` is a separate client authentication file that controls which hosts and roles are permitted to connect once a network connection is established. Both files must be configured correctly for Databox to reach your database.   Ask Genie Get instant answers or help with your data using the in-app AI assistant. Talk to an expert For customers: Get help with your setup, strategy, or making the most of Databox. Book a demo New to Databox? See how it works and get guidance on getting started. Send an email Reach out to support for help with your account, data, or technical issues.