Merge pull request #196 from supabase/main

* chore: move docs to mkdocs (#186)
* docs: auto publish docs on main (#189)
* fix: install mkdocs-material (#192)
* docs: more docs (#190)
* feat: add gh workflow (#180)
* fix: handle http request in the native mode (#193)
* feat: handle cancelling requests (#194)
* fix: prevent client <-> db locking (#195)

.github/workflows/docs.yml

@@ -0,0 +1,16 @@
+name: Publish docs
+on:
+  push:
+    branches:
+      - main
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-python@v2
+        with:
+          python-version: 3.x
+      - run: pip install mkdocs
+      - run: pip install mkdocs-material
+      - run: mkdocs gh-deploy --force --clean --verbose

.github/workflows/mirror.yml

@@ -0,0 +1,42 @@
+name: Mirror Image
+
+on:
+  workflow_call:
+    inputs:
+      version:
+        required: true
+        type: string
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Image tag"
+        required: true
+        type: string
+
+jobs:
+  mirror:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+      id-token: write
+    steps:
+      - name: configure aws credentials
+        uses: aws-actions/configure-aws-credentials@v2.2.0
+        with:
+          role-to-assume: ${{ secrets.PROD_AWS_ROLE }}
+          aws-region: us-east-1
+      - uses: docker/login-action@v2
+        with:
+          registry: public.ecr.aws
+      - uses: docker/login-action@v2
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - uses: akhilerm/tag-push-action@v2.1.0
+        with:
+          src: docker.io/supabase/supavisor:${{ inputs.version }}
+          dst: |
+            public.ecr.aws/supabase/supavisor:${{ inputs.version }}
+            ghcr.io/supabase/supavisor:${{ inputs.version }}

.github/workflows/publish_docker.yml

@@ -0,0 +1,75 @@
+name: Release on Dockerhub
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - ".github/workflows/publish_docker.yml"
+      - "VERSION"
+
+jobs:
+  settings:
+    runs-on: ubuntu-latest
+    outputs:
+      docker_version: ${{ steps.settings.outputs.result }}
+      image_tag: supabase/supavisor:${{ steps.settings.outputs.result }}
+    steps:
+      - uses: actions/checkout@v3
+      - id: settings
+        # Remove spaces to get the raw version string
+        run: echo "result=$(sed -r 's/\s+//g' VERSION)" >> $GITHUB_OUTPUT
+
+  build_image:
+    needs: settings
+    strategy:
+      matrix:
+        include:
+          - runner: [self-hosted, X64]
+            arch: amd64
+          - runner: arm-runner
+            arch: arm64
+    runs-on: ${{ matrix.runner }}
+    timeout-minutes: 180
+    outputs:
+      image_digest: ${{ steps.build.outputs.digest }}
+    steps:
+      - run: docker context create builders
+      - uses: docker/setup-buildx-action@v3
+        with:
+          endpoint: builders
+      - uses: docker/login-action@v2
+        with:
+          username: ${{ secrets.DOCKER_USERNAME }}
+          password: ${{ secrets.DOCKER_PASSWORD }}
+      - id: build
+        uses: docker/build-push-action@v5
+        with:
+          push: true
+          tags: ${{ needs.settings.outputs.image_tag }}_${{ matrix.arch }}
+          platforms: linux/${{ matrix.arch }}
+          cache-from: type=gha,scope=${{ github.ref_name }}-${{ matrix.arch }}
+          cache-to: type=gha,mode=max,scope=${{ github.ref_name }}-${{ matrix.arch }}
+
+  merge_manifest:
+    needs: [settings, build_image]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: docker/setup-buildx-action@v3
+      - uses: docker/login-action@v2
+        with:
+          username: ${{ secrets.DOCKER_USERNAME }}
+          password: ${{ secrets.DOCKER_PASSWORD }}
+      - name: Merge multi-arch manifests
+        run: |
+          docker buildx imagetools create -t ${{ needs.settings.outputs.image_tag }} \
+          ${{ needs.settings.outputs.image_tag }}_amd64 \
+          ${{ needs.settings.outputs.image_tag }}_arm64
+
+  publish:
+    needs: [settings, merge_manifest]
+    # Call workflow explicitly because events from actions cannot trigger more actions
+    uses: ./.github/workflows/mirror.yml
+    with:
+      version: ${{ needs.settings.outputs.docker_version }}
+    secrets: inherit

VERSION

@@ -1 +1 @@
-0.9.14
+0.9.23

docs/connecting/overview.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
+```

docs/connecting/pool_modes.md

@@ -0,0 +1,21 @@
+Configure the `mode_type` on the `user` to set how Supavisor connection pools will behave.
+
+The `mode_type` can be one of:
+
+- `transaction`
+- `session`
+- `native`
+
+## Transaction Mode
+
+`transaction` mode assigns a connection to a client for the duration of a single transaction.
+
+## Session Mode
+
+`session` mode assigns a connection to a client for the duration of the client connection.
+
+## Native Mode
+
+`native` mode proxies a client to the database as if it was directly connected.
+
+This mode is typically needed to run migrations.

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

docs/development/docs.md

@@ -0,0 +1,19 @@
+Documentation is managed with [mkdocs](https://www.mkdocs.org/).
+
+## Adding documentation
+
+Edit the documentation in:
+
+`/docs`
+
+Edit the documentation nav in:
+
+`/mkdocs.yaml`
+
+Build and serve the documentation locally with:
+
+`mkdocs serve`
+
+Production documentation is built on merge into `main` with the Github Action:
+
+`/.github/workflows/docs.yml`

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
+```

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)

docs/index.md

@@ -0,0 +1,21 @@
+# `supabase/supavisor`
+
+<p>
+<a href=""><img src="https://img.shields.io/badge/postgresql-12+-blue.svg" alt="PostgreSQL version" height="18"></a>
+<a href="https://github.com/supabase/supavisor/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg" alt="License" height="18"></a>
+
+</p>
+
+---
+
+**Documentation**: <a href="https://supabase.github.io/supavisor" target="_blank">https://supabase.github.io/supavisor</a>
+
+**Source Code**: <a href="https://github.com/supabase/supavisor" target="_blank">https://github.com/supabase/supavisor</a>
+
+---
+
+## 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.