Expand/contract deseniyle kesintisiz şema değişiklikleri

Şema değişiklikleri neden kesintiye yol açar

Veritabanı değişikliklerinden kaynaklanan kesinti her zaman temiz, açık bir erişim kaybı şeklinde olmaz. Kullanıcılar için bir sayfanın sonsuza kadar yüklenmesi, bir ödemenin başarısız olması veya uygulamanın aniden “bir şeyler yanlış gitti” göstermesi şeklinde görünebilir. Ekipler için ise uyarılar, artan hata oranları ve temizlenmesi gereken başarısız yazma kuyruğu olarak kendini gösterir.

Şema değişiklikleri risklidir çünkü veritabanı uygulamanızın çalışan her sürümü tarafından paylaşılır. Bir sürümdeki release sırasında genellikle eski ve yeni kod aynı anda çalışır (rolling deploy’lar, birden fazla örnek, arka plan işler). Görünüşte doğru olan bir migration yine de bu sürümlerin birini kırabilir.

Yaygın hata durumları şunlardır:

• Yeni kod, henüz olmayan bir sütuna yazmaya çalışır ve anında hata oluşur.
• Eski kod, bir migration’ın yeniden adlandırdığı veya sildiği bir sütunu/tabloyu okumaya çalışır ve deploy sonrası çöker.
• Bir backfill veya indeks oluşturma CPU’yu zirveye çıkarır veya satırları kilitler, normal istekleri yavaşlatır ya da zaman aşımına uğratır.
• NOT NULL gibi “hızlı” görünen bir kısıtlama, tablo doğrulanırken yazmaları engeller.

Kod doğru olsa bile sürümlerin zamanlaması ve uyumluluğu yüzünden yayınlar tıkanır.

Kesintisiz şema değişikliklerinin özünde bir kural var: her ara durum hem eski hem yeni kod için güvenli olmalı. Veritabanını, mevcut okumaları ve yazmaları bozmadan değiştirirsiniz; hem eski hem yeni yapılarına dayanabilecek kod gönderirsiniz; ve eski yolun hiç kimse tarafından kullanılmadığından emin olana kadar onu kaldırmazsınız.

Gerçek trafiğiniz, katı SLA’larınız veya çok sayıda uygulama örneğiniz ve worker’ınız varsa bu ekstra çaba kesinlikle değer. Çok az trafiğe sahip küçük bir iç araçsa planlı bakım penceresi daha basit olabilir.

Expand/contract nedir (basitçe)

Veritabanı işleri kaynaklı çoğu olay, uygulamanın veritabanının anında değişeceğini varsayıp işlerken veritabanının değişimin zaman aldığını fark etmemesinden doğar. Expand/contract deseni bunu, tek riskli değişikliği daha küçük, güvenli adımlara bölerek önler.

Kısa bir süre için sisteminiz iki “diyalektiği” aynı anda destekler. Önce yeni yapıyı tanıtırsınız, eski olanı çalışır tutarsınız, veriyi kademeli taşır, sonra temizlersiniz.

Desen basittir:

• Expand: gerekenleri ekleyin (sütunlar, tablolar, indeksler) ve mevcut uygulamayı bozmayın.
• Her iki yolu çalıştırın: eski ve yeni yapılarla çalışan kod deploy edin böylece karışık sürümler sorunsuz çalışır.
• Contract: her şey yeni yapıyı kullanınca, eski şemayı ve eski kodu kaldırın.

Bu yaklaşım rolling deploy’larla iyi çalışır. 10 sunucuyu teker teker güncelliyorsanız, kısa süreliğine eski ve yeni sürümler birlikte çalışır. Expand/contract, bu örtüşme sırasında veritabanının her iki sürüme de uyumlu kalmasını sağlar.

Ayrıca rollback’leri daha az korkutucu kılar. Yeni sürümde bir hata varsa uygulamayı geri alabilirsiniz; çünkü expand penceresi sırasında eski yapılar hâlâ mevcut olduğu için veritabanını geri almanıza gerek kalmaz.

Örnek: PostgreSQL’de full_name sütununu first_name ve last_name olarak bölmek istiyorsunuz. Yeni sütunları eklersiniz (expand), hem eski hem yeni şekilleri okuyup yazabilen kod gönderirsiniz, eski satırları backfill edersiniz, sonra full_name hiçbir yerde kullanılmadığından emin olunca silersiniz (contract).

Expand genelde neleri kapsar

Expand aşaması yeni seçenekler eklemekle ilgilidir; eski olanı kaldırmakla değil.

Yaygın ilk adım yeni bir sütun eklemektir. PostgreSQL’de genelde en güvenli yol sütunu nullable ve varsayılan değersiz eklemektir. Varsayılanlı ve NOT NULL bir sütun eklemek tablo yeniden yazımı veya daha ağır kilitler tetikleyebilir; Postgres versiyonunuza ve yaptığınız değişikliğe bağlıdır. Daha güvenli sıra genelde: önce nullable ekle, toleranslı kod deploy et, backfill yap, sonra NOT NULL uygulamaya koy.

İndeksler de dikkat ister. Normal indeks oluşturma beklediğinizden daha uzun süre yazmaları engelleyebilir. Mümkünse concurrent olarak indeks oluşturun; daha uzun sürer ama release’i durduracak kilitleri önler.

Expand ayrıca yeni tablolar eklemeyi de kapsayabilir. Tek sütundan many-to-many ilişkiye geçiyorsanız, yeni bir join tablosu ekleyip eski sütunu yerinde tutabilirsiniz. Eski yol çalışırken yeni yapı veri toplamaya başlar.

Pratikte expand genelde şunları içerir:

• Mevcutların yanında yeni nullable sütunlar veya yeni tablolar eklemek
• İndeksleri mümkün olduğunda non-blocking şekilde eklemek
• Yeni okumalar/yazmaların ne zaman açılacağını kontrol etmek için feature flag kullanmak
• Gerektiğinde hem eski hem yeni alanlara yazma (dual-write)
• Okumaları geriye uyumlu tutmak (eski, yeni veya fallback)

Expand sonrası, eski ve yeni uygulama sürümleri aynı anda sürpriz olmadan çalışabilmelidir.

Uyumluluğu koruyan kodu deploy etmek

Çoğu sürüm sıkıntısı ortada ortaya çıkar: bazı sunucular yeni kodu çalıştırırken diğerleri hâlâ eski kodu çalıştırıyor ve veritabanı zaten değişiyordur. Hedefiniz basit: rollout sırasında hangi sürüm olursa olsun hem eski hem genişletilmiş şema ile çalışabilmeli.

Yaygın yaklaşım dual-write’tir. Yeni bir sütun eklediğinizde yeni uygulama hem eskiye hem yenisine yazar. Eski uygulama sürümleri yalnızca eskiye yazmayı sürdürür; çünkü o sütun hâlâ vardır. Yeni sütunu başta opsiyonel tutun ve tüm yazarlar yükselene kadar katı kısıtlamaları erteleyin.

Okumalar genelde yazmalardan daha dikkatli değiştirilir. Bir süre eski sütunda (tam dolu olduğundan emin olduğunuz) okumaları tutun. Backfill ve doğrulamadan sonra okumaları yeni sütunu tercih edecek şekilde değiştirin; yeni eksikse eskiye geri dönün.

Ayrıca veritabanı değişirken API çıktınızı sabit tutun. İçsel bir alan ekleseniz bile tüketiciler hazır olana kadar (web, mobil, entegrasyonlar) yanıt biçimlerini değiştirmekten kaçının.

Geri alınması kolay bir rollout genelde şöyle görünür:

• Release 1: yeni sütunu ekleyin ve eski veriyi okuyabilen, her iki sütuna da yazabilen kodu gönderin.
• Release 2: mevcut satırları backfill edin, sonra yeni sütunu tercih eden ama geri dönebilen kod gönderin.
• Release 3: eski sütuna yazmayı durdurun (ama sütunu yerinde tutun).
• Release 4: eski okumaları kaldırın, sonra eski sütunu silin.

Ana fikir: ilk geri döndürülemez adım eski yapıyı düşürmektir; bunu sona bırakın.

DB’yi yormadan backfill yapmak

Backfill, birçok “kesintisiz şema değişikliği”nin ters gittiği yerdir. Yeni sütunu mevcut satırlar için doldurmak istiyorsunuz; uzun kilitler, yavaş sorgular veya ani yük zirveleri olmadan.

Batching önemlidir. Hızlı biten (saniyeler, dakikalar değil) batchler hedefleyin. Her batch küçükse işi duraklatıp devam ettirebilir, ayarlama yapabilir ve release’leri engellemezsiniz.

İlerlemeyi takip etmek için stabil bir cursor kullanın. PostgreSQL’de bu genelde primary key’tir. Satırları sıra ile işleyin ve tamamladığınız son id’yi depolayın ya da id aralıkları ile çalışın. Bu, job yeniden başladığında pahalı full-table scan’leri önler.

Basit bir desen:

UPDATE my_table
SET new_col = ...
WHERE new_col IS NULL
  AND id > $last_id
ORDER BY id
LIMIT 1000;

Update’i koşullu yapın (örneğin, WHERE new_col IS NULL) böylece job idempotent olur. Tekrar çalıştırmalar sadece hâlâ işi gereken satırları etkiler ve gereksiz yazmaları azaltır.

Backfill sırasında yeni verilerin gelmesini planlayın. Genel sıralama şöyledir:

• Uygulama kodunu önce güncelleyin ki yeni yazmalar da yeni alanı doldursun.
• Tarihsel satırları partiler halinde backfill edin.
• Kısa bir catch-up döngüsü çalıştırıp son satırları yeniden kontrol edin.
• Gerekirse yeni NULL’ları önlemek için trigger veya varsayılan gibi bir guardrail ekleyin.

İyi bir backfill sıkıcıdır: dengeli, ölçülebilir ve veritabanı ısındığında kolayca duraklatılabilir.

Migrasyonun gerçekten bittiğini doğrulamak

En riskli an yeni sütunu ekmek değil; ona güvenebileceğinize karar verdiğiniz andır.

Contract’a geçmeden önce iki şeyi kanıtlayın: yeni veri eksiksiz ve üretimde güvenle okunuyor.

Hızlı ve tekrarlanabilir tamamlanma kontrolleriyle başlayın:

• Yeni sütunda beklenmeyen NULL olmadığını doğrulayın.
• Kaç satırın hedeflendiğini ve kaçının doldurulduğunu karşılaştırın.
• Birkaç ID üzerinde eski ve yeni değerleri elle kontrol edin.
• Kenar durumları test edin (boş stringler, sıfır, çok eski kayıtlar).
• Aynı kontrolleri daha sonra tekrar çalıştırarak sapma olmadığını doğrulayın.

Dual-write yapıyorsanız sessiz hataları yakalamak için bir tutarlılık kontrolü ekleyin. Örneğin, old_value <> new_value dönen satır sayısını saatlik kontrol edip sıfır değilse alarm kurun. Bu genelde hangi yazıcının hâlâ sadece eski sütunu güncellediğini çabucak gösterir.

Migrasyon çalışırken temel üretim sinyallerini izleyin. Sorgu süresi veya kilit beklemeleri yükselirse, güvenli olduğunu düşündüğünüz doğrulama sorguları bile yük ekliyor olabilir. Yeni sütunu okuyan kod yolları için deploy’lardan hemen sonra hata oranlarını izleyin.

Her iki yolu ne kadar tutmalısınız? En az bir tam release döngüsünü ve bir backfill yeniden çalıştırmasını atlatacak kadar. Birçok ekip 1–2 hafta veya hiçbir eski uygulama sürümünün çalışmadığından emin olana kadar bekler.

Contract aşaması: eski yolu kaldırmak

Contract ekipleri genellikle gerginleştirir çünkü geri dönüşü olmayan bir nokta gibi hissettirir. Eğer expand doğru yapıldıysa, contract çoğunlukla temizliktir ve yine de küçük, düşük riskli adımlarla yapılabilir.

Zamanlamayı dikkatle seçin. Backfill hemen bitince bir şeyleri silmeyin. En az bir tam release döngüsü kadar bekleyin ki gecikmiş işler ve kenar durumlar ortaya çıksın.

Güvenli bir contract sırası genelde şöyle olur:

• Çift yazmayı durdurun ve yeni yazmaların yalnızca yeni sütuna gittiğini doğrulayın.
• Uygulamada eski okumaları kaldırın ki fallback ortadan kalksın.
• Eski şemaya referans veren ölü kod yollarını, feature flag’leri ve arka plan işlerini silin.
• Geçici trigger’ları, sync işlerini veya uyumluluk view’lerini kaldırın.
• Eski indeksleri ve kısıtları silin, sonra eski sütunu düşürün.

Mümkünse contract’ı iki release’e bölün: biri kod referanslarını kaldıran (ek logging ile), diğeri veritabanı nesnelerini silen. Bu ayrım rollback ve sorun giderme sürecini kolaylaştırır.

PostgreSQL spesifikleri burada önemlidir. Bir sütunu düşürmek çoğunlukla metadata değişikliğidir, ama kısa bir ACCESS EXCLUSIVE kilidi gerektirebilir. Sessiz bir zaman planlayın ve migration’ı hızlı tutun. Ek indeksler oluşturduysanız, yazmaları engellememek için DROP INDEX CONCURRENTLY kullanmayı tercih edin (bu işlem bir transaction bloğu içinde çalıştırılamaz; dolayısıyla migrasyon aracınızın bunu desteklemesi gerekir).

Yaygın hatalar ve tuzaklar

Kesintisiz migrasyonlar veritabanı ve uygulama neyin izinli olduğu konusunda anlaşmayı bıraktığında başarısız olur. Desen yalnızca her ara durum eski kod ve yeni kod için güvenliyse işe yarar.

Üretimi bozan tuzaklar

Bu hatalar sık görülür:

• Eski uygulama sürümü hâlâ yeni alansız yazma yaparken çok erken NOT NULL eklemek.
• Büyük bir tabloyu tek bir transaction’da backfill yapmak; kilitler, tablo şişmesi ve zaman aşımı yaratır.
• Varsayılan bir değerin ücretsiz olduğunu varsaymak. PostgreSQL’de bazı varsayılanlar tablo yeniden yazımı tetikleyebilir.
• Yazmalar güvenilir şekilde yeni sütunu doldurmadan okumaları yeni sütuna geçirmek.
• Tabloya erişen diğer yazıcı ve okuyucuları unutmak (cron işler, worker’lar, export’lar, raporlama sorguları).

Gerçekçi bir senaryo: API’den full_name yazılmaya başlanır, ama kullanıcı oluşturan bir arka plan işi hâlâ sadece first_name ve last_name ayarlıyor. Gece çalışır, full_name = NULL olan satırlar eklenir ve sonrasında full_name her zaman varmış gibi varsayan kod sorun çıkarır.

Migrasyon ortasında sıkışıp kalmamak için

Her adımı günlerce çalışabilecek bir release gibi değerlendirin:

• Geçiş süresince yeni sütunu nullable tutun ve önce kod içinde “zorunlu” kurallar koyun.
• Küçük partilerle backfill yapın, duraklatılabilir olsun ve DB yükünü izleyin.
• Kodunuzu hoşgörülü yapın: her iki yolu da okuyun, gerektiğinde her iki yola da yazın, eksik değerleri ele alın.
• Tabloya dokunan her yeri denetleyin: worker’lar ve raporlama dahil.

Her release öncesi hızlı kontrol listesi

Tekrar edilebilir bir kontrol listesi, sadece tek bir veritabanı durumunda çalışan kodu göndermenizi engeller.

Deploy etmeden önce veritabanında genişletme parçalarının (yeni sütunlar/tablolar, düşük kilitli oluşturulmuş indeksler) zaten mevcut olduğunu doğrulayın. Sonra uygulamanın toleranslı olduğunu doğrulayın: eski şekil, genişletilmiş şekil ve yarı-backfill durumunda çalışmalı.

Kısa bir kontrol listesi:

• Expansion hazır: yeni şema nesneleri mevcut ve düşük kilitli olarak eklendi.
• Uyumluluk gerçek: uygulama hem eski hem genişletilmiş şema ile çalışıyor, worker’lar ve admin yolları dahil.
• Backfill kontrol altında: küçük partiler, duraklatılabilir, temel ilerleme metrikleri var.
• Okuma geçişi planlı: okumaların ne zaman değişeceği ve yanlış sonuçlarda nasıl geri döneceğiniz belli.
• Contract ertelendi: eski nesneleri silmeden önce en az bir veya iki release döngüsü beklenecek.

Bir migrasyon, okumalar yeni veriyi kullandığında, yazmalar artık eski veriyi tutmadığında ve en az bir basit doğrulama (count veya örnekleme) ile backfill’in doğrulandığında tamamlanmış sayılır.

Gerçekçi bir örnek: bir sütunu kesintisiz değiştirmek

Diyelim PostgreSQL’de customers tablonuz var ve phone sütunu çeşitli formatlarda ve bazen boş tutuluyor. Bunu phone_e164 ile değiştirmek istiyorsunuz ama release’leri engellemek veya uygulamayı kapatmak istemiyorsunuz.

Temiz bir expand/contract sırası şöyle olur:

• Expand: phone_e164 sütununu nullable, varsayılan değersiz ekleyin ve henüz ağır kısıtlamalar koymayın.
• Uyumlu deploy: kodu hem phone hem phone_e164 yazacak şekilde güncelleyin, ancak kullanıcılar için hiçbir şey değişmemesi adına okumaları phone üzerinde tutun.
• Backfill: mevcut satırları küçük partiler halinde (ör. 1.000’er) dönüştürün.
• Okumaları değiştir: önce phone_e164’yi oku, NULL ise phone’a geri dön şeklinde bir fallback kullanın.
• Contract: her şeyin phone_e164 kullandığından emin olunca fallback’i kaldırın, phone’u silin ve gerekiyorsa sıkı kısıtlamaları ekleyin.

Her adım geriye uyumlu kaldığı sürece rollback basit olur. Okuma değişikliği sorun çıkarırsa uygulamayı geri alırsınız ve veritabanında her iki sütun da duruyor. Backfill yük yükseltirse işi duraklatır, batch boyutunu azaltır ve sonra devam edersiniz.

Ekip uyumunu korumak için planı tek bir yerde dokümante edin: kesin SQL, hangi release’in okumaları çevireceği, tamamlanmayı nasıl ölçeceğiniz (ör. phone_e164’nin yüzde kaçının NULL olmadığı) ve her adımın sahibi kim olduğu.

Sonraki adımlar: tekrarlanabilir hale getirin

Expand/contract en iyi şekilde rutin haline geldiğinde çalışır. Ekibinizin her şema değişimi için yeniden kullanabileceği kısa bir runbook yazın; ideal olarak bir sayfa ve yeni birinin takip edebileceği kadar spesifik olsun.

Pratik bir şablon şunları kapsar:

• Expand (kesin migration SQL’leri)
• Kod değişiklikleri (nerede geriye uyum sağlanmalı, dual-read veya dual-write nerede kullanılıyor)
• Backfill (batch boyutu, hız limitleri, duraklatma/devam)
• Doğrulama (doğruluğu kanıtlayan sorgular ve metrikler)
• Contract (neler kaldırılacak ve ne zaman)

Sorumluluğu baştan belirleyin. “Herkesin bir başkası yapacak sanması” eski sütunların ve feature flag’lerin aylarca kalmasının sebebidir.

Backfill çevrimiçiyse bile, bunu daha düşük trafikli zamanda planlayın. Partileri küçük tutmak, DB yükünü izlemek ve gecikme arttığında hızla durmak daha kolaydır.

Eğer Koder.ai (koder.ai) ile planlama ve deploy yapıyorsanız, Planning Mode migrasyon aşamalarını ve kontrol noktalarını dokümante etmek için faydalı olabilir. Uyumluluk kuralları yine geçerlidir; ancak adımları yazılı hale getirmek, kesintilere yol açan “sıkıcı” adımların atlanmasını zorlaştırır.