Önceki yazıda PostgreSQL 18'i Electron uygulamasının içine nasıl gömdüğümü anlatmıştım. O yazıyı yazdığımda projede 19 migration vardı. Bugün _journal.json içinde 51 kayıt var. Bu yazı, o 32 yeni migration'ın kullanıcının makinesine nasıl ulaştığını ve orada nasıl çalıştığını anlatıyor.
Sunucuda migration çalıştırmak kolay, çünkü başında biri duruyor. Masaüstünde ise kullanıcıdan db:migrate çalıştırmasını bekleyemem. Şema, uygulama güncellendiği anda kendiliğinden güncellenmek zorunda.
Migration'lar nereden geliyor
Şemanın kaynağı TypeScript. drizzle-kit generate fark çıkarıyor, SQL dosyasını ve bir anlık görüntüyü (meta/NNNN_snapshot.json) üretiyor. Yapılandırma kısa:
export default defineConfig({
schema: './src/db/schema/index.ts',
out: './src/db/migrations',
dialect: 'postgresql',
casing: 'snake_case',
strict: true,
})
Klasörde 51 SQL dosyası ve 51 günlük kaydı var, ama anlık görüntü sayısı 49. Aradaki iki dosyayı elle yazdım: 0009_cihaz_onayi_geri_doldurma ve 0013_gecis_yetkileri. İkisi de şemayı değiştirmiyor, veriyi düzeltiyor. drizzle-kit bu tür işi üretemiyor, çünkü şemada değişen bir şey yok:
-- Cihaz onayı devreye girmeden ÖNCE açılmış oturumlar onaylı sayılır.
UPDATE "sessions"
SET "onayli_at" = "created_at"
WHERE "onayli_at" IS NULL AND "iptal_at" IS NULL;
Bu satır olmasaydı, ayar ilk açıldığında yöneticinin kendisi de dahil herkes kilitlenecekti. Elle yazdığım migration'ların bir yan etkisi oldu: günlükte iki kayıt aynı idx: 12 değerini taşıyor ve klasörde iki tane 0013_ önekli dosya var. Drizzle idx alanına bakmadığı için bu bir hataya yol açmıyor. Ama dosya adlarına bakan biri şaşırabilir.
En büyük migration 0029 oldu. Kod adlarını Türkçeden İngilizceye çevirirken 1065 satırlık bir dosya çıktı: tablo, sütun, indeks ve kısıtlar RENAME ile değişiyor, DROP/ADD yok. Commit mesajında yazdığım gibi, eski ve yeni anlık görüntülerden üretildi ve geliştirme veritabanında gerçek veriyle denendi.
Paketin içine dosya olarak girmek
Sunucu kodu esbuild ile tek bir index.mjs dosyasına derleniyor. Migration'lar bu pakete giremez, çünkü çalışma anında dosya olarak okunuyorlar. Derleme betiği onları paketin yanına kopyalıyor:
export async function copyMigrations(target) {
await rm(target, { recursive: true, force: true })
await cp(resolve(ROOT, 'apps/api/src/db/migrations'), target, { recursive: true })
}
Hedef klasör out-server/migrations. electron-builder bu klasörü asarUnpack ile arşivin dışına çıkarıyor. Ana süreç yolu process.resourcesPath/app.asar.unpacked/out-server/migrations olarak kuruyor ve sunucuya parametre olarak veriyor. Bunun bir sebebi var: kod tek dosyaya derlenince import.meta.url artık dist/db/ klasörünü değil, paketin kendi klasörünü gösteriyor. Kaynak ağacına göre bir tahmin yürütmek bu yüzden işe yaramıyor.
Burada iki sessiz arıza yaşadım:
- Sunucu paketi önce
out/altındaydı.electron-vite buildbu klasörü temizlerken migration'ları da siliyordu.utilityProcess.forkolmayan bir dosyada hata fırlatmıyor, uygulama açılış ekranında sebepsiz takılıp kalıyordu. Çıktıyı temizlenen klasörün dışına aldım. - Ana süreç artık fork etmeden önce migration klasörünün var olup olmadığına bakıyor. Klasör yoksa açılış ekranında
migrationsMissinghatası çıkıyor. Bilinmeyen bir sebeple beklemek, açık bir hatadan daha kötü.
Açılışta sıra
Gömülü sunucunun launch() fonksiyonu her açılışta aynı sırayı izliyor:
if ((await pendingMigrations(options.migrationsDir)) > 0 && (await hasData())) {
notify(i18n.t('desktop:startup.stage.preUpdateBackup'))
try {
const b = await takeBackup()
console.log(`Güncelleme öncesi yedek alındı: ${b.file}`)
} catch (e) {
console.error('Güncelleme öncesi yedek ALINAMADI:', e)
}
}
await applyMigrations(options.migrationsDir)
if (!(await isSeeded())) await seed({ admin: false })
Güncelleme öncesi yedek ticari hazırlık listesinde "K3: Güncellemede göç öncesi otomatik yedek yok" diye duruyordu. Artık bekleyen bir migration varsa ve veritabanında kullanıcı kaydı varsa, migration'lardan önce pg_dump ile şifreli bir yedek alınıyor. Yeni kurulumda bu adım atlanıyor. Bir tercihi de bilerek yaptım: yedek alınamazsa açılış durmuyor, yalnızca günlüğe hata düşüyor. Gerekçem şu: günlük yedekler zaten var, uygulamanın hiç açılmaması ise kullanıcının verisine hiç ulaşamaması demek.
"Bekleyen migration var mı" sorusunu ben soruyorum, Drizzle değil:
const journal = JSON.parse(await readFile(join(dir, 'meta', '_journal.json'), 'utf8'))
const rows = await publicDb.execute(sql`select count(*)::int as n from drizzle.__drizzle_migrations`)
return Math.max(0, journal.entries.length - (rows[0]?.n ?? 0))
Tablo yoksa (yeni kurulumda) hepsi bekliyor sayılıyor.
Drizzle'ın migrator'ı gerçekte ne yapıyor
Kullandığım drizzle-orm 0.45.3'ün PostgreSQL migrator'ını okuyunca birkaç şeyi kendi varsaydığımdan farklı buldum:
const last = await session.all(sql`select id, hash, created_at from drizzle.__drizzle_migrations
order by created_at desc limit 1`)
await session.transaction(async (tx) => {
for (const m of migrations) {
if (!last || Number(last.created_at) < m.folderMillis) { /* uygula, kaydet */ }
}
})
| Varsaydığım | Gerçekte |
|---|---|
| Dosyanın hash'i kontrol ediliyor | Hash hesaplanıp tabloya yazılıyor ama hiçbir yerde karşılaştırılmıyor |
| Uygulanmamış olan her dosya çalışır | Yalnız günlükteki when değeri, son uygulanan kaydın created_at değerinden büyük olanlar çalışır |
| Her migration kendi transaction'ında çalışır | Bekleyen migration'ların hepsi tek transaction'da çalışır, biri düşerse hepsi geri alınır |
| Eşzamanlı çalışmaya karşı kilit var | Migrator kilit almıyor |
Pratikte bunun anlamı şu: uygulanmış bir migration dosyasını değiştirirsem kimse fark etmez, kurulu makinelerde eski hâli kalır. Projede bunu engelleyen bir lint kuralı ya da test yok. eslint-rules/ klasöründe yalnızca sabit metinleri yakalayan bir kural var. Migration klasörü ESLint'te // Drizzle üretiyor; elle düzenlenmiyor. yorumuyla yok sayılıyor. Kural bugün bir alışkanlıktan ibaret, araçla zorlanmıyor.
Bir de benim sayıma dayalı kontrolüm ile Drizzle'ın zaman damgasına dayalı kararı aynı şeyi ölçmüyor. Günlüğe, son uygulanandan daha eski bir when değeriyle bir kayıt girerse, Drizzle onu sessizce atlar. Benim sayacım ise her açılışta "1 bekliyor" der. Bu henüz başıma gelmedi, ama iki kontrolün ayrıştığını bilmek gerekiyor.
Kilit ve eşzamanlılık
Migration'ların etrafında advisory lock yok. Masaüstünde buna şimdilik ihtiyaç duymamamın sebebi Electron'un tek örnek kilidi:
// Tek örnek kilidi — iki kopya aynı yerel veriye yazmasın.
if (!app.requestSingleInstanceLock()) app.quit()
Gömülü sunucuyu yalnızca bu tek süreç başlatıyor ve migration'ları da yalnızca o uyguluyor. Projede pg_try_advisory_lock kullanan bir withLeaderLock var, ama o bakım işleri için. Migration yolunda kullanılmıyor. Bulut tarafında aynı soruyu GitHub Actions'taki concurrency: bulut-dagitim ve cancel-in-progress: false ayarları karşılıyor. Firma şemalarına migration'ları sırayla bir CLI komutu uyguluyor ve ilk hatada durup hangi firmada kaldığını raporluyor.
Hata olursa, sürüm geri dönerse
Bir migration düşerse Drizzle'ın tek transaction'ı her şeyi geri alıyor. launch() istisna fırlatıyor, yardımcı süreç PostgreSQL'i durduruyor ve ana sürece error mesajı gönderiyor. Kullanıcı açılış ekranında hata mesajını görüyor. Uygulama yarım bir şemayla açılmıyor, hiç açılmıyor. Dönülecek nokta, az önce alınan güncelleme öncesi yedek. Geri yükleme de kendi içinde applyMigrations() çağırıyor, böylece eski bir yedek açıldığında şema yine güncelleniyor.
Downgrade için ise elimde bir mekanizma yok. Kullanıcı eski bir sürümü kurarsa günlük kısa kalıyor. Benim sayacım Math.max(0, ...) yüzünden 0 döndürüyor. Drizzle de son kaydın zaman damgası daha yeni olduğu için hiçbir şey yapmıyor. Eski kod yeni şemayla sessizce açılıyor. Bunu yazarken fark ettim, listeye ekliyorum.
Yaşadığım tuzaklar
| Tuzak | Belirti | Çözüm |
|---|---|---|
electron-vite build out/ klasörünü temizliyor |
Migration'lar ve sunucu paketi siliniyor, açılış ekranı sonsuza kadar dönüyor | Çıktı out-server/ klasörüne alındı, fork öncesinde existsSync kontrolü eklendi |
Fork edilen betik app.asar içinde |
Fork sessizce ölü doğuyor, existsSync yalan söylüyor (Electron fs'i asar için yamalıyor) |
asarUnpack: out-server/**/*, 60 sn'lik zaman aşımı |
migrate.ts içinde "doğrudan mı çalıştırıldım" kontrolü |
Tek dosyalık pakette import.meta.url ile argv[1] eşleşiyor, migration açılışta ikinci kez sabit bir göreli yolla tetikleniyor |
Komut satırı girişi migrate-cli.ts dosyasına ayrıldı, kütüphane yan etkisiz |
prettier --write alt klasörden çalıştırıldı |
45 anlık görüntü dosyası yeniden biçimlendirildi | Ayrı bir commit ile geri alındı, içerik JSON karşılaştırmasıyla doğrulandı |
Tek dosyalık derlemede import.meta.url |
Migration yolu dist/db/ yerine dist/ oluyor |
Klasör paketin yanına kopyalanıyor, masaüstünde yol dışarıdan veriliyor |
Testler
Testler Docker kullanmıyor. Uygulamanın kendi PostgreSQL binary'leri geçici bir kümede açılıyor, satis_test veritabanı her koşuda silinip yeniden kuruluyor, ardından migration'ların hepsi ve tohum veri uygulanıyor. Yani her test koşusu, 51 migration'ın boş bir veritabanında baştan sona çalıştığını da kanıtlıyor. CI'da ayrı bir db:migrate adımı yok, aynı kurulum orada da çalışıyor. migrate.test.ts yalnızca bir şeyi sınıyor: kurulumdan sonra pendingMigrations() 0 döndürmeli, çünkü güncelleme öncesi yedeğin tetiği bu sayı.
Örnek veri (db:sample) de aynı launch() üzerinden geliyor. Sunucuyu ayağa kaldırıp gerçek API uçlarını sürüyor, bu yüzden demo veritabanı da her seferinde aynı migration yolundan geçiyor.
Eksik olan test, mevcut veri üzerinde bir yükseltme. Eski bir sürümün şemasını kurup üzerine yeni migration'ları uygulayan otomatik bir test yok. 0029 gibi büyük bir migration'ı geliştirme veritabanında gerçek veriyle elle denedim, ama bunu bir tekrara dönüştürmedim.
Masaüstünde migration bir komut değil, kullanıcının haberi olmadan her açılışta çalışan bir koddur. Ona üretim kodu gibi davranmak gerekiyor.