> For the complete documentation index, see [llms.txt](https://docs.soda.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.soda.io/soda-documentation/reference/data-source-reference-for-soda-core/postgresql.md).

# PostgreSQL

Access configuration details to connect Soda to a PostgreSQL data source.

### Connection configuration reference

Install the package `soda-postgres`:

```bash
pip install soda-postgres
```

#### Data source YAML

**Create the config file:**

```shellscript
soda data-source create -f ds_config.yml
```

The data source configuration YAML should look like the following:

{% code title="ds\_config.yml" %}

```yaml
type: postgres
name: my_postgres
connection:
  user: ${env.POSTGRES_USER}
  host: ${env.POSTGRES_HOST}
  port: 5432
  password: ${env.POSTGRES_PW}
  database: ${env.POSTGRES_DB}
```

{% endcode %}

#### Connection test

Test the data source connection:

```bash
soda data-source test -ds ds_config.yml
```

***

## Required permissions

Create a dedicated read-only user for Soda:

```sql
-- Create user
CREATE USER soda_user WITH PASSWORD '...';

-- Grant connection
GRANT CONNECT ON DATABASE <database> TO soda_user;

-- Grant schema access (repeat for each schema Soda should scan)
GRANT USAGE ON SCHEMA <schema> TO soda_user;

-- Grant table read access (current and future tables)
GRANT SELECT ON ALL TABLES IN SCHEMA <schema> TO soda_user;
ALTER DEFAULT PRIVILEGES IN SCHEMA <schema>
  GRANT SELECT ON TABLES TO soda_user;
```

{% hint style="warning" %}
**Schema discovery note:** Soda can only discover schemas that contain at least one table. Empty schemas will not appear in dataset discovery results.
{% endhint %}

{% hint style="info" %}
**Note:** These same permissions apply to compatible PostgreSQL-based sources: AWS Aurora (PostgreSQL-compatible), Google Cloud SQL (PostgreSQL), and Azure Database for PostgreSQL.
{% endhint %}

{% hint style="warning" %}

#### **Row-level security**

If your data source uses row-level security policies (e.g. Row Access Policies in Snowflake, Row-Level Security in PostgreSQL or SQL Server, Row Filters in Databricks Unity Catalog, or equivalent mechanisms in other data sources), **ensure that the Soda connection** user or role **has been granted the appropriate policy exemptions or access**.

Row-level security policies do not cause connection errors or scan failures, but **they silently filter the rows visible to Soda**. This can produce unexpected results. For example, `dataset_rows_tested: 0` even when the dataset clearly contains rows.
{% endhint %}

<br>

***

{% hint style="info" %}
You are **not logged in to Soda** and are viewing the default public documentation. Learn more about [Licensing & documentation access](/soda-documentation/reference/documentation-access-and-licensing.md).
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.soda.io/soda-documentation/reference/data-source-reference-for-soda-core/postgresql.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.