{"id":13513828,"url":"https://github.com/supabase/supavisor","last_synced_at":"2025-05-14T09:10:47.943Z","repository":{"id":151862145,"uuid":"588226575","full_name":"supabase/supavisor","owner":"supabase","description":"A cloud-native, multi-tenant Postgres connection pooler.","archived":false,"fork":false,"pushed_at":"2025-05-11T11:27:35.000Z","size":4193,"stargazers_count":1908,"open_issues_count":55,"forks_count":67,"subscribers_count":36,"default_branch":"main","last_synced_at":"2025-05-11T12:27:55.330Z","etag":null,"topics":["elixir","erlang","postgresql"],"latest_commit_sha":null,"homepage":"https://supabase.github.io/supavisor/","language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/supabase.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["supabase"],"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"custom":null}},"created_at":"2023-01-12T16:16:57.000Z","updated_at":"2025-05-08T11:48:14.000Z","dependencies_parsed_at":"2025-05-04T00:25:37.969Z","dependency_job_id":"e6b74bab-b75e-4f33-99e7-641edfdc3c34","html_url":"https://github.com/supabase/supavisor","commit_stats":{"total_commits":241,"total_committers":14,"mean_commits":"17.214285714285715","dds":0.2655601659751037,"last_synced_commit":"9f56b879e7421a6245846d3b9a61dc81756d6afd"},"previous_names":[],"tags_count":55,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/supabase%2Fsupavisor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/supabase%2Fsupavisor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/supabase%2Fsupavisor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/supabase%2Fsupavisor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/supabase","download_url":"https://codeload.github.com/supabase/supavisor/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253807871,"owners_count":21967433,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["elixir","erlang","postgresql"],"created_at":"2024-08-01T05:00:38.406Z","updated_at":"2025-05-14T09:10:47.924Z","avatar_url":"https://github.com/supabase.png","language":"Elixir","readme":"![Supavisor](/docs/images/supavisor-banner.png)\n\n# Supavisor - Postgres connection pooler\n\n- [Overview](#overview)\n- [Motivation](#motivation)\n- [Architecture](#architecture)\n- [Docs](#docs)\n- [Features](#features)\n- [Future work](#future-work)\n- [Acknowledgements](#acknowledgements)\n- [Benchmarks](#benchmarks)\n- [Inspiration](#inspiration)\n\n## Overview\n\nSupavisor is a scalable, cloud-native Postgres connection pooler. A Supavisor\ncluster is capable of proxying millions of Postgres end-client connections into\na stateful pool of native Postgres database connections.\n\nFor database managers, Supavisor simplifies the task of managing Postgres\nclusters by providing easy configuration of highly available Postgres clusters\n([todo](#future-work)).\n\n## Motivation\n\nWe have several goals with Supavisor:\n\n- **Zero-downtime scaling**: we want to scale Postgres server compute with\n  zero-downtime. To do this, we need an external Pooler that can buffer and\n  re-route requests while the resizing operation is in progress.\n- **Handling modern connection demands**: We need a Pooler that can absorb\n  millions of connections. We often see developers connecting to Postgres from\n  Serverless environments, and so we also need something that works with both TCP\n  and HTTP protocols.\n- **Efficiency**: Our customers pay for database processing power, and our goal\n  is to maximize their database capacity. While PgBouncer is resource-efficient,\n  it still consumes some resources on the database instance. By moving connection\n  pooling to a dedicated cluster adjacent to tenant databases, we can free up\n  additional resources to better serve customer queries.\n\n## Architecture\n\nSupavisor was designed to work in a cloud computing environment as a highly\navailable cluster of nodes. Tenant configuration is stored in a highly available\nPostgres database. Configuration is loaded from the Supavisor database when a\ntenant connection pool is initiated.\n\nConnection pools are dynamic. When a tenant client connects to the Supavisor\ncluster the tenant pool is started and all connections to the tenant database\nare established. The process ID of the new tenant pool is then distributed to\nall nodes of the cluster and stored in an in-memory key-value store. Subsequent\ntenant client connections live on the inbound node but connection data is\nproxied from the pool node to the client connection node as needed.\n\nBecause the count of Postgres connections is constrained only one tenant\nconnection pool should be alive in a Supavisor cluster. In the case of two\nsimultaneous client connections starting a pool, as the pool process IDs are\ndistributed across the cluster, eventually one of those pools is gracefully\nshutdown.\n\nThe dynamic nature of tenant database connection pools enables high availability\nin the event of node outages. Pool processes are monitored by each node. If a\nnode goes down that process ID is removed from the cluster. Tenant clients will\nthen start a new pool automatically as they reconnect to the cluster.\n\nThis design enables blue-green or rolling deployments as upgrades require. A\nsingle VPC / multiple availability zone topologies is possible and can provide\nfor greater redundancy when load balancing queries across read replicas are\nsupported ([todo](#future-work)).\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"https://user-images.githubusercontent.com/8291514/230757493-669bf563-084c-4705-b22e-38d398f4ec05.svg#gh-light-mode-only\"\u003e\n\u003cimg src=\"https://user-images.githubusercontent.com/8291514/230757489-2d2fb07a-1fcb-423b-939e-b0c04e2d4d9b.svg#gh-dark-mode-only\"\u003e\n\u003c/p\u003e\n\n## Docs\n\n- [Installation and usage](https://supabase.github.io/supavisor/development/installation/)\n- [Metrics](https://supabase.github.io/supavisor/monitoring/metrics/)\n\n## Features\n\n- Fast\n  - Within 90% throughput as compared to `PgBouncer` running `pgbench` locally\n- Scalable\n  - 1 million Postgres connections on a cluster\n  - 250_000 idle connections on a single 16 core node with 64GB of ram\n- Multi-tenant\n  - Connect to multiple different Postgres instances/clusters\n- Single-tenant\n  - Easy drop-in replacement for `PgBouncer`\n- Pool mode support per tenant\n  - Transaction\n- Cloud-native\n  - Cluster-able\n  - Resilient during cluster resizing\n  - Supports rolling and blue/green deployment strategies\n  - NOT run in a serverless environment\n  - NOT dependant on Kubernetes\n- Observable\n  - Easily understand throughput by tenant, tenant database or individual\n    connection\n  - Prometheus `/metrics` endpoint\n- Manageable\n  - OpenAPI spec at `/api/openapi`\n  - SwaggerUI at `/swaggerui`\n- Highly available\n  - When deployed as a Supavisor cluster and a node dies connection pools should\n    be quickly spun up or already available on other nodes when clients reconnect\n- Connection buffering\n  - Brief connection buffering for transparent database restarts or failovers\n\n## Future Work\n\n- Load balancing\n  - Queries can be load balanced across read-replicas\n  - Load balancing is independent of Postgres high-availability management (see\n    below)\n- Query caching\n  - Query results are optionally cached in the pool cluster and returned before\n    hitting the tenant database\n- Session pooling\n  - Like `PgBouncer`\n- Multi-protocol Postgres query interface\n  - Postgres binary\n  - HTTPS\n  - Websocket\n- Postgres high-availability management\n  - Primary database election on primary failure\n  - Health checks\n  - Push button read-replica configuration\n- Config as code\n  - Not only for the Supavisor cluster but tenant databases and tenant database\n    clusters as well\n  - Pulumi / Terraform support\n\n## Benchmarks\n\n### Local Benchmarks\n\n- Running `pgbench` on `PgBouncer` (transaction mode/pool size 60)\n\n```\nPGPASSWORD=postgres pgbench -M extended --transactions 100 --jobs 10 --client 100 -h localhost -p 6452 -U postgres postgres\npgbench (15.2, server 14.6 (Debian 14.6-1.pgdg110+1))\nstarting vacuum...end.\ntransaction type: \u003cbuiltin: TPC-B (sort of)\u003e\nscaling factor: 1\nquery mode: extended\nnumber of clients: 100\nnumber of threads: 10\nmaximum number of tries: 1\nnumber of transactions per client: 100\nnumber of transactions actually processed: 10000/10000\nnumber of failed transactions: 0 (0.000%)\nlatency average = 510.310 ms\ninitial connection time = 31.388 ms\ntps = 195.959361 (without initial connection time)\n```\n\n- Running `pgbench` on `Supavisor` (pool size 60, no logs)\n\n```\nPGPASSWORD=postgres pgbench -M extended --transactions 100 --jobs 10 --client 100 -h localhost -p 7654 -U postgres.localhost postgres\npgbench (15.2, server 14.6 (Debian 14.6-1.pgdg110+1))\nstarting vacuum...end.\ntransaction type: \u003cbuiltin: TPC-B (sort of)\u003e\nscaling factor: 1\nquery mode: extended\nnumber of clients: 100\nnumber of threads: 10\nmaximum number of tries: 1\nnumber of transactions per client: 100\nnumber of transactions actually processed: 10000/10000\nnumber of failed transactions: 0 (0.000%)\nlatency average = 528.463 ms\ninitial connection time = 178.591 ms\ntps = 189.228103 (without initial connection time)\n```\n\n### Load Test\n\n![Supavisor load test virtual users chart](./docs/images/load-test-vus.png)\n\n![Supavisor load test qps chart](./docs/images/load-test-qps.png)\n\n- Supavisor two node cluster\n  - 64vCPU / 246RAM\n  - Ubuntu 22.04.2 aarch64\n- 1 003 200 concurrent client connection\n- 20 000+ QPS\n- 400 tenant Postgres connection\n- `SELECT * FROM (VALUES (1, 'one'), (2, 'two'), (3, 'three')) AS t (num, letter);`\n- ~50% CPU utilization (pool owner node)\n- 7.8G RAM usage\n\n## Acknowledgements\n\n[José Valim](https://github.com/josevalim) and the [Dashbit](https://dashbit.co/) team were incredibly helpful in informing\nthe design decisions for Supavisor.\n\n## Inspiration\n\n- [PgBouncer](https://www.pgbouncer.org/)\n- [stolon](https://github.com/sorintlab/stolon)\n- [pgcat](https://github.com/levkk/pgcat)\n- [odyssey](https://github.com/yandex/odyssey)\n- [crunchy-proxy](https://github.com/CrunchyData/crunchy-proxy)\n- [pgpool](https://www.pgpool.net/mediawiki/index.php/Main_Page)\n- [pgagroal](https://github.com/agroal/pgagroal)\n\n## Commercial Inspiration\n\n- [proxysql.com](https://proxysql.com/)\n- [Amazon RDS Proxy](https://aws.amazon.com/rds/proxy/)\n- [Google Cloud SQL Proxy](https://github.com/GoogleCloudPlatform/cloud-sql-proxy)\n","funding_links":["https://github.com/sponsors/supabase"],"categories":["Elixir","elixir"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsupabase%2Fsupavisor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsupabase%2Fsupavisor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsupabase%2Fsupavisor/lists"}