PlanetScale
Connect a PlanetScale organization to Maple with one authorization. Maple collects every branch's CPU, memory, storage, connections, and replica lag, registers webhooks, and adds your databases to the service map.
You connect a PlanetScale organization once, with an OAuth authorization. It covers everything Maple reads: the database inventory, query insights, branch metrics from PlanetScale’s metrics API, and the webhooks Maple registers for you. Maple reads every branch’s metrics every 5 minutes, and picks up new branches and databases on its own.
Prerequisites
- Permission in the PlanetScale organization to authorize an OAuth application and manage database webhooks.
1. Authorize Maple
In Maple, open Sources, click Connect source and pick PlanetScale. Click Continue with PlanetScale. A popup takes you to PlanetScale to authorize Maple’s OAuth application. The step moves on by itself once you approve. You can revoke access from PlanetScale at any time.
- If the authorization covers one organization, Maple binds it automatically.
- If it covers several, pick the one to collect from. One source watches one organization.
The OAuth application needs read_databases for the database inventory, the service map, and query insights. If it is missing, the setup shows Reconnect with read_databases.
2. Pick the branches
Under Which branches?, keep Every branch, or set Only these branches (optional) and Exclude branches (optional). Both take glob patterns, where * matches any run of characters and ? matches exactly one (for example pr-*, preview-*). Click Start collecting.
To change the organization or the branch filters later, open the source and choose Edit data.
Maple then shows a Checking the connection list: access to the organization, the databases and branches it found, and the first branch metrics. Nothing else is asked of you. Within 10 minutes Maple reads each branch’s last minutes from the metrics API and the last row completes.
Maple reads every ready branch that passes your branch filters. For Postgres branches that is pod CPU and memory, disk usage and free space, PgBouncer connections, WAL size, and replica lag. For Vitess branches it is connections and router (vtgate) CPU and memory per zone; the metrics API serves no pod or disk metrics for Vitess.
Connections set up with a service token before the metrics API existed keep scraping PlanetScale’s Prometheus endpoints with it, and the card shows Streaming branch metrics from your organization as before.
3. Webhooks
Maple registers a webhook on every database in the organization, including databases you create later, within a few minutes. Out-of-memory restarts, storage thresholds, and anomalies open triage issues, and deploy requests and branch changes appear on the charts as they happen. The Webhooks row shows how many databases have one.
Registering webhooks needs the write_databases access. If you connected before Maple asked for it, the row reads Needs attention; click Reconnect. Maple only creates, re-enables, and deletes its own webhook and leaves your other webhooks alone. PlanetScale allows 5 webhooks per database, so a database that already has 5 shows the error on the row. Disconnecting removes Maple’s webhooks.
Verify
- Checking the connection shows Branch metrics arriving, and the source page shows a health row reading Streaming branch metrics from your organization. The page polls while it waits, so you do not need to reload.
- Open Infrastructure → PlanetScale to see your databases and branches.
- In the metrics explorer, search for
planetscale_to see branch series.
What you get
Each branch series carries planetscale_organization_name, planetscale_database_name, planetscale_branch_name, and planetscale_database_branch_id, which keys every series to a branch. Series read from the metrics API also carry planetscale_source="api". The main metrics:
| Metric | What it tells you |
|---|---|
planetscale_pods_cpu_util_percentages | (Postgres) CPU of the pods backing the branch. |
planetscale_pods_mem_util_percentages | (Postgres) Memory of the pods backing the branch. |
planetscale_volume_available_bytes | (Postgres) Free disk space, with planetscale_. |
planetscale_postgres_wal_size_bytes | (Postgres) WAL size. An early warning for replication and disk usage. |
planetscale_postgres_replica_lag_seconds | (Postgres) Replica lag, one series per replica. |
planetscale_api_connections | Connections (PgBouncer on Postgres, the router on Vitess). |
planetscale_vtgate_cpu_util_percentages | (Vitess) Router CPU per availability zone. |
Connections that scrape with a service token get PlanetScale’s full Prometheus metric set instead.
Group dashboards and alert rules by planetscale_database_branch_id. For example, alert when WAL size passes a threshold or active connections approach your pool limit.
Troubleshooting
- The metrics row shows an error. It reads Metrics collection degraded with what the last poll hit. A failing branch costs only its own window; the others keep arriving.
- Authorization shows as revoked. Click Reconnect to authorize again.
- Metrics stopped arriving. The row reads Metrics collection stalled. Check the error on the health row.
- The status stays on Waiting for first metrics. After 30 minutes without metrics the check stops on its own. Click Check again once you have fixed the cause.
- A new branch has no metrics yet. Maple reads the branch list from the hourly inventory, so a new branch starts reporting within the hour.
- Branch filters did not apply. Changes take effect on the next poll.
Next steps
- Service map: PlanetScale databases linked to the services that query them.
- Alert rules: alert on branch metrics.