Skip to main content

Run SQL

Run SQL against a project’s PostgreSQL database.

POST /projects/:projectid/databases/:dbid/query

Authentication​

Send the project API key in the Authorization header, without a Bearer prefix. Requires databases.query for the database in the URL.

Request​

FieldTypeDescription
querystring, requiredSQL to execute.
Powerful permission

databases.query is not a read-only grant. SQL can change or delete data and schema without separate write, delete, or schema grants. Give it only to trusted server-side integrations. Use Read rows when you only need a paginated read.

Example​

Use the environment variables from the database overview. Replace example IDs with your own.

curl --include --request POST \
--header "Authorization: ${INTELLECTIBLE_PROJECT_API_KEY}" \
--header "Content-Type: application/json" \
--data '{
"query": "SELECT customer_name, status FROM customers ORDER BY customer_name LIMIT 20;"
}' \
"${INTELLECTIBLE_PUBLIC_API_URL}/projects/${INTELLECTIBLE_PROJECT_ID}/databases/${INTELLECTIBLE_DATABASE_ID}/query"

Response​

200 OK

{
"rows": [
{
"customer_name": "Ada",
"status": "active"
},
{
"customer_name": "Grace",
"status": "active"
}
]
}

rows contains the rows returned by the statement, or an empty array when it returns none. There is no separate affected-row count. Use a suitable RETURNING clause when you need data back from a write.

Construct SQL carefully​

This HTTP endpoint accepts a SQL string only; it does not accept a parameter-values array. Do not concatenate untrusted input into SQL. Prefer the structured row endpoints for user-supplied values, or construct SQL using a library that safely quotes values and identifiers.

Add an explicit LIMIT to exploratory reads. The row endpoint’s 1000-row cap does not apply here, but execution time, resource limits, and project quotas still do. Database resource settings cannot be overridden through this endpoint. Retrying SQL that writes data can repeat its effects.

See Errors and safe retries for shared failure handling.