repository·main·Indexed 24 days ago
https://github.com/supabase/supavisorSupavisor is a scalable, cloud-native Postgres connection pooler designed to proxy millions of end-client connections into a stateful pool of native Postgres database connections. It supports TCP and HTTP protocols, multi-tenancy, and serves as a drop-in replacement for PgBouncer. Key features include Transaction, Session, and Native pool modes, Prometheus observability, and a Management API with OpenAPI/SwaggerUI support.
PgBouncer.Supavisor provides the following capabilities:
Transaction mode per tenant./metrics endpoint to monitor throughput by tenant, tenant database, or individual connection./api/openapi and SwaggerUI at /swaggerui.By default, Prisma uses named prepared statements, which can conflict with transaction-mode pooling. To allow Prisma to use named prepared statements in transaction mode without using the pgbouncer=true flag, you must enable the named_prepared_statements feature flag in Supavisor.
You can enable this in two ways:
NAMED_PREPARED_STATEMENTS_ENABLED environment variable.feature_flags configuration.Enabling this feature avoids the performance penalty associated with pgbouncer=true when querying tables with extension types.
You can control how Supavisor manages connections by setting the mode_type on a user. The mode_type determines the lifecycle of the connection assigned to a client.
mode_type can be one of:
- `transaction`
- `session`
- `native`Supavisor supports prepared statements based on the connection mode:
named_prepared_statements feature flag is enabled.You can enable this feature flag in two ways:
NAMED_PREPARED_STATEMENTS_ENABLED environment variable.feature_flags setting on the tenant.session mode, Supavisor assigns a database connection to a client for the entire duration of that client's connection. This is useful when your application requires state to persist across multiple queries within a single connection session.native mode, Supavisor proxies a client to the database as if it were directly connected. This mode is typically required for running database migrations or other operations that require direct, unmediated access to the database session.When a client connection is established, Supavisor verifies credentials using one of two methods depending on the configuration of the tenant record:
Tenant User Record: If no auth_query is defined on the tenant record, Supavisor looks up credentials from user records associated with that tenant. It verifies these against the credentials provided in the client connection string. For this method to work, there must be one or more user records for the tenant where is_manager is false.
Authentication Query: If the user in the client connection is not found in the tenant's user records, Supavisor falls back to using the user where is_manager is true and executes the auth_query defined on the tenant record. This query is used to fetch matching credentials directly from the tenant's database.
tenant record stored in its metadata database to manage configuration for specific groups of connections. A tenant is identified by an external_id which is discovered during the incoming client connection process. Additionally, the sni_hostname field can be used to match an incoming connection to a specific tenant record.When deployed as a cluster for high availability, Supavisor uses an 'owner node' model for tenant pools:
Why this model is used:
default_pool_size set on the tenant, avoiding synchronization delays between nodes that could lead to exceeding database limits.Supavisor operates as a highly available cluster of nodes in a cloud environment.