Skip to main content

Database

These endpoints power the console's database Studio. They act as the database owner, so row-level security doesn't apply to them; every write is audited. App code should use the SDK instead.

Auth: reads need view; writes need manage (owner, project developers, admins). All paths start with /api/projects/:name/db.

Endpoints​

MethodPathBody / queryWhat it does
GET/dbDatabase status, roles, SQL helpers, table templates and column types
GET/db/tablesTables with columns, RLS state and policy count
POST/db/tables{ name, columns?, template?, templateParam?, rls? }Create a table. RLS is on by default.
PATCH/db/tables/:table{ name?, rlsEnabled?, comment? }Rename, toggle RLS, comment
DELETE/db/tables/:table?cascade=1Drop a table
POST/db/tables/:table/columns{ name, type, nullable?, default?, unique?, references? }Add a column
PATCH/db/tables/:table/columns/:column{ name?, type?, nullable?, default? }Change a column
DELETE/db/tables/:table/columns/:columnDrop a column
GET/db/tables/:table/rows?limit&offset&order=col.desc&filter=col.eq.valueBrowse rows. order and filter repeat.
POST/db/tables/:table/rows{ rows: [...] } or one row objectInsert rows
PATCH/db/tables/:table/rows{ pk: { id: 1 }, patch: { … } }Update one row by primary key
DELETE/db/tables/:table/rows{ pks: [{ id: 1 }] }Delete rows by primary key
POST/db/sql{ sql, readOnly?, timeoutMs? }Run SQL. readOnly needs only view.
GET/db/policiesRow-level security policies in plain English
POST/db/policies{ table, template, param? }Add a policy from a template
DELETE/db/policies/:idDrop a policy
GET/db/schemaTables, columns, relationships and policies (for the diagram)
GET/db/migrationsApplied migrations
POST/db/migrations{ name, sql }Apply a named migration once
GET/db/snippetsSaved SQL snippets
POST/db/snippets{ name, sql }Save a snippet
DELETE/db/snippets/:idDelete a snippet

Run SQL​

POST /api/projects/expenses/db/sql
Content-Type: application/json

{ "sql": "select status, count(*) from purchase_requests group by 1", "readOnly": true }

Response 200

{
"results": [{ "command": "SELECT", "rowCount": 2, "rows": [{ "status": "pending", "count": "4" }, { "status": "approved", "count": "9" }] }],
"durationMs": 12
}

A statement timeout applies (15 s by default; timeoutMs can raise it up to four times that).

Apply a migration​

POST /api/projects/expenses/db/migrations
Content-Type: application/json

{ "name": "002_add_status", "sql": "alter table purchase_requests add column status text not null default 'pending';" }

Response 200: { "name": "002_add_status", "status": "applied", "checksum": "…" }. The same name and SQL again returns already_applied. Different SQL under an applied name returns 409 MIGRATION_CHANGED: write a new migration.

Migrations shipped in db/migrations/ are applied the same way on deploy. See the Data section.

Errors​

Database errors come back as { "error": { "code", "message" } } with the platform's code (for example BAD_REQUEST, MIGRATION_CHANGED) or the database's message.

Was this page helpful?