supabase/supavisor

Supavisor is a PostgreSQL proxy built in Elixir and Rust that manages database connections through pooling, tenant isolation, and multiple authentication methods including SCRAM and Just-In-Time access. It provides resilience features such as circuit breakers, read-replica support, and SSL/TLS enforcement, while offering a web API for cluster and tenant management alongside Prometheus metrics. The system supports distributed clustering via Postgres and is designed for high-concurrency deployments with hot-upgrade capabilities.

25 changes.

This period established the foundational structure of the Supavisor project, including development tooling, configuration, and database schema migrations. It introduced the core PostgreSQL proxy logic with connection pooling, SCRAM authentication, and circuit breaker protection, alongside a Phoenix-based web API for cluster and tenant management. The work also included comprehensive test suites, native Rust parsing capabilities, and deployment configurations for Fly.io and systemd.

12 changes.

This period focused on implementing Just-In-Time (JIT) database authentication with PAM integration and establishing the necessary test infrastructure, including certificate generation and development setup scripts. Significant effort was also directed toward expanding test coverage across the protocol layer, client handlers, monitoring plugins, and prepared statement storage strategies to ensure robustness.

New view modules (ChangesetView, ClusterTenantsView, ClusterView, TenantView, UserView, ErrorView, ErrorHelpers) have been added to the web layer to handle JSON serialization for API responses. These views define how cluster, tenant, user, and network ban data is structured in JSON output, including support for error translation and specific endpoints like connection termination results.

_lib/supavisor\web/views · high confidence

Introduces a new clustering strategy that uses Postgres LISTEN/NOTIFY to determine cluster topology. Nodes broadcast heartbeats to a shared channel, allowing other nodes to discover and connect to them. The strategy requires a database URL and supports optional configuration for heartbeat intervals and channel names.

lib/cluster · high confidence

A new Fail2ban filter configuration file has been added to detect and ban clients based on Supavisor error logs, specifically targeting 'Exchange error' and 'User not found' messages.

contrib · high confidence

A new Nix package definition (nix/package.nix) has been added to the project, enabling users to build and install Supavisor using the Nix package manager. The package configures the build environment to handle both Elixir dependencies (via mix) and native Rust components (via cargo), including specific build inputs for macOS systems such as libiconv and various Apple frameworks.

nix · high confidence

The development environment now includes a SQL setup script that initializes standard roles (anon, authenticated, service\_role) with appropriate schema permissions and creates the \_supavisor schema. Additionally, two PostgreSQL client authentication configuration files (pg\_hba.conf) are provided for MD5 and cleartext password authentication modes, allowing developers to configure local and external connection security policies for the database.

dev · high confidence

The \priv/repo\ directory now includes \seeds.exs\, \seeds\_before\_migration.exs\, and \seeds\_after\_migration.exs\ to automate the population of the database. These scripts create a \\_supavisor\ schema and pre-configure multiple tenants with various user profiles, pool sizes, connection modes (transaction and session), and feature flags (such as named prepared statements), providing a standardized environment for local development and integration testing.

priv/repo · high confidence

Users can now deploy the application using Fly.io or standard systemd services. A new Fly.io configuration file (fly.toml) defines the app as 'supavisor-staging', sets up HTTP/HTTPS listeners on ports 80 and 443, and exposes a TCP service on port 7654 with a concurrency limit of 16384 connections. Additionally, systemd support is provided via a service unit file (supavisor.service) and an environment variables template (service\_vars.ini), allowing the application to be managed as a system service with automatic restarts.

deploy · high confidence

The rel/overlays directory now includes shell and batch scripts (migrate, migrate.bat, server, server.bat) to facilitate running database migrations via the Supavisor.Release.migrate module and starting the application server with the PHX\_SERVER environment variable enabled.

rel/overlays · high confidence

The application now includes a standard set of configuration files (config.exs, dev.exs, prod.exs, runtime.exs, test.exs) to manage environment-specific settings. This structure introduces runtime configuration for cluster topology via libcluster (supporting DNSPoll, Epmd, and Postgres strategies), enables configurable metrics pushing to remote endpoints, and sets up SSL/TLS handling for upstream and downstream connections using environment variables for certificate paths. It also configures the Ecto repository, Phoenix endpoint, and logging metadata for development, production, and test environments.

config · high confidence

This change introduces the foundational configuration files for the Supavisor project, establishing the development environment and build standards. It includes the Elixir formatter settings, Credo linting rules, and Sobelow security scanner configuration. It also defines the specific toolchain versions for Erlang (27.3.4.16), Elixir (1.18.5), and Rust (1.84.1) via \.tool-versions\, alongside a Dockerfile and Makefile to standardize local development, testing, and containerized releases.

(repo-wide) · high confidence

This change introduces the initial codebase for Supavisor, a PostgreSQL proxy. The \lib/supavisor.ex\ module establishes the core proxy logic, including connection pooling, tenant management, and support for transaction, session, and native modes. It also adds a \lib/supavisor\_web.ex\ entry point that configures the Phoenix-based web interface for controllers, views, routers, and channels.

lib · high confidence

The native/pgparser module has been introduced, providing a Rust-based library that exposes PostgreSQL query parsing capabilities to the host application via Rustler. This change adds a new \statement\_types\ NIF, allowing users to identify the types of SQL statements (e.g., SELECT, INSERT) within a given query string, effectively establishing the foundational parsing logic for the parser component.

native/pgparser · high confidence

This change introduces the foundational web layer for Supavisor, establishing a Phoenix-based HTTP server with a structured API. It includes an OpenAPI specification (generated via OpenApiSpex) that documents Tenant and User schemas, along with a Swagger UI endpoint for interactive documentation. The router defines RESTful endpoints for managing tenants (CRUD, termination, credential updates, network bans) and clusters, as well as a metrics endpoint. Additionally, it implements a WebSocket proxy at /v2 to tunnel TCP traffic to the local database proxy, and configures telemetry for monitoring Phoenix, database, and VM metrics.

_lib/supavisor\web · high confidence

This change adds the foundational components for Just-In-Time (JIT) database authentication. It introduces a PAM module (\pam\_jit\_pg.so\) built via a dedicated Dockerfile, configured to delegate authentication to a new Python-based API service (\jit\_api\_service\) via \pam.d/postgresql\. The PostgreSQL container is updated to enforce SSL connections using generated test certificates and utilizes PAM for authentication in \pg\_hba.conf\. Additionally, a mock API server is included to simulate authentication responses for testing purposes.

priv/jit · high confidence

The web API now includes controllers for managing database clusters and their associated tenants, as well as exposing Prometheus metrics. Users can create, read, update, and delete clusters via the new \ClusterController\, and manage cluster-tenant mappings via \ClusterTenantsController\. Additionally, a \MetricsController\ exposes cluster-wide and per-tenant metrics at \/metrics\ and \/metrics/:external\_id\, with configurable process tuning for the metrics handler.

_lib/supavisor\web/controllers · high confidence

Added two new Mix tasks, \supavisor.gen.appup\ and \supavisor.gen.relup\, to the \lib/tasks\ directory. These tasks allow users to manually generate \appup\ and \relup\ files required for hot code upgrades by specifying source and target versions, supporting the generation of soft upgrade tarballs and manual appup workflows.

lib/tasks · high confidence

Added three new shell scripts to the project: \scripts/gen-test-certs.sh\ generates test CA and server certificates (RSA and ECDSA) for local testing; \scripts/jit\_dev\_setup.sh\ automates the setup of a JIT development environment by generating certificates, starting Docker services, configuring downstream certs, and creating a test tenant; and \scripts/test\_upgrade.sh\ facilitates manual hot-upgrade testing between versions by building releases, starting the old version, and performing the upgrade to the current branch.

scripts · high confidence

The lib/supavisor directory now contains the core proxy implementation, including the Application supervisor, ClientHandler for managing incoming PostgreSQL connections, and a dedicated AuthQuery module for fetching user secrets from upstream databases. Authentication is handled via a new ClientAuthentication system that supports SCRAM-SHA-256, cleartext password, and Just-In-Time (JIT) access methods, with secrets cached in Cachex and rate-limited refreshes. To improve resilience, a CircuitBreaker module with an atomic sliding-window counter and a Janitor process protects pool operations from cascading failures by temporarily blocking connections when thresholds are exceeded.

lib/supavisor · high confidence

This change adds the necessary \appup\ files to support seamless hot-upgrades from version 2.9.0 (and rc.4) to versions 2.9.5, 2.9.6, and 2.9.7. These upgrade scripts define the module loading, purging, and state migration steps required to safely transition the system, including handling changes to the \DbHandler\, \ClientHandler\, and \SecretChecker\ modules, as well as the introduction of \ConnectBackoff\ and \PromEx\ plugins.

relups · high confidence

The release environment scripts (rel/env.sh.eex, rel/env.bat.eex) and VM arguments (rel/vm.args.eex) have been added to support deployment on Fly.io and optimize distributed node communication. The shell script automatically detects the Fly.io local 6pn IP address or falls back to the hostname, sets the node name based on environment variables, and enables JPperf symbols on Linux. The VM arguments configure the Erlang VM with increased process limits (1,000,000), expanded ETS name table size, and specific distribution port ranges (20000-21000) with tuned socket buffers and nodelay settings for improved network performance.

rel · high confidence

The internal database schema for the Supavisor management system has been updated to support advanced connection management, security, and operational features. New migrations introduce read-replica support via the \clusters\ and \cluster\_tenants\ tables, enforce SSL/TLS configuration with \upstream\_ssl\ and \enforce\_ssl\ fields, and enable Just-In-Time (JIT) access through \use\_jit\ and \jit\_api\_url\. Operational controls now include tenant banning (\banned\_at\, \ban\_reason\), IP allow-listing (\allow\_list\), availability zone tracking, and configurable pool strategies (\fifo\/\lifo\) and idle timeouts. The \users\ table has been extended with connection limits (\max\_clients\), checkout timeouts, and performance indexes to support these capabilities.

priv/repo/migrations · high confidence

Added JavaScript integration tests for Postgres.js, Prisma, and Neon Serverless; Added benchmarking scripts for protocol and circuit breaker performance; Added test certificates for ECDSA and EdDSA key types; Added test coverage for client handler validation, proxying, and telemetry; Added test coverage for metrics and tenant controllers; Added test coverage for monitoring plugins; Added test fixtures and helpers for tenant and connection testing; Added tests for LogflareFormatter JSON output structure; Added tests for OpenAPI endpoints and WebSocket proxy password filtering; Added tests for backend prepared statement storage strategies; Added unit tests for the protocol layer; Expanded integration test coverage for proxy reliability and security; Expanded test coverage for core Supavisor components; Initial Elixir test suite and integration scaffolding; New test support modules for assertions, clustering, and integration testing.

This change introduces the foundational dependency manifests for the Supavisor project, establishing the build environment across Elixir, Rust, and JavaScript. The Elixir \mix.exs\ defines the core application stack, including Phoenix 1.7.2, Ecto 3.10, Postgrex (pinned to a specific Git commit), and Rustler 0.36.1 for native extensions, alongside a custom Supabase fork of Poolboy. The Rust \Cargo.toml\ sets up the \pgparser\ crate using Rustler and \pg\_query\ 6.1.0. Additionally, JavaScript integration test dependencies are added, specifying Prisma 5.22.0, the Neon serverless driver, and the \postgres\ client.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 55 → 56 (+0.2)
• Rubric changed (rubric-2026.08.19 → rubric-2026.09.15) — scores are not directly comparable.

• Code Health 95 → 97 (+1.3)
• Architecture 92 → 90 (-2.8)
• Maturity 67 → 67 (+0.0)
• Readiness 41 → 44 (+2.4)
• Security 57 → 54 (-2.8)

• Change coupling: client_handler.ex ↔ client.ex (lib/supavisor/client_handler.ex)
• Change coupling: client_handler.ex ↔ handler_helpers.ex (lib/supavisor/client_handler.ex)
• Change coupling: client_handler.ex ↔ tenant.ex (lib/supavisor/client_handler.ex)
• Coverage not included — suite not readable by the collector
• Dependency hygiene not measured — dependency manifest found but not parsed for hygiene
• Duplicated block (12 lines × 2) (lib/supavisor/client_handler/auth_methods/jit.ex)
• Duplicated block (6 lines × 2) (lib/supavisor/monitoring/prom_ex.ex)
• Duplicated block (8 lines × 2) (lib/supavisor/monitoring/prom_ex.ex)
• Duplicated block (9 lines × 2) (lib/supavisor/monitoring/prom_ex.ex)
• FileTooLong: supavisor/tenants.ex (lib/supavisor/tenants.ex)
• High CVE: [GHSA redacted] (mix.lock)
• High IaC: DS-0029 (Dockerfile)
• Medium CVE: [CVE redacted] (mix.lock)
• Medium CVE: EEF-[CVE redacted] (mix.lock)
• Medium CVE: EEF-[CVE redacted] (mix.lock)
• Medium CVE: EEF-[CVE redacted] (mix.lock)
• Medium CVE: EEF-[CVE redacted] (mix.lock)
• Medium CVE: EEF-[CVE redacted] (mix.lock)
• Medium CVE: EEF-[CVE redacted] (mix.lock)
• Medium CVE: EEF-[CVE redacted] (mix.lock)
• …and 22 more

• Boundary-crossing change coupling: config.exs ↔ application.ex (config/config.exs)
• Boundary-crossing change coupling: config.exs ↔ client_handler.ex (config/config.exs)
• Change coupling: runtime.exs ↔ test.exs (config/runtime.exs)
• Change-coupling hub: client_handler.ex → handler_helpers.ex, client.ex, tenant_supervisor.ex, tenant.ex (lib/supavisor/client_handler.ex)
• Dependency advisory scan runs only on code events
• Documentation: written for insiders (docs/development/docs.md)
• Duplicated block (10 lines × 2) (lib/supavisor_web/controllers/cluster_controller.ex)
• Duplicated block (11 lines × 2) (lib/supavisor/monitoring/prom_ex.ex)
• Duplicated block (11 lines × 2) (lib/supavisor/monitoring/prom_ex.ex)
• Duplicated block (14 lines × 2) (lib/supavisor/client_handler/auth_methods/jit.ex)
• Duplicated block (14 lines × 2) (lib/supavisor_web/controllers/cluster_json.ex)
• Duplicated block (5 lines × 2) (lib/supavisor/monitoring/net_stat.ex)
• Duplicated block (6 lines × 2) (lib/supavisor/monitoring/net_stat.ex)
• Duplicated block (7 lines × 2) (lib/supavisor/monitoring/prom_ex.ex)
• Duplicated block (7 lines × 2) (lib/supavisor/monitoring/prom_ex.ex)
• HackComment (lib/supavisor/monitoring/prom_ex.ex)
• High IaC: DS-0029 (Dockerfile)
• High IaC: DS-0029 (Dockerfile)
• High IaC: WD-DOCKER-0001 (Dockerfile)
• High: security finding (details withheld)
• …and 64 more

• 65 commits — 43 feature/other, 22 fixes

• lib/supavisor — 24 commits
• (repo) — 22 commits
• (root) — 6 commits
• .github/workflows — 6 commits
• docs/monitoring — 3 commits
• test/supavisor — 2 commits
• priv/repo — 1 commit
• test/integration — 1 commit

• fix: Merge pull request #1177 from supabase/fix/forward-port-enotfound-delay
• fix: Merge pull request #1178 from supabase/fix/forward-port-handshake-timeouts
• fix: Merge pull request #1186 from supabase/fix/sec-964-forward-client-ip-jit
• fix: Merge pull request #1196 from supabase/jv/dockerfile-debian-version-fix
• fix: chore: bump req to 0.6.3 (fix decompression bomb DoS)
• fix: fix(monitoring): drop tenant label from state duration metric (#1168)
• fix: fix: add 5s timeout on the handshake state (#1162)
• fix: fix: add project metadata to syn conflict resolution logs
• fix: fix: alias nested PromEx plugin modules in prom_ex_test.exs
• fix: fix: bound client TLS handshake with a timeout (#1153)
• fix: fix: bump DEBIAN_VERSION to a snapshot published for otp 27.3.4.16
• fix: fix: bypass :inet_gethost_native for literal IP addresses (#1160) (#1167)
• fix: fix: correct gzip assertion in MetricsPusher test
• fix: fix: forward client_ip internal pooling
• fix: fix: increase ENOTFOUND response delay to 2.5s (#1159)
• fix: fix: poll node IPv6 address instead of computing it once
• fix: fix: remove dead cache invalidation in SecretChecker.do_update_credentials (#1151)
• fix: fix: remove stale Sync handler (#1176)
• fix: fix: replace dynamic atom interpolation in config_key/2 with static clauses
• fix: fix: replay parse before named statement describe (#1185)
• …and 45 more

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

supabase/supavisor was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.