dimgigov
cd46edcb67
CI / test (push) Has been cancelled
CI / verify (push) Has been cancelled
Clients CI / build-server (push) Has been cancelled
Clients CI / test-python (push) Has been cancelled
Clients CI / test-javascript (push) Has been cancelled
Clients CI / test-nim (push) Has been cancelled
Clients CI / test-rust (push) Has been cancelled
Storage fixes: - Fix bloom filter hash2 OverflowDefect (uint64 instead of int Hash) - Fix MemTable.put size calculation on overwrite (was leaking size) - Fix fuzz_test duplicate-key issues in LSM delete and SSTable tests Test fixes: - Fix stress_test.nim: replace deprecated threadpool with std/threads - Fix fuzz_test.nim: add missing imports (tables, algorithm, sets) - Fix fuzz_test.nim: var sst for close() compatibility - Remove unused imports from test_all.nim and bench_all.nim Docker / CI fixes: - Fix Dockerfile.source: invalid nimlang/nim:2.2.10-alpine tag → 2.2.10 + ubuntu:24.04 runtime - Fix Dockerfile.source healthcheck (--spider → -qO- for 200 OK) - Fix Dockerfile run comment ports (9470/9471 → 9912/9913) - Fix scripts/docker-run.sh healthcheck port (9470 → 9912) - Add ARG BUILD_DATE/VCS_REF to Dockerfile for docker-build.sh - Update all version strings 1.1.4 → 1.1.6 across nimble/docker/source/docs
164 lines
3.3 KiB
Markdown
164 lines
3.3 KiB
Markdown
# BaraDB Nim Client
|
|
|
|
Official Nim client for **BaraDB** — a multimodal database engine.
|
|
|
|
## Features
|
|
|
|
- **Binary wire protocol** — fast TCP communication via `asyncnet`
|
|
- **Async/await API** — non-blocking by default
|
|
- **Sync wrapper** — `SyncClient` for blocking code
|
|
- **Query builder** — fluent SQL construction
|
|
- **Zero server dependencies** — self-contained, uses only Nim stdlib
|
|
|
|
## Installation
|
|
|
|
Add to your `.nimble` file:
|
|
|
|
```nim
|
|
requires "baradb >= 1.1.6"
|
|
```
|
|
|
|
Or clone locally:
|
|
|
|
```bash
|
|
git clone https://codeberg.org/baraba/baradb
|
|
cd clients/nim
|
|
nimble develop
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
### Async API
|
|
|
|
```nim
|
|
import asyncdispatch
|
|
import baradb/client
|
|
|
|
proc main() {.async.} =
|
|
let client = newClient()
|
|
await client.connect()
|
|
let result = await client.query("SELECT name, age FROM users WHERE age > 18")
|
|
echo result
|
|
client.close()
|
|
|
|
waitFor main()
|
|
```
|
|
|
|
### Sync API
|
|
|
|
```nim
|
|
import baradb/client
|
|
|
|
let client = newSyncClient()
|
|
client.connect()
|
|
let result = client.query("SELECT name, age FROM users WHERE age > 18")
|
|
echo result
|
|
client.close()
|
|
```
|
|
|
|
### Parameterized Queries
|
|
|
|
```nim
|
|
import baradb/client
|
|
|
|
proc main() {.async.} =
|
|
let client = newClient()
|
|
await client.connect()
|
|
let result = await client.query(
|
|
"SELECT * FROM users WHERE age > $1",
|
|
@[WireValue(kind: fkInt64, int64Val: 18)]
|
|
)
|
|
echo result
|
|
client.close()
|
|
|
|
waitFor main()
|
|
```
|
|
|
|
### Query Builder
|
|
|
|
```nim
|
|
import baradb/client
|
|
|
|
proc main() {.async.} =
|
|
let client = newClient()
|
|
await client.connect()
|
|
let result = await newQueryBuilder(client)
|
|
.select("name", "email")
|
|
.from("users")
|
|
.where("active = true")
|
|
.orderBy("name", "ASC")
|
|
.limit(10)
|
|
.exec()
|
|
echo result
|
|
client.close()
|
|
|
|
waitFor main()
|
|
```
|
|
|
|
## Running Tests
|
|
|
|
Unit tests (no server):
|
|
|
|
```bash
|
|
nimble test
|
|
```
|
|
|
|
Integration tests (requires server on `localhost:9472`):
|
|
|
|
```bash
|
|
# Start server
|
|
docker run -d -p 9472:9472 baradb:latest
|
|
|
|
# Run integration tests
|
|
nim c -r tests/test_integration.nim
|
|
```
|
|
|
|
## API Reference
|
|
|
|
### `ClientConfig`
|
|
|
|
| Field | Default | Description |
|
|
|--------------|-------------|------------------------|
|
|
| `host` | `127.0.0.1` | Server hostname |
|
|
| `port` | `9472` | TCP port |
|
|
| `database` | `default` | Default database |
|
|
| `username` | `admin` | Username |
|
|
| `password` | `""` | Password |
|
|
| `timeoutMs` | `30000` | Timeout in ms |
|
|
| `maxRetries` | `3` | Max reconnect retries |
|
|
|
|
### Methods (Async)
|
|
|
|
- `connect()` — open TCP connection
|
|
- `close()` — close connection
|
|
- `query(sql)` — execute SELECT-like query
|
|
- `query(sql, params)` — parameterized query
|
|
- `exec(sql)` — execute DDL/DML, returns affected rows
|
|
- `auth(token)` — JWT authentication
|
|
- `ping()` — health check
|
|
|
|
### Methods (Sync)
|
|
|
|
Same as async but blocking. Available on `SyncClient`.
|
|
|
|
## Ormin Integration
|
|
|
|
The Nim client ships with an [Ormin](https://github.com/Araq/ormin) backend for compile-time checked SQL queries.
|
|
|
|
```nim
|
|
import ormin
|
|
|
|
importModel(DbBackend.baradb, "my_model")
|
|
let db {.global.} = open("127.0.0.1:9472", "admin", "", "default")
|
|
|
|
let rows = query:
|
|
select users(id, name)
|
|
where name == ?"alice"
|
|
```
|
|
|
|
See `examples/ormin_basic.nim` for a full sample.
|
|
|
|
## License
|
|
|
|
Apache-2.0
|