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
| Method | Path | Body / query | What it does |
|---|---|---|---|
GET | /db | Database status, roles, SQL helpers, table templates and column types | |
GET | /db/tables | Tables 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=1 | Drop 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/:column | Drop a column | |
GET | /db/tables/:table/rows | ?limit&offset&order=col.desc&filter=col.eq.value | Browse rows. order and filter repeat. |
POST | /db/tables/:table/rows | { rows: [...] } or one row object | Insert 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/policies | Row-level security policies in plain English | |
POST | /db/policies | { table, template, param? } | Add a policy from a template |
DELETE | /db/policies/:id | Drop a policy | |
GET | /db/schema | Tables, columns, relationships and policies (for the diagram) | |
GET | /db/migrations | Applied migrations | |
POST | /db/migrations | { name, sql } | Apply a named migration once |
GET | /db/snippets | Saved SQL snippets | |
POST | /db/snippets | { name, sql } | Save a snippet |
DELETE | /db/snippets/:id | Delete 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.