supavisor

![Supavisor](/docs/images/supavisor-banner.png)

# Supavisor - Postgres connection pooler

[![Coverage Status](https://coveralls.io/repos/github/supabase/supavisor/badge.svg?branch=main)](https://coveralls.io/github/supabase/supavisor?branch=main)

- [Overview](#overview)
- [Motivation](#motivation)
- [Architecture](#architecture)
- [Docs](#docs)
- [Features](#features)
- [Future work](#future-work)
- [Acknowledgements](#acknowledgements)
- [Benchmarks](#benchmarks)
- [Inspiration](#inspiration)

## Overview

Supavisor is a scalable, cloud-native Postgres connection pooler. A Supavisor
cluster is capable of proxying millions of Postgres end-client connections into
a stateful pool of native Postgres database connections.

For database managers, Supavisor simplifies the task of managing Postgres
clusters by providing easy configuration of highly available Postgres clusters
([todo](#future-work)).

## Motivation

We have several goals with Supavisor:

- **Zero-downtime scaling**: we want to scale Postgres server compute with
  zero-downtime. To do this, we need an external Pooler that can buffer and
  re-route requests while the resizing operation is in progress.
- **Handling modern connection demands**: We need a Pooler that can absorb
  millions of connections. We often see developers connecting to Postgres from
  Serverless environments, and so we also need something that works with both TCP
  and HTTP protocols.
- **Efficiency**: Our customers pay for database processing power, and our goal
  is to maximize their database capacity. While PgBouncer is resource-efficient,
  it still consumes some resources on the database instance. By moving connection
  pooling to a dedicated cluster adjacent to tenant databases, we can free up
  additional resources to better serve customer queries.

## Architecture

Supavisor was designed to work in a cloud computing environment as a highly
available cluster of nodes. Tenant configuration is stored in a highly available
Postgres database. Configuration is loaded from the Supavisor database when a
tenant connection pool is initiated.

Connection pools are dynamic. When a tenant client connects to the Supavisor
cluster the tenant pool is started and all connections to the tenant database
are established. The process ID of the new tenant pool is then distributed to
all nodes of the cluster and stored in an in-memory key-value store. Subsequent
tenant client connections live on the inbound node but connection data is
proxied from the pool node to the client connection node as needed.

Because the count of Postgres connections is constrained only one tenant
connection pool should be alive in a Supavisor cluster. In the case of two
simultaneous client connections starting a pool, as the pool process IDs are
distributed across the cluster, eventually one of those pools is gracefully
shutdown.

The dynamic nature of tenant database connection pools enables high availability
in the event of node outages. Pool processes