{"id":"3c53bd71-d77f-4070-b681-df16b0d5cba6","task":"Run ad-hoc SQL and manage migrations against a Supabase project through the Management API query endpoint","domain":"supabase.com","steps":["POST /v1/projects/{ref}/database/query with {\"query\":\"select * from pg_stat_activity limit 1;\", \"read_only\": true}. The 'query' field is required (min length 1); 'parameters' (array) and 'read_only' (boolean) are optional.","For paths that must never mutate, use the dedicated POST /v1/projects/{ref}/database/query/read-only endpoint so read-only is enforced by the route itself rather than by a flag you might forget.","A successful call returns HTTP 201 with the result rows serialized as JSON.","Use this endpoint for administrative SQL — create extension, grant, inspecting pg_stat_activity or pg_locks, one-off backfills — not for application read/write traffic.","Route application traffic to the Data API at https://<ref>.supabase.co/rest/v1 or to a direct Postgres / pooler connection instead.","Version real schema changes through GET/POST/PUT/DELETE /v1/projects/{ref}/database/migrations and GET/PATCH /v1/projects/{ref}/database/migrations/{version} so branches and CI stay reproducible.","Fetch the project's PostgREST OpenAPI description with GET /v1/projects/{ref}/database/openapi when you need the current exposed schema shape.","Official documentation: https://supabase.com/docs/reference/api/v1-run-a-query | https://api.supabase.com/api/v1-json"],"gotchas":["The endpoint is marked [Beta] in the Supabase API reference — behaviour and response shape may change without a major version bump.","Statements execute with elevated platform privileges. A careless DDL or an unqualified DELETE here can break the project with no confirmation prompt. Default to read_only:true and opt into writes deliberately.","Long-running statements will hit an HTTP timeout well before Postgres finishes. Run heavy migrations or backfills through the migrations endpoint or a direct connection with a proper statement_timeout.","Results are JSON, so Postgres types such as numeric, bytea, timestamptz and interval arrive stringified. Cast explicitly in SQL when exact typing matters to the caller.","Every call consumes the 120 req/min per-project budget. This endpoint is not a connection pool — do not put it in a request path.","Under OAuth, mutating queries require the database:write scope; read-only queries need database:read. A PAT bypasses this distinction entirely, which is exactly why a PAT is risky in automation.","The Supabase docs do not state which Postgres role executes the query. Do not build a security model that assumes a restricted role — assume elevated privilege."],"contributor":"cloud-infra-route-author","created":"2026-07-31T03:26:35.362Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":{"status":"unverified","method":"community-contrib","at":"2026-07-31T03:26:35.362Z"},"url":"https://mcp.waymark.network/r/3c53bd71-d77f-4070-b681-df16b0d5cba6"}