> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.hoop.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Supabase
> Guardrails, data masking and audit in front of a Supabase Postgres database, with no app code change.
The Sidecar runs in your infrastructure, between your Postgres clients and the Supabase connection pooler.
Clients change only the host and port of their connection string. Every statement from an AI agent, from a developer in `psql`, or from an application then passes through your guardrails, masking rules and audit trail.
The Sidecar sees Postgres connections only. Supabase's HTTPS APIs (PostgREST and `supabase-js`, Storage, Auth, Realtime) and the dashboard SQL editor reach the database inside Supabase, so their traffic does not pass through the Sidecar.
***
## Requirements
* A Supabase project. The free plan works.
* Docker on a host with outbound IPv4 access.
* A Postgres client, such as `psql`.
***
## Setup
In the Supabase dashboard, click **Connect**, open the **Direct** tab and select **Session pooler**.
The URI below the options holds the two values you need:
```
postgresql://postgres.:[YOUR-PASSWORD]@aws-0-.pooler.supabase.com:5432/postgres
```
* **Host:** `aws-0-.pooler.supabase.com`. Copy it exactly, because some projects use `aws-1`.
* **User:** `postgres.`.
| Connection method | Use with the Sidecar |
| - | - |
| Session pooler, port `5432` | **Yes.** IPv4, and one server connection per client, like a direct connection. |
| Direct connection | Only from a host with IPv6 egress, or with the IPv4 add-on. It is IPv6 only by default. |
| Transaction pooler, port `6543` | No. It does not support prepared statements, which most drivers and ORMs use. |
Open **Database**, then **Settings**. In **SSL configuration**, click **Download certificate** and save the file as `certs/supabase-root.crt`.
The pooler presents a certificate signed by Supabase's own CA (`Supabase Root 2021 CA`). That CA is not in public trust stores, so the Sidecar needs this file to verify the pooler.
Save this as `config.yaml` next to the `certs` folder. Replace the `upstream` host with yours.
```yaml config.yaml theme={"dark"}
admin:
listen: 0.0.0.0:19000
audit:
file: "-"
query_sessions: 500
guardrails:
rules:
- name: no-destructive-sql
type: operation
operations: [drop, delete, truncate]
message: destructive statements are blocked by Hoop
mask:
rules:
- {name: emails, entities: [EMAIL_ADDRESS], strategy: redact}
listeners:
- name: supabase
protocol: postgres
listen: 0.0.0.0:15432
upstream: aws-0-.pooler.supabase.com:5432
upstream_tls:
ca_file: /etc/hoop-inspect/certs/supabase-root.crt
```
* `guardrails` blocks `DROP`, `DELETE` and `TRUNCATE`.
* `mask` replaces email addresses in results.
* `audit` writes every statement to stdout as JSON lines, and `query_sessions` turns on the `/api/sessions` endpoint.
* `upstream_tls` encrypts the hop to Supabase and verifies it against the root certificate.
* `admin` serves health checks and the audit API. It has no authentication, so the next step publishes it on loopback only.
The config holds no database password. The Sidecar relays the login from the client to Supabase.
```bash theme={"dark"}
docker run --rm \
-v "$PWD/config.yaml:/etc/hoop-inspect/config.yaml:ro" \
-v "$PWD/certs:/etc/hoop-inspect/certs:ro" \
hoophq/hoopsidecar: hoop start sidecar --validate
docker run -d --name hoop-supabase \
-p 127.0.0.1:15432:15432 -p 127.0.0.1:19000:19000 \
-v "$PWD/config.yaml:/etc/hoop-inspect/config.yaml:ro" \
-v "$PWD/certs:/etc/hoop-inspect/certs:ro" \
hoophq/hoopsidecar:
```
`--validate` prints `config OK: 1 listener(s)` and the rule counts. Versions are on the [releases page](https://github.com/hoophq/hoop/releases).
Change the host and port. The user, password and database stay the same. Every client takes the same change: the MCP server or `psql` an AI agent uses, a developer's `psql`, and application drivers.
```
before: postgresql://postgres.@aws-0-.pooler.supabase.com:5432/postgres
after: postgresql://postgres.@127.0.0.1:15432/postgres?sslmode=disable
```
`sslmode=disable` applies only to the hop from the client to the Sidecar on the same host. When clients reach the Sidecar over a network, turn on [`downstream_tls`](/docs/setup/configuration/hoop-sidecar/protocols/postgres#tls-on-each-leg) and connect with `sslmode=require`.
***
## Verify
Create a test table through the Sidecar:
```bash theme={"dark"}
psql "postgresql://postgres.@127.0.0.1:15432/postgres?sslmode=disable"
```
```sql theme={"dark"}
create table customers (id serial primary key, name text, email text);
insert into customers (name, email) values ('Ana Souza', 'ana.souza@example.com');
```
A select returns the email masked:
```
postgres=> select * from customers;
id | name | email
----+-----------+--------------------------
1 | Ana Souza | [REDACTED:EMAIL_ADDRESS]
```
A destructive statement is refused with your message:
```
postgres=> drop table customers;
FATAL: destructive statements are blocked by Hoop
```
The audit lists each session with its principal and counts (fields trimmed):
```bash theme={"dark"}
curl -s 127.0.0.1:19000/api/sessions
```
```json theme={"dark"}
{"sessions":[{"principal":"postgres.","protocol":"postgres","connection":"supabase","denied_count":1,"masked_count":1,"verdict":"denied"}],"total":1}
```
***
## Allow only the Sidecar with Network Restrictions
Supabase Network Restrictions limit which IP addresses can connect to Postgres and the pooler.
Allow only the Sidecar's egress IP, and no client with another IP can connect to Supabase directly and skip your rules. Workloads that share the Sidecar's host or NAT gateway keep that access, so give the Sidecar a static egress IP of its own.
1. Open **Database**, then **Settings**, and find **Network Restrictions**.
2. Click **Add restriction**, then add the Sidecar's IP as `/32`.
Or with the Supabase CLI:
```bash theme={"dark"}
supabase network-restrictions update --project-ref --db-allow-cidr /32 --experimental
```
A connection from any other IP fails before it reaches the database:
```
FATAL: (EADDRNOTALLOWED) address not in tenant allow_list
```
Network Restrictions cover Postgres only, so Supabase's HTTPS APIs keep working. Edge Functions lose direct database access and must use `supabase-js`.
***
## Name who ran each statement
By default every client connects as `postgres.`, so the audit shows one shared user. Two ways give each statement a name.
**A role per person.** Create a Postgres role for each person and connect as `.`. The audit records that role as the principal.
```bash theme={"dark"}
psql "postgresql://alice.@127.0.0.1:15432/postgres?sslmode=disable"
```
**A tag on the connection.** Send a custom setting in the startup options. The Sidecar records it on every event of the session, and Supabase accepts it.
```bash theme={"dark"}
PGOPTIONS='-c hoop.user=alice' psql "postgresql://postgres.@127.0.0.1:15432/postgres?sslmode=disable"
```
```json theme={"dark"}
{"principal":"postgres.","metadata":{"postgres.option.hoop.user":"alice"}}
```
See [trace ids from the startup packet](/docs/setup/configuration/hoop-sidecar/protocols/postgres#trace-ids-from-the-startup-packet) to choose which options the Sidecar records.
The audit records the full statement text. Run `CREATE ROLE ... PASSWORD` from the Supabase SQL editor, so the password does not go through the Sidecar.
***
## Behavior to know
* **A denied statement closes the connection.** The client reads the message as `FATAL` `42501`, and Postgres rolls back the open transaction. Connection pools open a new connection. See [denials the user can read](/docs/core-concepts/sidecar#denials-the-user-can-read).
* **Supabase errors reach the client unchanged.** A login or Network Restrictions failure reads the same with or without the Sidecar.
* **The Sidecar removes channel binding.** It offers `SCRAM-SHA-256` instead of `SCRAM-SHA-256-PLUS`, with the same password. See [TLS on each leg](/docs/setup/configuration/hoop-sidecar/protocols/postgres#tls-on-each-leg).
***
## Free and Enterprise
**Free tier:** one Data Masking rule and one Guardrail per Sidecar are free, forever. Running more than one rule per feature, or managing rules centrally across Sidecars, requires [Enterprise](https://hoop.dev/start).
* **More rules:** an Enterprise license with the guardrails and data-masking features lifts the one-rule caps, with or without a Control Plane. In Docker, pass it with `-e HOOP_LICENSE="$(cat license.json)"`. See [Licensing](/docs/setup/configuration/hoop-sidecar/config-file#licensing).
* **Reviews and central management:** connect the Sidecar to a [Control Plane](/docs/core-concepts/control-plane), which also needs an Enterprise license. It adds reviews, shared rule sets and one view of many Sidecars.
***
## Next
Write rules that block statements by operation, table or content.
Choose entity types, columns and masking strategies.
What the Postgres lane decodes, terminates and masks.
Every section and field of `config.yaml`.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.