Core/Database/Migrations — master ve kiraci şema geçişleri

Doğrulanan kod tabanı: 1d89c431 (dal feat/fw-license-master) · Tarih: 2026-10-05 · Yayın: 0.9.7 = bu commit + sonrası; belge yalnız doğrulama anındaki kodu anlatır
Kaynak klasör: Core/Database/Migrations/ — 3 *.php + 1 *.sql.
Envanter: 3 php dosyasının 3'ü anlatıldı; 111-z_user_tokens.sql aşağıda not edilmiştir.

1. Ne işe yarar, kim kullanır

Master veritabanında merkezi lisans/uygulama tablolarını kuran migration
(Master/) ve kiraci (proje) veritabanlarında project_key kolonu ile
benzersiz indeks ekleyen/geri alan migration (Tenant/). İkisi de
idempotent ve geri alınabilir çalışır; Tenant sınıfı plan/uygula/geri al
üçlüsünü ayırır.

Kimler çağırır: CLI migration komutları (rbn migrate:*, rbn tenant:plan,
rbn tenant:apply, rbn tenant:revert) ve kurulum sihirbazı.

2. Dosya envanteri

Dosya	Görev	Önemli public yöntemler
`Master/CreateLicenceAndApplicationTables.php`	`applications` ve `licences` tablolarını oluşturur, mevcut proje lisanslarını merkezi tabloya kopyalar.	`const NAME`, `up(): void`, `down(): void`, `copyProjectLicences(): void`, `applicationsDdl(): string`, `licencesDdl(): string` (protected)
`Master/NormalizeProjectVersions.php`	`projects.version` değerlerini tek biçime indirger; yedek tablo yazar ve değişen satır sayısını raporlar.	`const …` (`BACKUP_TABLE`), `up(): void`, `down(): void`, `static rapor(): array`
`Tenant/TenantKeyMigration.php`	Kiraci kolonu (`project_key`) + benzersizlik indeksini ölçer, ekler, geri alır. `final`.	`__construct(private readonly string $column = ProjectDbData::TENANT_COLUMN, private readonly string $columnType = ProjectDbData::TENANT_COLUMN_TYPE)`, `columnDefinition(): string`, `plan(PDO $pdo,string $database,array $tables): array`, `apply(PDO $pdo,string $database,array $tables,bool $dryRun=false): array`, `revert(PDO $pdo,string $database,array $tables): array`, `tableExists/columnExists/columnState/indexExists/indexNames/uniqueIndexMap/hasUniqueIndex/duplicateGroupCount`: (…), `applyUnique(...)`, `revertUnique(...)`, `uniqueIndexName(string $table,string $slugColumn): string`, `indexName(string $table): string`

SQL dosyası: 111-z_user_tokens.sql — z_user_tokens tablosunun DDL'i
(her proje veritabanına ayrı uygulanır). PHP sınıfı yoktur; migration
motoru .sql dosyalarını sırayla çalıştırır.

Kapsama: 3/3 php.

3. Akış

rbn tenant:plan  → TenantKeyMigration::plan($pdo,$db,TENANT_TABLES)
   └─ her tablo için: tableExists() + columnState()   (yalnız SELECT)   :91-105

rbn tenant:apply → apply($pdo,$db,$tables, dryRun)
   ├─ tablo yoksa skipped[] (uygulama sessizce atlanır)  :123-126
   ├─ kolon yoksa  → ALTER TABLE … ADD COLUMN columnDefinition()  :130-135
   ├─ kolon var    → duplicateGroupCount() ile yinelenen kayıt ölçülür
   └─ applyUnique() → UNIQUE INDEX ekler (dryRun'da yalnız SQL üretilir)  :369-…

rbn tenant:revert → revert($pdo,$db,$tables)
   ├─ kolonu kaldırır
   └─ revertUnique() → benzersiz indeksleri kaldırır

CreateLicenceAndApplicationTables::up() sırası:
applications DDL → licences DDL → copyProjectLicences()
(CreateLicenceAndApplicationTables.php:45).

4. Yapılandırma

Sabit	Yer	Not
`NAME`	`CreateLicenceAndApplicationTables.php:43`	`2026_10_02_000001_create_licence_and_application_tables`
`TENANT_COLUMN` / `TENANT_COLUMN_TYPE` / `TENANT_INDEX_PREFIX`	`ProjectDbData`	`TenantKeyMigration` varsayılan olarak bunları kullanır (`TenantKeyMigration.php:68`)
`TENANT_TABLES`	`ProjectDbData`	`tenant:plan/apply` yalnız bu listedeki tabloları işler (bkz. ../../acik-sorular.md §2.2)

5. Tuzaklar ve kurallar

down() yalnız kendi yarattığı tabloyu düşürür. projects tablosuna
dokunulmaz (CreateLicenceAndApplicationTables.php:52).
Anahtar tahmini yapılmaz. Proje lisansları LIFETIME + active +
süresiz olarak kopyalanır; boş/NULL anahtar atlanır (:62-82).
dryRun yalnız SQL üretir, hiçbir şey çalıştırmaz
(TenantKeyMigration.php:113).
Tablo adı güvenli karakterlere indirgenir (guvenliTabloAdi(),
RbnHeartbeatsModel.php:145 benzeri desen) ve ref() ile
kırpılır — SQL enjeksiyonu yüzeyi kapatılmıştır.
asw_* tablolarına dokunulmaz (gece görevi kuralı; migration da bu
tabloları TENANT_TABLES listesinden almaz).

6. Örnek (gerçek koddan)

// Plan çıktısı biçimi (TenantKeyMigration.php:104)
['schema' => 'db_adi', 'items' => [
    ['table' => 'z_users', 'exists' => true,  'column' => ['name' => 'project_key', 'exists' => true]],
]];

7. İlgili belgeler

../README.md, Models.md
../../kavramlar/03-veritabani-ve-kiracilik.md — migration ve tenant sözleşmesi
../System/Config.md — ProjectDbData::TENANT_* sabitleri
../../acik-sorular.md §2.2