supabase

Coming soon

This plugin is not released yet. The agent side lives on the unmerged supabase-plugin branch of the plugins package. The server rules and the dashboard card are on the matching frontend branch.

The supabase plugin watches Supabase Cloud projects. Per project it reports whether the project is paused, the health of each Supabase service, and disk, memory, connections and database size. It runs on any agent, because it only makes HTTPS calls.

Set it up

Each project can use one or both of two sources. Each source has its own credential.

Source	Credential	Gives
Management API, api.supabase.com/v1	A personal access token. It covers every project in the account that made it.	Project status, the only place "paused" shows up. Region and Postgres version. Health for each service.
The project's metrics endpoint, https://<PROJECT_REF>.supabase.co/customer/v1/privileged/metrics	The project's secret API key, sent as basic auth with user service_role.	Disk, memory, connections and database size.

Either one alone works. A project with neither reports an error.

1. Find each project's ref. It is the subdomain in https://<PROJECT_REF>.supabase.co.
2. Create a personal access token in each Supabase account that owns a project, and copy each project's secret key if you want the figures.
3. Add a supabase block to the agent config and add supabase to the plugins array.

{
  "plugins": ["supabase"],
  "supabase": {
    "refreshInterval": 60000,
    "accessToken": "sbp_<DEFAULT_ACCOUNT_TOKEN>",
    "diskWarnPct": 80,
    "diskCritPct": 90,
    "connWarnPct": 85,
    "projects": [
      { "ref": "<PROJECT_REF>", "name": "portal" },
      {
        "ref": "<OTHER_PROJECT_REF>",
        "name": "calendar",
        "accessToken": "sbp_<OTHER_ACCOUNT_TOKEN>",
        "serviceKey": "sb_secret_<SECRET_KEY>"
      }
    ]
  }
}

The top-level accessToken is the default. A project in a different Supabase account needs its own accessToken, since one token only covers its own account.

Option	Default	What it does
projects	required	List of projects. Each has ref, and optionally name, accessToken and serviceKey. Entries without ref are skipped.
projects[].name	project name from the API, else ref	Card title.
accessToken	none	Default personal access token.
services	auth, db, pooler, realtime, rest, storage	Services asked of the health endpoint. Drop one a project does not use.
diskWarnPct	80	Disk use, in percent, that warns.
diskCritPct	90	Disk use, in percent, that is an error.
connWarnPct	85	Connections in use, as a percent of max_connections, that warns.
requestTimeout	10000	Milliseconds per HTTP request.
refreshInterval	60000	Milliseconds between polls.

What it reports

One report per project per interval, keyed supabase-<ref>. Projects are polled one after another, and the first poll runs on start.

• ref, name and reachable.
• projectStatus, such as ACTIVE_HEALTHY or INACTIVE, plus region and pgVersion.
• services[], each with name, healthy, status and error.
• metrics, from the Prometheus endpoint. diskPct, diskUsedBytes and diskTotalBytes read the /data volume, or / when there is no /data. Also memPct, load1, connections, maxConnections and dbSizeBytes. A series that is missing reports null, not 0.
• errors[], one entry per configured source that failed while another answered.
• diskWarnPct, diskCritPct and connWarnPct, the thresholds from the agent config. The server judges with these.

If every source fails, the report is { reachable: false, error }.

When it alerts

The server checks these in order and stops at the first match.

Condition	Severity	Reason text
error set, or reachable is false	error	<name>: <error>
projectStatus is INACTIVE	error	<name>: project is paused
projectStatus is a transient state	warning	<name>: project <status>
projectStatus is any other value besides ACTIVE_HEALTHY	error	<name>: project <status>
The db service is unhealthy and not COMING_UP	error	<name>: database unhealthy, <error>
diskPct at or above diskCritPct	error	<name>: disk <n>% full
Any service unhealthy	warning	<name>: <services> unhealthy
diskPct at or above diskWarnPct	warning	<name>: disk <n>% full
Connections at or above connWarnPct of the maximum	warning	<name>: <n> of <max> connections in use
errors[] is not empty	warning	<name>: <first error>

The transient states are COMING_UP, RESTORING, UPGRADING, RESTARTING, RESIZING, PAUSING, GOING_DOWN and UNKNOWN.

A new problem does not notify on the first bad report. The server waits for a second consecutive bad report. A report that comes back online resolves the alert.

On the dashboard

One card per project, titled with the project name and labelled Supabase · <region>. Each reading shows only when it was measured.

Reading	Source	Warn	Crit
PROJECT	projectStatus. ACTIVE_HEALTHY reads ACTIVE, INACTIVE reads PAUSED	any other state	PAUSED
DISK	metrics.diskPct	diskWarnPct	diskCritPct
CONNS	connections / maxConnections	connWarnPct	none
DB SIZE	metrics.dbSizeBytes	none	none
MEM	metrics.memPct	none	none
POSTGRES	pgVersion, major and minor	none	none

Below that, one row per service. Healthy is green, COMING_UP is amber, anything else is red. When the report is unreachable, the card shows only API UNREACHABLE. The card links to the project in the Supabase dashboard.

Gotchas

• The branch's commit message says the health and project response fields, and the metric series names, were written from memory. They have not been run against a live project.
• The dashboard and the server do not color everything the same way. An unhealthy service other than db is red on the card but only a warning on the server. A project state outside the transient list is amber on the card but an error on the server.
• load1, diskUsedBytes and diskTotalBytes are reported but not shown. memPct is shown but never judged.
• A partial report, where one source failed, does not show which source failed on the card. The reason text carries the first error.