Document $psql / $psql-cancel and SQL Console changes#11
Open
andreyorst wants to merge 1 commit intomainfrom
Open
Document $psql / $psql-cancel and SQL Console changes#11andreyorst wants to merge 1 commit intomainfrom
andreyorst wants to merge 1 commit intomainfrom
Conversation
spicyfalafel
requested changes
Apr 28, 2026
|
|
||
| ## $psql | ||
|
|
||
| Run a raw multi-statement SQL script in a single request. The endpoint is what the Aidbox UI SQL Console uses; `/$notebook-psql` is an alias with identical behavior. |
Collaborator
There was a problem hiding this comment.
What's the point of mentioning $notebook-psql?
| { "query": "SELECT 1; SELECT 2", "limit": 1000 } | ||
| ``` | ||
|
|
||
| - `query` — the SQL text. Sent verbatim to PostgreSQL; Aidbox does not split, trim, or rewrite it. |
Collaborator
There was a problem hiding this comment.
passive voice -> active voice:
Aidbox sends the query verbatim, without splitting, trimming, or rewriting it.
| ``` | ||
|
|
||
| - `query` — the SQL text. Sent verbatim to PostgreSQL; Aidbox does not split, trim, or rewrite it. | ||
| - `limit` (optional) — applied via JDBC `setMaxRows` to cap each result set. |
Collaborator
There was a problem hiding this comment.
why we mention setMaxRows?
|
|
||
| ### Breaking change in 2604 | ||
|
|
||
| Prior versions returned a vector of per-statement debug objects and accepted an `execute=true` query parameter to switch between two execution paths; multi-statement scripts were split on `\n----\n`. All three behaviours were removed. Old clients that posted to `/$psql` without `execute=true` and parsed `[{:result …}, …]` need to be updated to the shape above. The endpoint URL is unchanged. |
Collaborator
There was a problem hiding this comment.
execute=true was only $psql thing? no $sql updates?
|
|
||
| **Features** | ||
|
|
||
| * Reworked SQL Console — see the new [`$psql` endpoint](../api/rest-api/other/sql-endpoints.md#usdpsql) for the full backend contract. Configurable per-tab transaction mode (transaction / autocommit), `statement_timeout`, fetch size, foreground / background execution, and `Tab` keybinding to indent. `EXPLAIN` plans render as a monospace block. |
Collaborator
There was a problem hiding this comment.
call to action "see the new psql endpoint" is useless because most of the people will use ui, not the endpoint, right?
Collaborator
There was a problem hiding this comment.
explaining too many UI details
|
|
||
| **Breaking changes** | ||
|
|
||
| * `$psql` response shape changed from `[{:result :duration :status :query}, …]` to `{:status :result [{:type :rset|:count :data …} …] :duration :query}`. The `execute=true` query parameter and the `\n----\n` multi-statement separator are no longer recognised. `$sql` is unchanged. See [SQL endpoints](../api/rest-api/other/sql-endpoints.md#usdpsql). |
Collaborator
There was a problem hiding this comment.
It seems no one really knows $psql endpoint. Please link to the $psql breaking change paragraph.
| **Breaking changes** | ||
|
|
||
| * `$psql` response shape changed from `[{:result :duration :status :query}, …]` to `{:status :result [{:type :rset|:count :data …} …] :duration :query}`. The `execute=true` query parameter and the `\n----\n` multi-statement separator are no longer recognised. `$sql` is unchanged. See [SQL endpoints](../api/rest-api/other/sql-endpoints.md#usdpsql). | ||
| * The legacy DB Console at `/ui/db` now redirects to the new SQL Console at `/u/db-console` and forwards the `?query=` URL parameter. |
Collaborator
There was a problem hiding this comment.
"and forwards the ?query= URL parameter." - does it matter?
|
|
||
| * Reworked SQL Console — see the new [`$psql` endpoint](../api/rest-api/other/sql-endpoints.md#usdpsql) for the full backend contract. Configurable per-tab transaction mode (transaction / autocommit), `statement_timeout`, fetch size, foreground / background execution, and `Tab` keybinding to indent. `EXPLAIN` plans render as a monospace block. | ||
| * Background SQL execution via `X-Aidbox-Sql-Async: true` — the server runs the query without retaining result rows; only metadata (status / duration / query / error) is recorded. | ||
| * Robust query cancellation via [`$psql-cancel`](../api/rest-api/other/sql-endpoints.md#usdpsql-cancel) — matches by `application_name` set from the new `X-Aidbox-Sql-Query-Id` header instead of a fragile `LIKE '%query%'` scan. Cancels both sync and async runs. |
Collaborator
There was a problem hiding this comment.
too much text for this thing. "Query cancellation via $psql-cancel" is fine imho
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Documents the SQL Console v3 changes shipping in
edge(sansara PR #7487 / aidbox-ui PR #63):docs/api/rest-api/other/sql-endpoints.md— new sections for$psql(and the$notebook-psqlalias) and$psql-cancel. Documents the new response shape, all execution headers (X-Aidbox-Sql-Autocommit,-Timeout,-Read-Only,-Query-Id,-Async), the cancel flow, and the breaking change (old vector-of-debug-objects shape,execute=truequery param, and\n----\nseparator are gone).docs/overview/release-notes.md— April 2026 edge entry covering the new features and breaking changes.docs/overview/aidbox-ui/README.md— expanded the SQL Console blurb with per-tab settings, foreground / background execution, Tab-key indent, and prettyEXPLAIN.