diff --git a/docs/modules/sql-on-fhir/operation-run.md b/docs/modules/sql-on-fhir/operation-run.md index 4435ec9a3..93f8f2369 100644 --- a/docs/modules/sql-on-fhir/operation-run.md +++ b/docs/modules/sql-on-fhir/operation-run.md @@ -176,6 +176,15 @@ For example, if you specify `Accept: application/fhir+json` and `_format`: JSON, If you specify `Accept: application/json` and `_format`: JSON, the server will return the processed data (without wrapping inside Binary resource). +## SQL errors + +Aidbox fetches the whole result of the SQL it builds from the ViewDefinition before it sends the response. When that SQL fails, the response has an error status and an `OperationOutcome` in every `_format`, with the Postgres error in `diagnostics`. + +| Status | Condition | +|--------|------------------------------------------------------------------------------------------------------------------------| +| 422 | The ViewDefinition can't be processed, for example a column declared as `integer` whose values are text, such as `gender` | +| 500 | The database fails for a reason outside the ViewDefinition, such as a lost connection | + ## Examples ### Provided resources and ViewDefinition diff --git a/docs/modules/sql-on-fhir/operation-sqlquery-run.md b/docs/modules/sql-on-fhir/operation-sqlquery-run.md index c3341648f..4428b5fee 100644 --- a/docs/modules/sql-on-fhir/operation-sqlquery-run.md +++ b/docs/modules/sql-on-fhir/operation-sqlquery-run.md @@ -202,6 +202,34 @@ When `_format=fhir`, each result column is rendered using a FHIR `value[x]` type If a result column has a SQL type not listed above (for example `jsonb`, `interval`, `array`, `xml`), the operation returns `422 Unprocessable Entity`. Cast the column to a supported type inside the SQL query to work around this. +## SQL execution + +Aidbox runs the Library's SQL in a read-only transaction. SQL that changes data fails with 422 and leaves the database as it was. This covers `INSERT`, `UPDATE`, `DELETE`, `MERGE`, a `WITH` query that modifies data, a function that writes, `nextval()` and `SELECT … FOR UPDATE`. + +The SQL must be a single statement. A trailing semicolon is fine, but Aidbox counts any text after it as another statement, even a comment, and refuses SQL with more than one statement with 422. + +Aidbox fetches the whole result before it sends the response, so an error in the SQL returns an error status with an `OperationOutcome` in every `_format`. + +| Status | Condition | +|--------|------------------------------------------------------------------------------------------------------------------------------------| +| 422 | The SQL has more than one statement | +| 422 | The SQL changes data | +| 422 | The SQL itself is at fault: a syntax error, an unknown table or column, a missing privilege, a data error such as division by zero or an invalid cast, or a subquery that returns more than one row | +| 422 | With `_format=fhir`, a result column has a SQL type that [Output format](#output-format) doesn't list | +| 500 | The database fails for a reason outside the SQL: a lost connection, a cancelled or timed-out statement, exhausted resources, a lock timeout, or an internal error | + +The `diagnostics` of the `OperationOutcome` carries the reason, for example: + +```text +SQL on FHIR runs queries read-only: ERROR: cannot execute INSERT in a read-only transaction +The SQL has 2 statements; SQL on FHIR runs a single one +ERROR: division by zero +``` + +{% hint style="warning" %} +The read-only transaction protects the data. The SQL still runs as Aidbox's database user, so it can read every table that user can read, Aidbox's own tables included. When that user is a Postgres superuser, a read-only transaction also lets the SQL read files and run programs on the database server. Grant `$sqlquery-run` to clients you would trust with read access to the whole database, and restrict it with an [AccessPolicy](../../access-control/authorization/access-policies.md). +{% endhint %} + ## Examples The examples below assume the following ViewDefinitions and supporting resources exist on the server: