> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adriel.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How to connect

> How to connect the Postgres data source to Adriel: allowlist the proxy IP, grant a read-only user, and enter the database connection details.

Postgres (PostgreSQL) is an open-source relational database. Connecting it queries a customer-owned Postgres database as a dashboard data source, so transactional tables, event logs, and custom analytics tables surface in Adriel alongside marketing data sources.

## Before you connect

The following are required:

* A PostgreSQL database (self-hosted, AWS RDS, Cloud SQL, Supabase, Neon, or similar) reachable over the network.
* The connection details for that database: host, port (typically `5432`), database name, username, and password.
* Workspace permission to add a new data source.

Queries reach the database through Adriel's database proxy, so the database only needs to accept connections from the proxy's single egress address, `52.79.160.224`. Allowlist that address in the network firewall (or the cloud provider's security group) and in the host-based rules in `pg_hba.conf`. When direct exposure is not an option, an SSH tunnel to the database works as well.

A read-only role is recommended, because the connector only issues `SELECT` statements. Create one with read rights on the target tables in the `public` schema:

```sql theme={null}
CREATE USER reporter WITH PASSWORD '<strong-password>';
GRANT CONNECT ON DATABASE your_database TO reporter;
GRANT USAGE ON SCHEMA public TO reporter;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO reporter;
ALTER DEFAULT PRIVILEGES IN SCHEMA public
  GRANT SELECT ON TABLES TO reporter;
```

## Connect Postgres

<Steps>
  <Step title="Open the connector">
    On the **Data Sources** page, search for **Postgres** and select it.
  </Step>

  <Step title="Enter the connection details">
    Fill in the fields for the target database:

    | Field        | Required | Notes                                                                                  |
    | ------------ | -------- | -------------------------------------------------------------------------------------- |
    | **Host**     | Yes      | Database hostname or IP. Allowlist `52.79.160.224` if the host sits behind a firewall. |
    | **Database** | Yes      | Name of the database to import.                                                        |
    | **User**     | Yes      | A user with read access to the target tables.                                          |
    | **Password** | Yes      | Password for that user.                                                                |
    | **Port**     | No       | Database port. Defaults to `5432`.                                                     |
  </Step>

  <Step title="Select the table">
    Choose the **Table** to report on. The list shows every table in the `public` schema the connecting user can read. One data source binds to one table; to combine several tables, expose them as a view in `public` and select the view.
  </Step>

  <Step title="Submit">
    Click **Submit** to complete the connection. Initial data availability can take up to one business day.
  </Step>
</Steps>

## What gets imported

Table columns become metrics or breakdowns based on their Postgres type. JSONB columns can be projected into breakdowns with the `column->>'key'` accessor, and ARRAY columns are joined into a delimited string and deduplicated. Null breakdown values are surfaced as the literal `Unknown` so groupings stay visible.

For supported column types, field type mapping, filter operators, string-aggregation modes, caching, and limits, see the [Postgres data reference](/data-sources/o-z/postgres/data-reference).

## Troubleshooting

<AccordionGroup>
  <Accordion title="Connection refused or timeout">
    The database is not reachable from the proxy. Allowlist the egress address `52.79.160.224` in the network firewall and in `pg_hba.conf`, or expose the database through an SSH tunnel.
  </Accordion>

  <Accordion title="Permission denied for table">
    The connecting user lacks `SELECT` on the target table. Run `GRANT SELECT ON TABLE <table> TO <user>` against the target database.
  </Accordion>

  <Accordion title="Tables outside the public schema are missing">
    Table discovery lists only tables in the `public` schema. To expose a table from another schema, create a view in `public` that selects from it, then bind the view.
  </Accordion>

  <Accordion title="Null values appear as 'Unknown' in breakdowns">
    Null breakdown values are converted to the literal `Unknown` in post-processing so the group stays visible in widget output. This is intentional. To remove the bucket, populate the column in the source database or filter the widget to the values that should appear.
  </Accordion>

  <Accordion title="Concern about load on the production database">
    Queries are read-only and use a per-query connection that is closed after the response. Running the connector against a read replica is recommended for high-traffic primaries.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Postgres data reference" href="/data-sources/o-z/postgres/data-reference">
    Query model, field type mapping, caching, and limits for the Postgres data source.
  </Card>

  <Card title="Postgres FAQs" href="/data-sources/o-z/postgres/faqs">
    Common questions and expected behaviors for the Postgres data source.
  </Card>

  <Card title="How to connect MySQL" href="/data-sources/g-n/mysql/how-to-connect">
    Connect the sibling SQL database, with the same view-based patterns.
  </Card>

  <Card title="How to connect Redshift" href="/data-sources/o-z/redshift/how-to-connect">
    Connect the cloud data warehouse alternative for large SQL datasets.
  </Card>

  <Card title="How to connect Snowflake" href="/data-sources/o-z/snowflake/how-to-connect">
    Connect the cloud data platform for warehoused SQL data.
  </Card>
</CardGroup>