diff --git a/VERSION b/VERSION index 6d44d227..5d11b147 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.9.14 +0.9.15 diff --git a/docs/connecting.md b/docs/connecting.md new file mode 100644 index 00000000..dacb21ca --- /dev/null +++ b/docs/connecting.md @@ -0,0 +1,37 @@ +To connect to a tenant database Supavisor needs to look up the tenant with an `external_id`. + +You can connect to Supavisor just like you connect to Postgres except we need to include the `external_id` in the connection string. + +Supavisor parses the `external_id` from a connection in one three ways: + +- The username +- Server name identification +- `options` parameters + +> 📘 Examples +> +> In the following examples our `external_id` is `dev_tenant`. + +## Username + +Include the `external_id` in the username. The `external_id` is found after the `.` in the username: + +``` +psql postgresql://postgres.dev_tenant:postgres@localhost:6543/postgres +``` + +## Server name indication + +The subdomain of the SNI from the TLS handshake: + +``` +dev_tenant.supabase.co +``` + +## Options parameters + +Include the `external_id` as the `reference` in the `options` parameters: + +``` +psql postgresql://postgres:postgres@localhost:6543/postgres&options=reference%3Ddev_tenant +``` diff --git a/docs/deployment/fly.md b/docs/deployment/fly.md new file mode 100644 index 00000000..668c4b04 --- /dev/null +++ b/docs/deployment/fly.md @@ -0,0 +1,41 @@ +The `toml.yaml` file should be in the `deploy/fly` directory of Supavisor. + +Type the following command in your terminal: + +```bash +fly launch +``` + +Choose a name for your app when prompted, then answer "yes" to the following question: + +```bash +Would you like to copy its configuration to the new app? (y/N) +``` + +Next, select an organization and choose a region. You don't need to deploy the app yet. + +Since the pooler uses an additional port (7654) for the PostgreSQL protocol, you need to reserve an IP address: + +```bash +fly ips allocate-v4 +``` + +Set your app's secrets by running the following command: + +```bash +fly secrets set DATABASE_URL="ecto://postgres:postgres@localhost:6432/postgres" \ +VAULT_ENC_KEY="some_vault_secret" \ +API_JWT_SECRET="some_api_secret" \ +METRICS_JWT_SECRET="some_metrics_secret" \ +SECRET_KEY_BASE="some_kb_secret" +``` + +Replace the example values with your actual secrets. + +Finally, deploy your app using the following command: + +```bash +fly deploy +``` + +This will deploy your app on Fly.io diff --git a/docs/development/installation.md b/docs/development/installation.md new file mode 100644 index 00000000..0c773a1b --- /dev/null +++ b/docs/development/installation.md @@ -0,0 +1,13 @@ +Before starting, set up the database where Supavisor will store tenants' data. The following command will pull a Docker image with PostgreSQL 14 and run it on port 6432: + +``` +docker-compose -f ./docker-compose.db.yml up +``` + +> `Supavisor` stores tables in the `supavisor` schema. The schema should be automatically created by the `dev/postgres/00-setup.sql` file. If you encounter issues with migrations, ensure that this schema exists. + +Next, get dependencies and apply migrations: + +``` +mix deps.get && mix ecto.migrate --prefix _supavisor --log-migrator-sql +``` diff --git a/docs/development/setup.md b/docs/development/setup.md new file mode 100644 index 00000000..b696f229 --- /dev/null +++ b/docs/development/setup.md @@ -0,0 +1,60 @@ +Launch the Supavisor application: + +``` +make dev +``` + +You need to add tenants to the database. For example, the following request will add the `dev_tenant` with credentials to the database set up earlier. + +## Add/update tenant + +```bash +curl -X PUT \ + 'http://localhost:4000/api/tenants/dev_tenant' \ + --header 'Accept: application/json' \ + --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJvbGUiOiJhbm9uIiwiaWF0IjoxNjQ1MTkyODI0LCJleHAiOjE5NjA3Njg4MjR9.M9jrxyvPLkUxWgOYSf5dNdJ8v_eRrq810ShFRT8N-6M' \ + --header 'Content-Type: application/json' \ + --data-raw '{ + "tenant": { + "db_host": "localhost", + "db_port": 6432, + "db_database": "postgres", + "ip_version": "auto", // "auto" | v4 | v6 + "require_user": true, // true | false + "upstream_ssl": true, // true | false, + "enforce_ssl": false, // true | false, + "upstream_verify": "peer", // "none" | "peer" + "upstream_tls_ca": "-----BEGIN CERTIFICATE-----\nblalblalblablalblalblaba\n-----END CERTIFICATE-----\n", // "" + "users": [ + { + "db_user": "postgres", + "db_password": "postgres", + "pool_size": 20, + "mode_type": "transaction", + "pool_checkout_timeout": 100 + } + ] + } +}' +``` + +Now, it's possible to connect through the proxy. By default, Supavisor uses port `6543` for transaction mode and `5432` for session mode: + +``` +psql postgresql://postgres.dev_tenant:postgres@localhost:6543/postgres +``` + +> :warning: The tenant's ID is incorporated into the username and separated by the `.` symbol. For instance, for the username `some_username` belonging to the tenant `some_tenant`, the modified username will be `some_username.some_tenant`. This approach enables the system to support multi-tenancy on a single IP address. + +## Delete tenant + +To delete a tenant, send the following request: + +```bash +curl -X DELETE \ + 'http://localhost:4000/api/tenants/dev_tenant' \ + --header 'Accept: application/json' \ + --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJvbGUiOiJhbm9uIiwiaWF0IjoxNjQ1MTkyODI0LCJleHAiOjE5NjA3Njg4MjR9.M9jrxyvPLkUxWgOYSf5dNdJ8v_eRrq810ShFRT8N-6M' +``` + +API documentation can be found at [http://localhost:4000/swaggerui](http://localhost:4000/swaggerui) diff --git a/docs/images/favicon.ico b/docs/images/favicon.ico new file mode 100644 index 00000000..d3fca2ac Binary files /dev/null and b/docs/images/favicon.ico differ diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..4543b650 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,21 @@ +# `supabase/supavisor` + +

+PostgreSQL version +License + +

+ +--- + +**Documentation**: https://supabase.github.io/supavisor + +**Source Code**: https://github.com/supabase/supavisor + +--- + +## Overview + +Supavisor is an open source scalable connection pooler for Postgres. + +Review the [readme](https://github.com/supabase/supavisor/blob/main/README.md) for a detailed overview. diff --git a/docs/metrics.md b/docs/metrics.md new file mode 100644 index 00000000..1e3c2caf --- /dev/null +++ b/docs/metrics.md @@ -0,0 +1,31 @@ +The metrics feature provides a range of metrics in the Prometheus format. The main modules involved in this implementation are: + +- `Supavisor.Monitoring.PromEx` +- `Supavisor.PromEx.Plugins.OsMon` +- `Supavisor.PromEx.Plugins.Tenant` +- `Supavisor.Monitoring.Telem` + +## Metrics exposed + +The exposed metrics include the following: + +- Application +- BEAM +- Phoenix +- Ecto +- System monitoring metrics: + - CPU utilization + - RAM usage + - Load average (LA) +- Pool checkout queue time +- Number of connected clients +- Query duration and query counts +- Network usage for client sockets and database sockets + +## Usage + +To use the metrics feature, send an HTTP request to the `/metrics` endpoint. The endpoint is secured using Bearer authentication, which requires a JSON Web Token (JWT) generated using the `METRICS_JWT_SECRET` environment variable. Make sure to set this environment variable with a secure secret key. + +When a node receives a request for metrics, it polls all nodes in the cluster, accumulates their metrics, and appends service tags such as region and host. To generate a valid JWT, use a library or tool that supports JWT creation with the HS256 algorithm and the `METRICS_JWT_SECRET` as the secret key. + +Remember to keep the `METRICS_JWT_SECRET` secure and only share it with authorized personnel who require access to the metrics endpoint. diff --git a/mkdocs.yaml b/mkdocs.yaml new file mode 100644 index 00000000..a2d96117 --- /dev/null +++ b/mkdocs.yaml @@ -0,0 +1,43 @@ +site_name: supavisor +site_url: https://supabase.github.io/supavisor +site_description: A cloud native multi-tenant connection pooler for Postgres + +repo_name: supabase/supavisor +repo_url: https://github.com/supabase/supavisor + +nav: + - Welcome: 'index.md' + - Development: + - Installation: 'development/installation.md' + - Setup: 'development/setup.md' + - Deployment: + - Deploy with Fly.io: 'deployment/fly.md' + - Connecting: 'connecting.md' + - Metrics: 'metrics.md' + +theme: + name: 'material' + favicon: 'images/favicon.ico' + logo: 'images/favicon.ico' + homepage: https://supabase.github.io/supavisor + features: + - navigation.expand + palette: + primary: black + accent: light green + +markdown_extensions: + - pymdownx.highlight: + linenums: true + guess_lang: false + use_pygments: true + pygments_style: default + - pymdownx.superfences + - pymdownx.tabbed: + alternate_style: true + - pymdownx.snippets + - pymdownx.tasklist + - admonition + - pymdownx.emoji: + emoji_index: !!python/name:materialx.emoji.twemoji + emoji_generator: !!python/name:materialx.emoji.to_svg \ No newline at end of file