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

# Postgres

> Connect Postgres providers such as Supabase, choose the correct Supabase Session Pooler URL, and execute SQL with Deepline.

[Human guide: work with your agent →](https://deepline.com/docs/human/providers/postgres/guide.md)

> [!NOTE]
>
> Connect an authorized Postgres database and inspect one bounded read before
> considering writes.

Use the Postgres integration to run SQL against a database that your workspace
already owns. Deepline stores the connection details with the same encrypted
workspace-credential system used for API keys. SQL tool calls cannot supply or
override credentials.

## Connect Postgres

In the Deepline dashboard, open **Integrations → Postgres**, then provide either:

* A `postgres://` or `postgresql://` connection string
* Individual host, port, database, user, and password fields

You can also set an optional schema as the session search path. Select
**Connect**, then select **Test**. Deepline shows a success or failure toast with
the connection result.

### Supabase

Use the Supabase Session Pooler connection string. The direct database endpoint
may require IPv6, while the Session Pooler provides a broadly reachable public
endpoint.

1. Open the Supabase project and select **Connect**.
2. Select **Session pooler** as the connection method.
3. Confirm the displayed host, port, and username.
4. Copy the displayed PostgreSQL URI.
5. Replace the password placeholder with the database password.
6. In Deepline, open **Integrations → Postgres → Change credentials**, select
   **Connection string**, and paste the URI.
7. Select **Connect**, then **Test**.

Copy the actual pooler host from [Supabase Connect](https://supabase.com/docs/guides/database/connecting-to-postgres).
Do not construct it from the region. The URI has this illustrative shape:

```text theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
postgresql://postgres.<project-ref>:<url-encoded-password>@<pooler-host-from-dashboard>:5432/postgres
```

> [!WARNING]
>
> URL-encode reserved characters in the password. The `@` before the hostname is
> the user-info separator and must not be preceded by shell-style backslashes.
> For example, encode an `@` inside the password as `%40` and a backslash as
> `%5C`.

## Run SQL

The integration exposes one tool: `postgres_run_query`. It accepts one SQL
statement, positional `binds`, a timeout, and a row limit. `SELECT` and
read-only `WITH` statements are bounded and run in a read-only transaction.
Mutating and DDL statements execute directly without a `write` opt-in flag.
The connected database user's permissions determine which statements are
allowed, so use a read-only database role when writes must be prohibited.

List user tables with the local Deepline CLI:

```bash theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
deepline tools execute postgres_run_query --input '{
  "query": "SELECT table_schema, table_name FROM information_schema.tables WHERE table_type = '\''BASE TABLE'\'' AND table_schema NOT IN ('\''pg_catalog'\'', '\''information_schema'\'') ORDER BY table_schema, table_name",
  "rowLimit": 200,
  "timeoutMs": 30000
}'
```

Inspect declared foreign keys before choosing a join:

```sql theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
SELECT
  tc.table_schema,
  tc.table_name,
  kcu.column_name,
  ccu.table_schema AS foreign_table_schema,
  ccu.table_name AS foreign_table_name,
  ccu.column_name AS foreign_column_name
FROM information_schema.table_constraints tc
JOIN information_schema.key_column_usage kcu
  ON tc.constraint_name = kcu.constraint_name
 AND tc.table_schema = kcu.table_schema
JOIN information_schema.constraint_column_usage ccu
  ON ccu.constraint_name = tc.constraint_name
 AND ccu.table_schema = tc.table_schema
WHERE tc.constraint_type = 'FOREIGN KEY'
ORDER BY tc.table_schema, tc.table_name;
```

For example, a Supabase project containing the PostgreSQL DVD Rental sample
schema can join actors to films through `film_actor`:

```bash theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
deepline tools execute postgres_run_query --input '{
  "query": "SELECT a.actor_id, a.first_name, a.last_name, f.film_id, f.title, f.release_year FROM public.film_actor fa JOIN public.actor a ON a.actor_id = fa.actor_id JOIN public.film f ON f.film_id = fa.film_id ORDER BY a.actor_id, f.film_id LIMIT 10",
  "rowLimit": 10,
  "timeoutMs": 30000
}'
```

The response includes `data.rows`, `data.rowCount`, `data.columns`, the command
tag, and non-secret connection metadata such as the host, database, and schema.

## Connection safeguards

* Postgres credentials are workspace-scoped and encrypted at rest.
* Tool calls always use the saved credential and cannot accept inline database
  credentials.
* Require TLS is enabled by default. It encrypts the connection without
  verifying the server certificate. turning it off disables encryption.
* Private, loopback, link-local, reserved, metadata, and other non-public
  network targets are blocked.
* Deepline resolves and validates DNS answers before pinning the connection to
  an approved public address.
* Keep reads bounded with `rowLimit` and SQL `LIMIT` clauses.

## Verify this task

Verify connection identity and the database role. Check returned rows and limits. Do not confuse connected Postgres permissions with Customer DB rules.

Ask your agent to explain a failed check before repeating work or expanding the scope.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.