BlueForge Docs

Execute SQL

Run parameterized SQL queries directly against a project's Postgres database. Useful for migrations, ad-hoc queries, and schema inspection.

Endpoint

MethodPathAuthIdempotent
POST
/api/platform/projects/:id/sql
tenant Bearerno

Parameters

NameTypeRequiredDefaultNotes
id
stringyes—path parameter; project ID
query
stringyes—SQL statement; max 50,000 characters

Response

{
  rows: Record<string, unknown>[]
  rowCount: number
  fields: Array<{
    name: string
    dataTypeID: number
  }>
  latencyMs: number
}

Examples

curl -X POST https://api.blueforge.studio/api/platform/projects/prj_xxx/sql \
  -H "Authorization: Bearer $BF_TENANT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT id, name FROM users LIMIT 10"}'

import { Client } from "@blueforge/client"

const result = await client.projects.sql("prj_xxx", {
  query: "SELECT id, name FROM users WHERE active = $1 LIMIT $2",
  params: [true, 10]
})

console.log(`Returned ${result.rowCount} rows in ${result.latencyMs}ms`)

Pitfalls

  • Query length is limited to 50,000 characters. Split large batch statements into multiple calls.
  • A 30-second statement timeout is enforced. Queries exceeding this are aborted.
  • DDL statements (CREATE TABLE, ALTER TABLE, etc.) are supported but should be used with caution outside migration windows.
  • This endpoint is not idempotent. Replaying the same INSERT or UPDATE will duplicate or overwrite data.

See also

  • projects.create — Create a new platform project
  • SQL query capabilities depend on the project schema; inspect via 
    SELECT table_name FROM information_schema.tables

Tested against

  • @blueforge/platform-api: 2.4.1
  • Last verified: 2026-07-15