> ## 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.

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. Open **Direct connection string**.
3. Select **Session pooler** as the connection method.
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**.

The resulting URI has this shape:

```text theme={null}
postgresql://postgres.<project-ref>:<url-encoded-password>@<region>.pooler.supabase.com: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`.
</Warning>

## 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={null}
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
}' --json
```

Inspect declared foreign keys before choosing a join:

```sql theme={null}
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={null}
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
}' --json
```

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.