feat: migrate system + cross-DB engine + IMPORT/EXPORT syntax -- 22 files, client+server+docs

clients/nim-allographer/PLAN_MIGRATION.md

@@ -0,0 +1,142 @@
+# План: Миграционна система + Data Migration Engine
+
+## Архитектурен проблем
+
+BaraDB сървърът има пълна BaraQL миграционна система:
+```sql
+CREATE MIGRATION name { UP: ...; DOWN: ...; }
+APPLY MIGRATION name
+MIGRATION STATUS
+MIGRATION UP [N]
+MIGRATION DOWN [N]
+MIGRATION DRY RUN name
+```
+С checksums (SHA-256), locks, rollback, dry-run. Но nim-allographer клиентът
+**не я използва** — вместо това праща raw SQL и поддържа собствена
+`_allographer_migrations` таблица.
+
+## Решение
+
+Унифициране: клиентът да изпраща BaraQL миграционни команди към сървъра,
+вместо да емулира миграции с raw SQL. Сървърът вече знае как да валидира,
+lock-ва, и track-ва миграциите.
+
+---
+
+## Фаза 1: Свързване на клиента със сървърната BaraQL миграционна система [В ПРОГРЕС]
+
+### 1.1 `baradb_client.nim` — нови процедури за миграции
+- `createMigration(name, upBody, downBody)` → `CREATE MIGRATION name { UP: ...; DOWN: ...; }`
+- `applyMigration(name)` → `APPLY MIGRATION name`
+- `migrateUp(count)` → `MIGRATION UP [N]`
+- `migrateDown(count)` → `MIGRATION DOWN [N]`
+- `migrationStatus()` → `MIGRATION STATUS` (връща QueryResult)
+- `migrationDryRun(name)` → `MIGRATION DRY RUN name`
+
+Имплементация: конструират BaraQL стринг и го пращат през съществуващия `query()`.
+
+### 1.2 `baradb_exec.nim` — high-level migration API + prepared statements
+- `createMigration(rdb, name, upBody, downBody)` — convenience wrapper
+- `applyMigration(rdb, name)` — с връщане на резултат
+- `migrateUp(rdb, count=0)` — batch apply
+- `migrateDown(rdb, count=1)` — rollback
+- `migrationStatus(rdb)` → `seq[JsonNode]`
+- **Prepared Statements:** `prepare()`, `ensureStmt()`, `preparedGet()`, `preparedExec()`, `withConn()`
+
+### 1.3 `schema_utils.nim` — checksum-based shouldRun
+- `shouldRun()` → изпраща `MIGRATION STATUS` и проверява дали миграцията е applied
+- `execThenSaveHistory()` → използва `CREATE MIGRATION` + `MIGRATION UP`
+
+### 1.4 `create_migration_table.nim` — опростяване
+- Сървърът поддържа migration state в LSM-Tree (`_schema:migration:*`)
+- Клиентската `_allographer_migrations` таблица вече не е нужна за BaraDB
+
+---
+
+## Фаза 2: Prepared Statements (от стар план, Седмица 3)
+
+### 2.1 `baradb_exec.nim` — prepared statement API
+- `prepare(sql)` → `BaradbPreparedStatement`
+- `ensureStmt(conn, sql, nArgs)` → кеширане в preparedCache
+- `preparedGet(stmt, args)` → използва mkQueryParams
+- `preparedExec(stmt, args)` → execute през mkQueryParams
+- `withConn(pool, callback)` → context-based connection
+- `flushStmt(stmt)`, `clearStmtCache()`
+
+### 2.2 Сигурност
+- Премахване на client-side string interpolation за параметризирани заявки
+- Всички параметризирани заявки да минават през `mkQueryParams`
+
+---
+
+## Фаза 3: Cross-DB Migration Engine — нов модул `migrate_data.nim`
+
+### 3.1 Schema extraction от source база
+- `extractSchema(rdb)` → `TableDef[]` за PostgreSQL/MySQL/SQLite/MariaDB/SurrealDB
+- Четене от `information_schema` (или еквивалент)
+
+### 3.2 Type mapping
+- Source тип → BaraDB тип
+- Мапване на constraints (PK, FK, UNIQUE, NOT NULL, DEFAULT)
+
+### 3.3 DDL генератор
+- Генерира `CREATE MIGRATION` скриптове с UP/DOWN за всяка таблица
+- Запазва foreign key зависимости (order на таблиците)
+
+### 3.4 Batch data transfer
+- `transferTable(source, target, tableName, batchSize=1000)`
+- Четене на batch от source → bulk insert в BaraDB
+- Progress reporting, resume от последния успешен batch
+
+### 3.5 CLI команда
+```
+allographer migrate \
+  --from postgres://user:pass@host:5432/db \
+  --to baradb://user:pass@host:9876/db \
+  [--tables users,orders,products] \
+  [--batch-size 5000] \
+  [--dry-run]
+```
+
+---
+
+## Фаза 4: BaraDB сървър — подобрения за миграция
+
+### 4.1 `IMPORT FROM` синтаксис в BaraQL
+### 4.2 `EXPORT TO` синтаксис в BaraQL
+### 4.3 Bulk Insert оптимизация
+
+---
+
+## Фаза 5: Database URL + Paginate + Polish (от стар план)
+
+### 5.1 Database URL support — `baradb://user:pass@host:port/db`
+### 5.2 Paginate / fastPaginate
+
+---
+
+## Фаза 6: Тестове и документация
+
+### 6.1 Липсващи тестове за BaraDB (от стар план)
+- `test_prepared_statement.nim`, `test_schema.nim`, `test_create_schema.nim`
+- `test_pool_wait.nim`, `test_transaction.nim`
+
+### 6.2 Нови тестове за миграция
+- `test_migration_create.nim`, `test_migration_up_down.nim`
+- `test_cross_db_migration.nim`
+
+### 6.3 Документация
+- `documents/migration.md`
+
+---
+
+## Прогрес
+
+| Фаза | Статус | Дата |
+|------|--------|------|
+| 1. Унификация | ✅ ГОТОВО | 2026-05-21 |
+| 2. Prepared Statements | ✅ ГОТОВО | 2026-05-21 |
+| 3. Cross-DB Engine | ✅ ГОТОВО | 2026-05-21 |
+| 4. IMPORT/EXPORT | ✅ ГОТОВО | 2026-05-21 |
+| 5. DB URL + Paginate | ✅ ГОТОВО | 2026-05-21 |
+| 6. Тестове + Докум. | ✅ ГОТОВО | 2026-05-21 |