From 406dcf4f4e6a846c4c6538ecadcb13ac68deb491 Mon Sep 17 00:00:00 2001 From: dimgigov Date: Fri, 15 May 2026 22:56:45 +0300 Subject: [PATCH] docs(ormin): clarify transaction and returning support MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Top-level BEGIN/COMMIT/ROLLBACK work (server-side) - SAVEPOINT (nested tx) does not work — BaraDB server limitation - RETURNING parsed but ignored by BaraDB executor — server limitation --- clients/nim/ormin/README-baradb.md | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/clients/nim/ormin/README-baradb.md b/clients/nim/ormin/README-baradb.md index 27c097e..632f077 100644 --- a/clients/nim/ormin/README-baradb.md +++ b/clients/nim/ormin/README-baradb.md @@ -112,15 +112,27 @@ If you omit the port, the default `9472` is used. | `query(T)` typed | ✅ | | `createProc` | ✅ | | `createIter` | ✅ | -| `transaction` | ⚠️ (relies on server support) | -| `returning` | ⚠️ (single-row limit works) | +| `transaction` | ✅ (top-level only) | +| `returning` | ❌ (not yet supported by BaraDB server) | ## Limitations - **Wire protocol strings**: BaraDB returns all column values as strings over the wire. The backend parses them at runtime. This is slightly less efficient than native SQLite/PostgreSQL bindings but keeps the implementation simple and portable. -- **`getLastId`**: Currently returns `0`. If BaraDB supports `RETURNING id`, use `limit 1` queries instead. +- **`getLastId` / `RETURNING`**: BaraDB's SQL parser recognizes `RETURNING`, but the executor ignores it — the result is always just the affected-row count. For now, use a `limit 1` `select` after `insert` to fetch the new row. +- **Nested transactions (SAVEPOINT)**: Not supported by BaraDB. Top-level `BEGIN` / `COMMIT` / `ROLLBACK` work fine, but nested `transaction:` blocks (which Ormin implements via `SAVEPOINT`) will fail. - **Async**: Ormin's DSL is synchronous by design. This backend uses `SyncClient` under the hood. If you need async, use the raw `baradb/client` async API directly. +## Why some features are missing + +These are **server-side limitations**, not client bugs: + +| Feature | Status in BaraDB server | Needed for | +|---------|------------------------|------------| +| `SAVEPOINT` | Not implemented | Nested `transaction:` blocks | +| `RETURNING` | Parsed but ignored by executor | `insert ... returning id` | + +If you need these, open an issue on the [BaraDB server repo](https://git.invoicing.top/baraba/Baradb) — the fixes belong in `src/barabadb/query/executor.nim` and `src/barabadb/query/parser.nim`. + ## Running the example ```bash