Supabase

​

Requirements

• A Supabase project. The free plan works.
• Docker on a host with outbound IPv4 access.
• A Postgres client, such as psql.

​

Setup

1

Copy the session pooler host

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.<project-ref>:[YOUR-PASSWORD]@aws-0-<region>.pooler.supabase.com:5432/postgres

• Host: aws-0-<region>.pooler.supabase.com. Copy it exactly, because some projects use aws-1.
• User: postgres.<project-ref>.

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.

2

Download the Supabase root certificate

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.

3

Write the config

Save this as config.yaml next to the certs folder. Replace the upstream host with yours.

config.yaml

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

4

Validate and start the Sidecar

docker run --rm \
  -v "$PWD/config.yaml:/etc/hoop-inspect/config.yaml:ro" \
  -v "$PWD/certs:/etc/hoop-inspect/certs:ro" \
  hoophq/hoopsidecar:<version> 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:<version>

--validate prints config OK: 1 listener(s) and the rule counts. Versions are on the releases page.

5

Point your clients at the Sidecar

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.<project-ref>@aws-0-<region>.pooler.supabase.com:5432/postgres
after:  postgresql://postgres.<project-ref>@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 and connect with sslmode=require.

​

Verify

psql "postgresql://postgres.<project-ref>@127.0.0.1:15432/postgres?sslmode=disable"

create table customers (id serial primary key, name text, email text);
insert into customers (name, email) values ('Ana Souza', 'ana.souza@example.com');

postgres=> select * from customers;
 id |   name    |          email
----+-----------+--------------------------
  1 | Ana Souza | [REDACTED:EMAIL_ADDRESS]

postgres=> drop table customers;
FATAL:  destructive statements are blocked by Hoop

curl -s 127.0.0.1:19000/api/sessions

{"sessions":[{"principal":"postgres.<project-ref>","protocol":"postgres","connection":"supabase","denied_count":1,"masked_count":1,"verdict":"denied"}],"total":1}

​

Allow only the Sidecar with Network Restrictions

1. Open Database, then Settings, and find Network Restrictions.
2. Click Add restriction, then add the Sidecar’s IP as <ip>/32.

supabase network-restrictions update --project-ref <project-ref> --db-allow-cidr <ip>/32 --experimental

FATAL:  (EADDRNOTALLOWED) address not in tenant allow_list

​

Name who ran each statement

psql "postgresql://alice.<project-ref>@127.0.0.1:15432/postgres?sslmode=disable"

PGOPTIONS='-c hoop.user=alice' psql "postgresql://postgres.<project-ref>@127.0.0.1:15432/postgres?sslmode=disable"

{"principal":"postgres.<project-ref>","metadata":{"postgres.option.hoop.user":"alice"}}

​

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

​

Free and Enterprise

• 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.
• Reviews and central management: connect the Sidecar to a Control Plane, which also needs an Enterprise license. It adds reviews, shared rule sets and one view of many Sidecars.

​

Next