Baradb/clients/nim/ormin/README-baradb.md

Ormin + BaraDB

This is a fork of Ormin (prepared SQL statement generator for Nim) with added support for BaraDB — a multimodal database engine with a binary wire protocol.

What changed?

• Added DbBackend.baradb to the backend enum.
• Added ImportTarget.baradb for schema import.
• New backend file ormin/ormin_baradb.nim that bridges Ormin's compile-time query DSL to the BaraDB Nim client (baradb/client).

Installation

Install both the BaraDB client and this Ormin fork:

# Install BaraDB client (from barabadb/clients/nim)
cd clients/nim
nimble install

# Install Ormin with BaraDB support
cd ormin
nimble install

Quick Start

1. Write your schema

Create a file named model.sql:

CREATE TABLE users (
  id SERIAL PRIMARY KEY,
  name VARCHAR(255) NOT NULL,
  email VARCHAR(255),
  age INT
);

2. Use Ormin DSL in Nim

import json
import ormin

importModel(DbBackend.baradb, "model")

let db {.global.} = open("127.0.0.1:9472", "admin", "", "default")

# Select tuples
proc listUsers() =
  let rows = query:
    select users(id, name, email)
    orderby id
  for r in rows:
    echo "User #", r.id, ": ", r.name

# Parameterized query
proc findUser(name: string) =
  let row = query:
    select users(id, name, email)
    where name == ?name
    limit 1
  echo row

# Insert
proc addUser(name, email: string; age: int) =
  query:
    insert users(name = ?name, email = ?email, age = ?age)

# JSON output
proc usersAsJson(): seq[JsonNode] =
  result = query:
    select users(id, name)
    produce json

when isMainModule:
  listUsers()

Compile with:

nim c -r myapp.nim

Connection string format

open(host:port, username, password, database)

let db = open("127.0.0.1:9472", "admin", "", "default")

If you omit the port, the default 9472 is used.

Supported Ormin features

Feature	Status
select	✅
where	✅
join / leftjoin	✅
insert	✅
update	✅
delete	✅
orderby	✅
limit / offset	✅
? placeholders	✅
% JSON params	✅
produce json	✅
query(T) typed	✅
createProc	✅
createIter	✅
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 / 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 — the fixes belong in src/barabadb/query/executor.nim and src/barabadb/query/parser.nim.

Running the example

cd clients/nim/ormin/examples
nim c -r baradb_basic.nim

(Requires a BaraDB server on localhost:9472.)

License

Same as upstream Ormin — MIT.