5.2.51. Supavisor

1. Overview

Supavisor is Atlas's optional Supabase Postgres transaction pooler. It protects supabase-db from connection growth as backend workers, workflows, notebooks, and data services expand.

This first slice is deliberately conservative: Supavisor is disabled by default and only routes backend, the Celery worker, n8n, and n8n-worker through transaction mode when enabled.

2. Access

Supavisor speaks the Postgres wire protocol on transaction port 6543 inside the container. Atlas keeps that listener internal-only in this first slice, so it does not consume a host port and does not participate in the topology port-slot allocator.

There is no Kong alias for Supavisor. The management API stays internal-only in this slice because it is not a browser dashboard and should not be exposed as a public Atlas route.

3. Configuration

Set SUPAVISOR_SOURCE=container to enable the pooler. Leave SUPAVISOR_SOURCE=disabled for the default direct-Postgres behavior.

Key variables:

Variable	Purpose
SUPAVISOR_SOURCE	disabled or container.
SUPAVISOR_TENANT_ID	Tenant suffix appended to the Postgres user. Default: atlas.
SUPAVISOR_DEFAULT_POOL_SIZE	Per-user upstream pool size. Default: 20.
SUPAVISOR_MAX_CLIENT_CONN	Maximum accepted client connections. Default: 100.
SUPAVISOR_DB_POOL_SIZE	Supavisor metadata DB pool size. Default: 5.
SUPAVISOR_VAULT_ENC_KEY	Exactly 32 bytes; generated by the bootstrapper when blank.

Generated client variables:

Variable	Enabled value	Disabled rollback value
SUPAVISOR_DATABASE_URL	postgresql://${SUPABASE_DB_USER}.${SUPAVISOR_TENANT_ID}:...@supavisor:6543/${SUPABASE_DB_NAME}	Direct supabase-db:5432 URL
SUPAVISOR_DB_HOST	supavisor	supabase-db
SUPAVISOR_DB_PORT_VALUE	6543	5432
SUPAVISOR_DB_USER	${SUPABASE_DB_USER}.${SUPAVISOR_TENANT_ID}	${SUPABASE_DB_USER}

4. Architecture & wiring

Supavisor depends on supabase-db-init, runs /app/bin/migrate, evaluates pooler/pooler.exs, then starts the pooler server. The pooler.exs tenant bootstrap creates the Atlas tenant and maps the configured Supabase DB user to transaction mode.

Pooled consumers in this slice:

Consumer	Pooled setting
backend	DATABASE_URL=${SUPAVISOR_DATABASE_URL:-...direct...}
Celery worker	DATABASE_URL=${SUPAVISOR_DATABASE_URL:-...direct...}
n8n	DB_POSTGRESDB_HOST/PORT/USER from generated Supavisor envs
n8n-worker	Mirrors n8n DB settings

Direct Supabase consumers intentionally remain direct until session/native behavior is proven:

Direct consumer	Reason
PostgREST (supabase-api)	Session-sensitive API surface; not part of the first transaction-mode audit.
Realtime	Replication/session behavior stays direct.
GoTrue/Auth	Core Supabase service; direct until separately validated.
Storage, Meta, Studio	Core Supabase internals stay on supabase-db:5432.
supabase-db-init, postgres-exporter	Bootstrap and scrape paths stay direct.

5. Dependencies & Integrations

5.1. Current — Upstream (this service calls)

Service	Category
supabase	data

5.2. Current — Downstream (services that call this)

Service	Category
celery	agents
n8n	agents
backend	apps

5.3. Architecture diagram

Open the full-size diagram for a full-screen view.

5.4. Future — Missing pair integrations

No high-confidence opportunities identified.

5.5. Future — Candidate new services

No high-confidence opportunities identified.

5.6. Future — Unused features in this service

No high-confidence opportunities identified.

6. Rollback

Set SUPAVISOR_SOURCE=disabled and rerun ./start.sh. The bootstrapper regenerates SUPAVISOR_DATABASE_URL, SUPAVISOR_DB_HOST, SUPAVISOR_DB_PORT_VALUE, and SUPAVISOR_DB_USER back to direct supabase-db:5432 values, so backend, Celery, and n8n return to the pre-Supavisor path without compose-file edits.

7. Troubleshooting

• FATAL: Tenant or user not found: confirm the client username includes the tenant suffix, for example ${SUPABASE_DB_USER}.${SUPAVISOR_TENANT_ID}.
• VAULT_ENC_KEY errors: make sure SUPAVISOR_VAULT_ENC_KEY is exactly 32 bytes. The bootstrapper generates this when the value is blank.
• Backend or n8n auth failures after enabling: set SUPAVISOR_SOURCE=disabled to roll back, then inspect Supavisor tenant bootstrap logs.
• No Kong alias or host port is expected. v1 consumers connect over the Compose network at supavisor:6543.