docs: more docs (#190)

* docs: more docs

* fix: version

VERSION

@@ -1 +1 @@
-0.9.17
+0.9.18

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/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/metrics.md → docs/monitoring/metrics.md

@@ -5,7 +5,23 @@ The metrics feature provides a range of metrics in the Prometheus format. The ma
 - `Supavisor.PromEx.Plugins.Tenant`
 - `Supavisor.Monitoring.Telem`
 
-## Metrics exposed
+## Endpoint
+
+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.
+
+### Filtered per tenant
+
+Metrics endpoints filtered for specific tenants are available at their own endpoints:
+
+```
+/metrics/:external_id
+```
+
+## System, VM & application metrics
 
 The exposed metrics include the following:
 
@@ -17,15 +33,12 @@ The exposed metrics include the following:
   - CPU utilization
   - RAM usage
   - Load average (LA)
+
+## Tenant metrics
+
+Supavisor also tags many metrics with the `tenant` `external_id` so you can drill down to metrics per tenant:
+
 - 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.

docs/orms/prisma.md

@@ -0,0 +1,17 @@
+Connecting to a Postgres database with Prisma is easy.
+
+## PgBouncer Compatability
+
+Supavisor pool modes behave the same way as PgBouncer. You should be able to connect to Supavisor with the exact same connection string as you use for PgBouncer.
+
+## Named Prepared Statements
+
+Prisma will use named prepared statements to query Postgres by default.
+
+To turn off named prepared statements use `pgbouncer=true` in your connection string with Prisma.
+
+The `pgbouncer=true` connection string parameter is compatable with Supavisor.
+
+## Prisma Connection Management
+
+Make sure to review the [Prisma connection management guide](https://www.prisma.io/docs/guides/performance-and-optimization/connection-management).

mkdocs.yaml

@@ -10,10 +10,16 @@ nav:
     - Development: 
       - Installation: 'development/installation.md'
       - Setup: 'development/setup.md'
+      - Docs: 'development/docs.md'
     - Deployment:
       - Deploy with Fly.io: 'deployment/fly.md'
-    - Connecting: 'connecting.md'
-    - Metrics: 'metrics.md'
+    - Connecting:
+      - Overview: 'connecting/overview.md'
+      - Pool Modes: 'connecting/pool_modes.md'
+    - Monitoring: 
+      - Metrics: 'monitoring/metrics.md'
+    - ORMs:
+      - Prisma: 'orms/prisma.md'
 
 theme:
     name: 'material'