ArchDB: modułowe schematy BD jako kod

Inżynieria schematów modułowych z ArchDB: szablony, pakiety i modelowanie deklaratywne

ArchDB umożliwia deklaratywne opisywanie struktury bazy danych w plikach .adb, integrując ją z repozytorium Git. Szablony (Template) eliminują duplikację pól audytu i identyfikacji, pakiety (Package) dekomponują monolit na niezależne moduły. Z modelu generowane są DDL, dokumentacja i diagramy. Podejście przyspiesza przegląd zmian i synchronizację z ORM.

// Core.adb - podstawowe szablony
Package com.example.ecommerce.Core

Template IdentifiableUuid {
  id uuid [pk, default: `gen_random_uuid()`]
}

Template Auditable {
  created_at timestamp [not_null, default: `now()`]
  created_by uuid [ref: > User.id, nullable]
  updated_at timestamp [default: `now()`]
  updated_by uuid [ref: > User.id, nullable]
  indexes {
    idx_created_at (created_at)
  }
}

Template BusinessEntity extends IdentifiableUuid, Auditable {
  version_no integer [default: 1]
  status varchar(50) [default: 'active']
}

Szablony do ponownego wykorzystania

Szablony są komponowane za pomocą extends, dziedzicząc pola i indeksy. BusinessEntity łączy identyfikację, audyt i wersjonowanie. Zastosowanie do tabeli User dodaje wszystkie pola automatycznie:

• UUID id z PK i domyślnym generatorem
• Pola created_at/updated_at z indeksami
• version_no do optymistycznej blokady

Sprawdzania (Checks) i unikalne indeksy konfigurowane są na poziomie tabeli:

Table User extends BusinessEntity {
  email varchar(255) [unique, not_null]
  password_hash text [not_null]
  checks {
    `char_length(password_hash) >= 8`
  }
}

Grupy logiczne (Group) poprawiają wizualizację w dokumentacji, przypisując kolor i opis.

Dekompozycja modułowa przez Package

Każdy plik .adb to osobny Package z importami. Product.adb importuje Core.adb, aby rozszerzyć BusinessEntity:

// Product.adb
Package com.example.ecommerce.Product
import "com.example.ecommerce.Core.adb" version 3.4.0

export Product as "com.example.ecommerce.Product" version 3.6.0

Table Product extends Core.BusinessEntity {
  sku varchar(50) [unique, not_null]
  price decimal(12, 2) [not_null]
  stock_quantity integer [default: 0]
  available_quantity integer [generated: `stock_quantity - reserved_quantity`]
  checks {
    `price >= cost_price`
    `reserved_quantity <= stock_quantity`
  }
}

Pola generowane (Generated) są obliczane na poziomie bazy danych. Relation opisuje relacje M:N:

Relation ProductCategory {
  Product.id <-> Category.id
}

Wersjonowanie eksportu (export ... version) zapewnia kompatybilność modułów.

| Zaleta | Opis |

|--------------|----------|

| Niezależność | Równoległy rozwój modułów |

| Wersjonowanie | Git + semver dla importów |

| Ponowne użycie | Szablony dystrybuowane przez biblioteki |

Zaawansowane encje: zamówienia i enum

Order.adb importuje Core i Product, dodając typy domenowe:

// Order.adb
import "com.example.ecommerce.Core.adb" version 3.4.0
import "com.example.ecommerce.Product.adb" version 3.6.0

Enum OrderStatus {
  pending [note: "Oczekuje na płatność"]
  paid
  shipped
  cancelled
}

Table Order extends Core.BusinessEntity {
  user_id uuid [ref: > Core.User.id]
  status OrderStatus [default: 'pending']
  total_amount decimal(12, 2) [not_null]
}

Enum jest integrowany jako typ pola. Kaskadowe usuwanie (on_delete: cascade) na kluczu obcym.

Co jest ważne

• Deklaratywność: opisuje się pożądany stan, generatory tworzą DDL i migracje.
• Modułowość: Package + import/export dla niezależnego rozwoju i CI/CD.
• Szablony: extends komponuje pola audytu, soft-delete, logikę biznesową bez kopiowania.
• Walidacja: checks na poziomie schematu, pola generowane dla obliczeń.
• Dokumentacja: note, Group, Metadata generują diagramy i README.

Praktyczne techniki wdrożenia

• Utwórz podstawowy Core.adb z szablonami Identifiable, Auditable, SoftDeletable.
• Podziel monolit na Package według domen: User, Product, Order.
• Skonfiguruj Git hooks do walidacji schematów przed commitem.
• Zintegruj z CI: generacja DDL, testy schematu, aktualizacja dokumentacji.
• Dla ORM: skrypty generowania encji z .adb.

Metadata i Project określają kontekst: database: "postgresql", version, author.

— Editorial Team