Baradb/docs/bg/migration.md

Миграции и Импорт/Експорт на Данни

BaraDB има вградена миграционна система чрез BaraQL. Миграциите се управляват изцяло от сървъра — checksums, locking, rollback и проследяване на статуса. Клиентът изпраща BaraQL команди и не поддържа собствена миграционна таблица.

BaraQL Синтаксис за Миграции

-- Създаване на миграция с UP и DOWN скриптове
CREATE MIGRATION add_users_table {
  UP: CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    email VARCHAR(255) UNIQUE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
  );
  DOWN: DROP TABLE IF EXISTS users;
}

-- Прилагане на конкретна миграция
APPLY MIGRATION add_users_table

-- Прилагане на всички неприложени миграции
MIGRATION UP

-- Прилагане на следващите N миграции
MIGRATION UP 3

-- Отмяна на последната миграция
MIGRATION DOWN

-- Отмяна на последните N миграции
MIGRATION DOWN 2

-- Преглед на статуса
MIGRATION STATUS

-- Dry run (валидация без изпълнение)
MIGRATION DRY RUN add_users_table

Заключване при Миграция

BaraDB заключва глобално преди прилагане на миграция, което предотвратява конкурентно изпълнение и осигурява:

• Само една миграция се изпълнява в даден момент
• Checksums се проверяват преди изпълнение
• Неуспешните миграции могат да се върнат безопасно
• MIGRATION STATUS показва точното състояние на всяка миграция

Checksums

Тялото на всяка миграция се хешира с SHA-256. Сървърът съхранява checksum при създаване и го проверява преди прилагане.

CREATE MIGRATION add_users → checksum: a3f2b8c1...
APPLY MIGRATION add_users → проверява checksum → изпълнява

Връщане (Rollback)

Миграциите с DOWN скриптове поддържат връщане:

CREATE MIGRATION add_column {
  UP: ALTER TABLE users ADD COLUMN phone VARCHAR(20);
  DOWN: ALTER TABLE users DROP COLUMN phone;
}

MIGRATION DOWN изпълнява DOWN скрипта и маркира миграцията като върната.

Dry Run

Валидирайте миграция преди прилагане:

MIGRATION DRY RUN add_users_table
-- Изход:
-- DRY RUN add_users_table:
--   Statements: 1
--   [1] nkCreateTable
--   DOWN script: yes
--   Checksum: a3f2b8c1d4e5f6a7b8c9d0e1f2a3b4c5

---

IMPORT FROM / EXPORT TO

BaraDB поддържа импорт и експорт на данни директно чрез BaraQL.

IMPORT FROM

-- Импорт от CSV
IMPORT FROM '/data/users.csv' INTO users
  FORMAT CSV
  DELIMITER ','
  HEADER true
  BATCH 1000

-- Импорт от JSON масив
IMPORT FROM '/data/users.json' INTO users
  FORMAT JSON

-- Импорт от NDJSON
IMPORT FROM '/data/users.ndjson' INTO users
  FORMAT NDJSON

Опции:

Опция	Стойности	По подр.	Описание
FORMAT	CSV, JSON, NDJSON	CSV	Формат на входния файл
DELIMITER	произволен знак	,	Разделител за CSV
HEADER	true/false	true	Първият ред на CSV е заглавен
BATCH	цяло число	1000	Редове на партида

EXPORT TO

-- Експорт към CSV
EXPORT TO '/backup/users.csv' FROM users
  FORMAT CSV
  DELIMITER ','
  HEADER true

-- Експорт към JSON
EXPORT TO '/backup/users.json' FROM users
  FORMAT JSON

-- Експорт към NDJSON
EXPORT TO '/backup/users.ndjson' FROM users
  FORMAT NDJSON

---

Миграция между Бази Данни

Nim клиентът на BaraDB (nim-allographer) включва engine за миграция между различни бази данни. Мигрирайте данни от PostgreSQL, MySQL, MariaDB, SQLite или SurrealDB директно към BaraDB.

Поддържани Източници

База Данни	Извличане на Схема	Статус
PostgreSQL	information_schema	✅
MySQL	information_schema	✅
MariaDB	information_schema	✅
SQLite	sqlite_master + PRAGMA	✅
SurrealDB	INFO FOR DB / INFO FOR TABLE	✅

Nim API

import allographer/migrate_data

# Свързване към източник и цел
let pg = dbOpen(PostgreSQL, "sourcedb", "user", "pass", "localhost", 5432)
let bdb = dbOpen(Baradb, "targetdb", "admin", "", "127.0.0.1", 9472)

# Мигриране на всички таблици
let report = waitFor migrate(pg, bdb, batchSize = 5000)
echo report
# Migration: PostgreSQL → BaraDB
#   Tables: 12/12
#   Rows:   45230
#   Time:   3.2s

# Мигриране на конкретни таблици
let report = waitFor migrate(pg, bdb,
  tables = @["users", "orders", "products"])

Съответствие на Типове

Миграционният engine автоматично мапва типовете:

PostgreSQL	MySQL	SQLite	BaraDB
SERIAL	INT AUTO_INCREMENT	INTEGER PK	SERIAL
VARCHAR(n)	VARCHAR(n)	TEXT	VARCHAR(n)
TEXT	TEXT	TEXT	TEXT
BOOLEAN	TINYINT(1)	INTEGER	BOOLEAN
JSONB	JSON	TEXT	JSON
TIMESTAMP	DATETIME	TEXT	TIMESTAMP
UUID	CHAR(36)	TEXT	UUID

Пълна карта: 50+ поддържани типа.

---

Nim allographer API

Управление на Миграции

import allographer/query_builder/models/baradb/baradb_exec

# Създаване
let qr = waitFor rdb.createMigration("add_products",
  "CREATE TABLE products (id SERIAL PRIMARY KEY, name VARCHAR(255))",
  "DROP TABLE IF EXISTS products")

# Прилагане
let qr = waitFor rdb.applyMigration("add_products")
let qr = waitFor rdb.migrateUp()  # всички неприложени
let qr = waitFor rdb.migrateDown(1)  # връщане

# Статус
let status = waitFor rdb.migrationStatus()
if waitFor rdb.isMigrationApplied("add_products"):
  echo "Вече е приложена"

Prepared Statements

let stmt = waitFor rdb.prepare(
  "SELECT * FROM users WHERE age > ? AND status = ?", nArgs = 2)

let results = waitFor stmt.preparedGet(@[
  WireValue(kind: fkInt32, int32Val: 18),
  WireValue(kind: fkString, strVal: "active")
])

stmt.flushStmt()
rdb.clearStmtCache()

Pagination

# Offset-базирана
let page = waitFor rdb.table("users").paginate(page = 1, perPage = 20)

# Cursor-базирана (по-бърза за големи таблици)
let batch = waitFor rdb.table("users")
  .fastPaginate("id", perPage = 100, afterId = "42")

---

Най-добри Практики

1. Винаги включвайте DOWN скриптове — позволява безопасно връщане
2. Първо dry run — валидирайте преди прилагане в production
3. Партиден импорт — използвайте BATCH 1000 за CSV импорт
4. Експортирайте преди миграция — backup с EXPORT TO
5. Проверка след миграция — MIGRATION STATUS
6. Първо таблици без foreign keys — после тези с foreign keys