Baradb/clients/nim-allographer/PLAN_BARADB.md

План за интеграция на BaraDB в nim-allographer

Цел

BaraDB е пълноценен драйвер в nim-allographer. Използва се чист Nim клиент (BaraClient / SyncClient) без C зависимости. Compile-time switch: DB_BARADB.

---

Актуално състояние (2026-05-21)

Статус по фази

Фаза	Състояние	Бележки
1. Инфраструктура и типове	ГОТОВО	env.nim, connection.nim, query_builder.nim, schema_builder.nim — всичко е интегрирано
2. Query Builder — SQL генерация	ГОТОВО	baradb_generator.nim (397 реда), baradb_builder.nim (237 реда) — всички CRUD + агрегати
3. Query Builder — execution	ГОТОВО (с бележки)	baradb_exec.nim (716 реда) — всички операции работят, но insertId използва SELECT MAX вместо RETURNING
4. Schema Builder	СКЕЛЕТ	Flow-ът е налице, но column type mapping е 24 реда вместо 466 (PostgreSQL)
5. Тестове и документация	МИНИМАЛНО	Само test_open.nim и test_query.nim

---

Какво е ГОТОВО (не пипай)

Wire Protocol клиент — query_builder/libs/baradb/baradb_client.nim (706 реда)

• Pure Nim, async + sync, без C FFI
• Binary serialization (big-endian) на всички WireValue типове (13 типа: fkNull..fkJson)
• mkQuery, mkQueryParams, mkAuth, mkPing съобщения
• readQueryResponse — парсва mkData, mkComplete, mkError, mkReady
• Вграден QueryBuilder (fluent) за standalone употреба

Connection Pool — baradb_open.nim + baradb_exec.nim

• dbOpen(Baradb, database, user, pass, host, port, maxConnections, timeout)
• getFreeConn() — async с deque-based waiters и timeout
• returnConn() — освобождава и буди чакащи
• Connection aging: maxConnectionLifetime, maxConnectionIdleTime
• refreshConn(), hasConnExpired(), openBaradbConn()

Query Builder — baradb_query.nim (386 реда)

• Всички fluent методи: select, table, distinct, join, leftJoin
• where / orWhere (string|int|float, bool, nil overloads)
• whereBetween, whereNotBetween, whereIn, whereNotIn, whereNull
• groupBy, having, orderBy, limit, offset
• raw(sql, args) — суров SQL с параметри

SQL Generator — baradb_generator.nim (397 реда)

• Всички SQL конструкции: SELECT, INSERT, UPDATE, DELETE, агрегати
• Quoting с backtick ` (MySQL/SQLite стил, не PostgreSQL ")
• Placeholder: ? (не $1)

Execution — baradb_exec.nim (716 реда)

• get(), first(), find() → seq[JsonNode] / Option[JsonNode]
• getPlain(), firstPlain(), findPlain() → seq[seq[string]]
• insert(JsonNode), insert(seq[JsonNode]), insertId(...)
• update(JsonNode), delete(), delete(id)
• count(), min(), max(), avg(), sum()
• begin(), commit(), rollback() + transaction макро
• Raw query варианти за всички операции
• seeder шаблони

ORM — споделен модул

• orm() template работи с BaraDB

Schema Code Generation — usecases/baradb/create_schema.nim

• Четене от information_schema и генериране на Nim типове

---

Какво трябва да се ДОИЗПИПА

1. Prepared Statements — САМО типове, НЯМА имплементация

Текущо състояние: Типовете са дефинирани в baradb_types.nim:

• BaradbPreparedEntry — sql, nArgs, refCount, lastUsedAt
• BaradbPreparedContext — owner, connI
• BaradbPreparedStatement — owner, entry, sql, nArgs, isClosed
• preparedCache е инициализиран в baradb_open.nim

Липсващо:

• prepare() proc — да създава BaradbPreparedStatement
• ensureStmt() — да кешира и преизползва statement-и
• get*() / exec*() procs върху BaradbPreparedStatement
• withConn() proc за context-based изпълнение
• flushStmt() / clearStmtCache()

Wire protocol поддръжка: baradb_client.nim вече има mkQueryParams — параметризираните заявки са вградени на ниво протокол. Трябва само да се свърже от allographer слоя.

Проблем: В момента baradb_exec.nim използва client-side string interpolation (formatSql + escapeSqlValue) вместо server-side параметри. Това е по-малко сигурно и по-малко ефективно.

Референция: PostgreSQL драйверът има ~300 реда prepared statement код (postgres_exec.nim — ensureStmt, preparedQuery, preparedExec, deallocate, flush, clearCache, context API).

План:

Файл: baradb_exec.nim
- [ ] prepare(sql: string): BaradbPreparedStatement
- [ ] ensureStmt(conn, sql, nArgs): BaradbPreparedEntry — кеширане в preparedCache
- [ ] preparedGet(stmt, args): seq[JsonNode] — използва mkQueryParams
- [ ] preparedExec(stmt, args): void
- [ ] withConn(pool, callback): auto — context-based
- [ ] flushStmt(stmt): void — deallocate
- [ ] clearStmtCache(): void

---

2. RETURNING id за INSERT — използва SELECT MAX (race condition)

Текущо състояние в baradb_exec.nim:

discard await self.pools.conns[connI].client.exec(sql)
let idSql = &"SELECT MAX(\"{key}\") FROM \"{table}\""
let qr = await self.pools.conns[connI].client.query(idSql)

Проблем: Race condition при конкурентни INSERT-и — друг INSERT може да мине между двете заявки.

Варианти:

1. INSERT ... RETURNING id — ако BaraDB го поддържа (за предпочитане, атомарно)
2. last_insert_rowid() — ако BaraDB има такава функция (както SQLite)
3. SELECT LAST_INSERT_ID() — MySQL-стил
4. CTE с INSERT ... RETURNING — WITH inserted AS (INSERT ...) SELECT id FROM inserted

План:

Файл: baradb_exec.nim — insertId proc
- [ ] Проверка дали BaraDB поддържа RETURNING
- [ ] Ако да: INSERT ... RETURNING "id" (като PostgreSQL)
- [ ] Ако не: използване на заявката за последно вмъкнат ID от wire protocol-а
- [ ] Премахване на SELECT MAX workaround

---

3. Schema Builder — Column Type Mapping е СКЕЛЕТ

Текущо състояние в queries/baradb/sub/create_column_query.nim (24 реда):

query.add(&"`{column.name}` {column.typ}")
# Само: NOT NULL, UNIQUE, DEFAULT

Проблем: Изкарва raw RdbTypeKind enum стойности (rdbIncrements, rdbString) вместо SQL типове (SERIAL, VARCHAR(256)).

Референция: PostgreSQL sub/create_column_query.nim — 466 реда, обработва всички RdbTypeKind:

• rdbIncrements → SERIAL PRIMARY KEY
• rdbBigIncrements → BIGSERIAL PRIMARY KEY
• rdbInteger → INTEGER
• rdbBigInteger → BIGINT
• rdbBoolean → BOOLEAN
• rdbString(n) → VARCHAR(n) (default 255)
• rdbText → TEXT
• rdbFloat → DOUBLE PRECISION
• rdbDecimal(p,s) → DECIMAL(p,s)
• rdbDate → DATE
• rdbDateTime / rdbTimestamp → TIMESTAMP
• rdbTimestampz → TIMESTAMPTZ
• rdbTime → TIME
• rdbBinary → BYTEA
• rdbUuid → UUID
• rdbJson / rdbJsonb → JSON / JSONB
• rdbEnum → VARCHAR(255) + CHECK constraint
• Foreign keys: REFERENCES "table"("column") ON DELETE/UPDATE CASCADE/SET NULL/...
• Indexes, comments, unsigned

План:

Файл: queries/baradb/sub/create_column_query.nim
- [ ] Пълен mapping на RdbTypeKind → SQL тип (по PostgreSQL референцията)
- [ ] Auto-increment: SERIAL / BIGSERIAL PRIMARY KEY
- [ ] String/Text: VARCHAR(n), TEXT с default 255
- [ ] Числови: INTEGER, BIGINT, SMALLINT, DOUBLE PRECISION, DECIMAL(p,s)
- [ ] Дати: DATE, TIME, TIMESTAMP, TIMESTAMPTZ
- [ ] Бинарни: BYTEA
- [ ] Специални: UUID, JSON, JSONB, BOOLEAN, ENUM
- [ ] Foreign key constraints: REFERENCES ... ON DELETE/UPDATE
- [ ] Index генерация
- [ ] Column comments

Файл: queries/baradb/create_table.nim
- [ ] Да използва create_column_query вместо raw {column.typ}

Файлове: rename_column.nim, rename_table.nim
- [ ] Fix: `changeTo` → `previousName` (ако е bug)

Файл: create_migration_table.nim
- [ ] Консистентност: backtick quoting вместо double-quote

Файл: schema_utils.nim
- [ ] shouldRun() — checksum-based skip (вместо винаги true)

---

4. SQL Quoting Inconsistency

Проблем: baradb_generator.nim използва backtick `, но create_migration_table.nim използва double-quote ". Трябва да е консистентно.

Въпрос: Какво използва BaraDB сървърът? Ако поддържа и двете — изберем едно. Ако само едно — коригираме навсякъде.

---

5. Database URL Support — липсва

PostgreSQL/MySQL/MariaDB драйверите поддържат databaseUrl = asDatabaseUrl("postgresql://..."). BaraDB dbOpen приема само позиционни параметри.

Файл: baradb_open.nim
- [ ] Парсване на `baradb://user:pass@host:port/db` URL
- [ ] Интеграция с `libs/database_url.nim`

---

6. Paginate / fastPaginate — липсват

Налични в други драйвери, липсват в BaraDB query builder.

Файл: baradb_exec.nim
- [ ] paginate(page, perPage): seq[JsonNode] + metadata
- [ ] fastPaginate(key, perPage): cursor-based

---

7. whereNull Bug

Проблем: baradb_generator.nim:205 — whereNullSql референцира row["symbol"], но baradb_query.nim whereNull не задава "symbol" ключ. Ще даде runtime crash.

Файл: baradb_query.nim — whereNull proc
- [ ] Добавяне на "symbol": "IS" или "IS NOT" в JSON а

---

Тестове — какво липсва

Тестов файл	Съществува за	Липсва за BaraDB
test_open.nim	postgres, sqlite, mysql, mariadb, surreal, baradb	—
test_query.nim	postgres, sqlite, mysql, mariadb, surreal, baradb	—
test_prepared_statement.nim	postgres, sqlite, mysql, mariadb, surreal	baradb
test_schema.nim	postgres, sqlite, mysql, mariadb, surreal	baradb
test_create_schema.nim	postgres, sqlite, mysql, mariadb, surreal	baradb
test_pool_wait.nim	postgres	baradb
test_transaction.nim	postgres, sqlite, mysql, mariadb, surreal	baradb

---

Приоритети

#	Подобрение	Сложност	Ефект	Приоритет
1	Schema Builder column mapping	Средна	Без него migrations не работят	ВИСОК
2	INSERT RETURNING id	Ниска	Премахва race condition	ВИСОК
3	Prepared Statements	Висока	Security + performance	СРЕДЕН
4	Database URL support	Ниска	UX удобство	НИСЪК
5	Paginate / fastPaginate	Ниска	Feature parity	НИСЪК
6	whereNull fix	Ниска	Bug fix	ВИСОК
7	SQL quoting консистентност	Ниска	Потенциален runtime error	СРЕДЕН
8	Schema utils checksum	Ниска	Migration skip optimization	НИСЪК

---

Архитектура — файлова карта

src/allographer/
├── env.nim                          # DB_BARADB compile switch ✅
├── connection.nim                   # Import/export Baradb типове ✅
├── query_builder.nim                # Import/export baradb модули ✅
├── schema_builder.nim               # Import/export baradb schema ✅
│
├── query_builder/
│   ├── libs/baradb/
│   │   └── baradb_client.nim        # Wire protocol (706 реда) ✅
│   │
│   └── models/baradb/
│       ├── baradb_types.nim         # Типове (90 реда) ✅
│       ├── baradb_open.nim          # dbOpen + pool (52 реда) ✅
│       ├── baradb_query.nim         # Fluent API (386 реда) ✅
│       ├── baradb_exec.nim          # Execution (716 реда) ✅⚠️
│       ├── baradb_transaction.nim   # Transaction макро (42 реда) ✅
│       └── query/
│           ├── baradb_builder.nim   # SQL builder (237 реда) ✅
│           └── baradb_generator.nim # SQL generator (397 реда) ✅
│
├── schema_builder/
│   ├── queries/baradb/
│   │   ├── baradb_query_type.nim    # Типове (14 реда) ✅
│   │   ├── create_table.nim         # CREATE TABLE (16 реда) ⚠️ skeletal
│   │   ├── add_column.nim           # ADD COLUMN (8 реда) ⚠️ minimal
│   │   ├── change_column.nim        # ALTER COLUMN (8 реда) ⚠️ minimal
│   │   ├── drop_column.nim          # DROP COLUMN (8 реда) ✅
│   │   ├── drop_table.nim           # DROP TABLE (7 реда) ✅
│   │   ├── rename_column.nim        # RENAME COLUMN (8 реда) ⚠️ possible bug
│   │   ├── rename_table.nim         # RENAME TABLE (7 реда) ⚠️ possible bug
│   │   ├── reset_table.nim          # DELETE FROM (7 реда) ✅
│   │   ├── create_migration_table.nim (12 реда) ⚠️ quoting inconsistency
│   │   ├── schema_utils.nim         # shouldRun (12 реда) ⚠️ always true
│   │   └── sub/
│   │       ├── create_column_query.nim  # (24 реда) ❌ skeletal
│   │       ├── add_column_query.nim     # (8 реда) ⚠️ minimal
│   │       └── change_column_query.nim  # (6 реда) ⚠️ minimal
│   │
│   └── usecases/baradb/
│       ├── create.nim               # Table creation flow (24 реда) ✅
│       ├── alter.nim                # Alter flow (45 реда) ✅
│       ├── drop.nim                 # Drop flow (18 реда) ✅
│       ├── create_schema.nim        # Code gen from DB (60 реда) ✅
│       └── create_query_def.nim     # Factory (10 реда) ✅

tests/baradb/
├── config.nims                      # DB_BARADB=true ✅
├── connections.nim                  # Connection setup ✅
├── test_open.nim                    # Basic connection test ✅
├── test_query.nim                   # Integration tests ✅
├── test_prepared_statement.nim      # ❌ липсва
├── test_schema.nim                  # ❌ липсва
├── test_create_schema.nim           # ❌ липсва
├── test_pool_wait.nim               # ❌ липсва
└── test_transaction.nim             # ❌ липсва

Легенда: ✅ готово | ⚠️ partial/needs work | ❌ липсва | ✅⚠️ работи но с workaround

---

Краткосрочен план (следващи стъпки)

Седмица 1: Schema Builder + Bug fixes

1. sub/create_column_query.nim — пълен RdbTypeKind → SQL mapping (по PostgreSQL референция)
2. create_table.nim — да използва column query вместо raw тип
3. Fix whereNull bug в baradb_query.nim
4. Fix quoting inconsistency в create_migration_table.nim
5. Fix rename_column.nim / rename_table.nim ако changeTo не съществува

Седмица 2: INSERT RETURNING + Prepared Statements (част 1)

1. insertId — проучване дали BaraDB поддържа RETURNING, имплементация
2. prepare() / ensureStmt() — prepared statement кеш
3. preparedGet() / preparedExec() — изпълнение през mkQueryParams

Седмица 3: Тестове + Prepared Statements (част 2)

1. test_schema.nim — schema builder тестове
2. test_prepared_statement.nim — prepared statement тестове
3. test_transaction.nim — transaction тестове
4. test_pool_wait.nim — pool timeout тестове

Седмица 4: Polish

1. Database URL support
2. Paginate / fastPaginate
3. Schema utils checksum
4. Документация в documents/