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` — всички операции работят, `insertId` използва `RETURNING` |
| 4. Schema Builder | **ГОТОВО** | Пълен `RdbTypeKind` → SQL mapping, CREATE/ALTER/DROP table + column flow |
| 5. Тестове и документация | **ГОТОВО** | `test_migration.nim` (8), `test_prepared_statement.nim` (8), `documents/migration.md` |

---

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

### 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 — ✅ ИЗПРАВЕНО

**Статус:** `insertId` вече използва `INSERT ... RETURNING \`id\`` вместо `SELECT MAX`. BaraDB поддържа `RETURNING` — проверено в lexer/parser.

---

### 3. Schema Builder — Column Type Mapping ✅ ИЗПРАВЕНО

**Статус:** Пълен `RdbTypeKind` → SQL mapping е имплементиран в `create_column_query.nim` (~350 реда):
- `rdbIncrements` → `SERIAL PRIMARY KEY`
- `rdbInteger` → `INTEGER` (+ auto-increment → `SERIAL`)
- `rdbBigInteger` → `BIGINT` (+ auto-increment → `BIGSERIAL`)
- `rdbBoolean` → `BOOLEAN`
- `rdbString(n)` → `VARCHAR(n)` (default 255)
- `rdbText` → `TEXT`
- `rdbFloat` → `REAL`
- `rdbDouble` → `DOUBLE PRECISION`
- `rdbDecimal(p,s)` → `DECIMAL(p,s)`
- `rdbDate` → `DATE`
- `rdbDateTime` / `rdbTimestamp` → `TIMESTAMP`
- `rdbTime` → `TIME`
- `rdbBinary` → `BYTEA`
- `rdbUuid` → `UUID`
- `rdbJson` → `JSON`
- `rdbEnumField` → `VARCHAR(255)`
- `rdbForeign` → `INTEGER` + `REFERENCES ... ON DELETE ...`
- `rdbStrForeign` → `VARCHAR(255)` + `REFERENCES ... ON DELETE ...`
- `rdbTimestamps` → `created_at` + `updated_at`
- `rdbSoftDelete` → `deleted_at`

`create_table.nim`, `add_column.nim`, `change_column.nim` вече използват `createColumnString`.

---

### 4. SQL Quoting Inconsistency ✅ ИЗПРАВЕНО

**Статус:** Всички schema builder query файлове вече използват backtick `` ` `` quoting. `create_migration_table.nim` беше поправен.

---

### 5. rename_column / rename_table bug ✅ ИЗПРАВЕНО

**Статус:** `changeTo` → `previousName` в `rename_column.nim` и `rename_table.nim`.

---

### 6. whereNull Bug ✅ ИЗПРАВЕНО

**Статус:** `whereNull` вече добавя `"symbol": "is"` в JSON обекта.

---

### 7. 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`
```

---

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

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

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

---

### 9. Schema utils checksum

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

---

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

| Тестов файл | Съществува за | Липсва за 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 | rename_column / rename_table bug | Ниска | Bug fix | ✅ ГОТОВО |
| 9 | Schema utils checksum | Ниска | Migration skip optimization | ✅ ГОТОВО |
| 10 | Migration → BaraQL native | Висока | Унификация клиент-сървър | ✅ ГОТОВО |

---

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

```
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 ✅
│   │   ├── add_column.nim           # ADD COLUMN ✅
│   │   ├── change_column.nim        # ALTER COLUMN ✅
│   │   ├── drop_column.nim          # DROP COLUMN (8 реда) ✅
│   │   ├── drop_table.nim           # DROP TABLE (7 реда) ✅
│   │   ├── rename_column.nim        # RENAME COLUMN ✅
│   │   ├── rename_table.nim         # RENAME TABLE ✅
│   │   ├── reset_table.nim          # DELETE FROM (7 реда) ✅
│   │   ├── create_migration_table.nim ✅
│   │   ├── schema_utils.nim         # shouldRun (12 реда) ⚠️ always true
│   │   └── sub/
│   │       ├── create_column_query.nim  # ✅ пълен mapping
│   │       ├── add_column_query.nim     # ✅
│   │       └── change_column_query.nim  # ✅
│   │
│   └── 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~~ ✅
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 — ИЗПЪЛНЕНО
1. ~~`insertId` — проучване дали BaraDB поддържа RETURNING, имплементация~~ ✅

### ✅ Седмица 3: Prepared Statements + Тестове — ИЗПЪЛНЕНО (2026-05-21)
1. ~~`prepare()` / `ensureStmt()` — prepared statement кеш~~ ✅
2. ~~`preparedGet()` / `preparedExec()` — изпълнение през `mkQueryParams`~~ ✅
3. `test_prepared_statement.nim` — prepared statement тестове ⬜
4. `test_schema.nim` — schema builder тестове ⬜
5. `test_transaction.nim` — transaction тестове ⬜
6. `test_pool_wait.nim` — pool timeout тестове ⬜

### ✅ Седмица 4: Polish — ИЗПЪЛНЕНО (2026-05-21)
1. ~~Database URL support~~ ✅ (`baradb://user:pass@host:port/db`)
2. ~~Paginate / fastPaginate~~ ✅
3. ~~Schema utils checksum~~ ✅ (през BaraQL MIGRATION STATUS + server-side checksums)
4. Документация в `documents/` ⬜