AI ile Oluşturulan Sistemlerde Şema Değişiklikleri ve Göçler: Bir Rehber

AI ile Oluşturulan Sistemlerde “Şema” Ne Anlama Gelir

Bir şema, basitçe verinin biçimi ve her alanın ne anlama geldiği konusunda ortak kabul demektir. AI ile oluşturulan sistemlerde bu anlaşma yalnızca veritabanı tablolarında değil birçok yerde ortaya çıkar—ve ekiplerin beklediğinden daha sık değişir.

Şema sadece veritabanı işi değildir

Şemalar en az dört katmanda karşınıza çıkar:

• Veritabanları: tablo/sütun adları, veri tipleri, kısıtlar, indeksler ve ilişkiler.
• API’ler: istek/yanıt JSON biçimi, zorunlu vs isteğe bağlı alanlar, enum’lar, hata formatları, sayfalandırma kuralları.
• Olaylar ve mesajlar: akışlar, kuyruklar ve webhook’lar aracılığıyla gönderilen yükler (çoğunlukla tüketiciler aracılığıyla dolaylı olarak sürümlenir).
• Konfigürasyonlar ve sözleşmeler: özellik bayrakları, ortam değişkenleri, YAML/JSON konfigürasyonları ve dosya formatları ile adlandırma kuralları gibi “gizli sözleşmeler”.

Sistemin iki parçası veri değiş tokuşu yapıyorsa, bir şema vardır—hatta kimse bunu yazmamış olsa bile.

Neden AI ile oluşturulan sistemlerde şema daha sık değişir

AI tarafından üretilen kod geliştirmeyi hızlandırır, ama aynı zamanda değişimi artırır:

• Üretilen kod en güncel prompt ve bağlamı yansıtır, bu yüzden küçük prompt değişiklikleri alan adlarını, iç içe yapıları, varsayılanları veya doğrulamaları değiştirebilir.
• Gereksinimler daha hızlı evrilir çünkü yeni bir endpoint veya pipeline adımı yayınlamak ucuzdur.
• Tutarsız konvansiyonlar (snake_case vs camelCase, id vs userId) birden fazla üretim veya refaktör sonucu ortaya çıkar.

Bunun sonucu, üreticiler ile tüketiciler arasında daha sık “sözleşme sürüklenmesi”dir.

Eğer sohbet yoluyla handler’lar, DB erişim katmanları ve entegrasyonlar üretiyorsanız, bu iş akışına baştan itibaren şema disiplini yerleştirmek önemlidir. Koder.ai gibi platformlar sohbet arayüzünden React/Go/PostgreSQL ve Flutter uygulamaları üreterek ekiplerin hızlı ilerlemesine yardımcı olur—ama ne kadar hızlı gönderirseniz, arayüzleri sürümlendirmek, yükleri doğrulamak ve değişiklikleri kasıtlı olarak dağıtmak o kadar önemli olur.

Bu rehberin amacı

Bu yazı, üretimi stabil tutarken hızlı iterasyon yapmayı sağlayan pratik yöntemlere odaklanır: geriye dönük uyumluluğu korumak, değişiklikleri güvenli şekilde yayınlamak ve verileri sürpriz olmadan taşımak.

Neleri kapsamıyoruz

Teori ağırlıklı modelleme, formal yöntemler veya satıcıya özel özelliklerin derin detaylarına girmeyeceğiz. Odak, el ile yazılmış, AI destekli veya büyük ölçüde AI tarafından üretilmiş her türlü teknolojide uygulanabilecek örüntüler üzerinedir.

AI ile Üretilen Kodda Şema Değişikliklerinin Neden Daha Yaygın Olduğu

AI tarafından üretilen kod, şema değişikliklerini “normal” hale getirebilir—bu ekiplerin dikkatsiz olmasından değil, sistem girdilerinin daha sık değişmesinden kaynaklanır. Uygulama davranışınız promptlara, model sürümlerine ve üretilen bağlantı kodlarına kısmen bağlıysa, verinin biçimi zaman içinde daha kolay sürüklenir.

Pratikte sık karşılaşılan tetikleyiciler

Aşağıdaki kalıplar şema sürüklenmesine sık neden olur:

• Yeni ürün özellikleri: yeni bir alan eklemek (ör. risk_score, explanation, source_url) veya bir kavramı bölmek (ör. address yerine street, city, postal_code).
• Model çıktı değişiklikleri: daha yeni bir model daha ayrıntılı yapılar, farklı enum değerleri veya isimlendirme farkları üretebilir ("confidence" vs "score").
• Prompt güncellemeleri: kaliteyi iyileştirmek için yapılan prompt değişiklikleri istemeden formatı, zorunlu alanları veya iç içe yapıyı değiştirebilir.

AI sistemlerini kırılgan yapan riskli kalıplar

AI tarafından üretilen kod genellikle hızlı çalışır, ama kırılgan varsayımları kodlayabilir:

• Örtük varsayımlar: kod bir alanın her zaman mevcut, sayısal veya belirli bir aralıkta olduğunu varsayar.
• Gizli bağlılık: bir servis, tanımlı bir arayüz yerine başka servisin iç alan adlarına veya sıraya bağımlı olur.
• Belgesiz alanlar: model yeni bir özellik üretmeye başlar ve aşağı akıştaki kod bunu sözleşmenin parçasıymış gibi kullanır.

Neden AI değişim sıklığını artırır

Kod üretimi hızlı iterasyonu teşvik eder: gerektikçe handler’ları, parser’ları ve veritabanı erişim katmanlarını yeniden üretebilirsiniz. Bu hız faydalıdır, ama aynı zamanda küçük arayüz değişikliklerini tekrar tekrar göndermeyi kolaylaştırır—bazen fark etmeden.

Daha güvenli yaklaşım, her şemayı bir sözleşme olarak görmektir: veritabanı tabloları, API yükleri, olaylar ve hatta yapılandırılmış LLM yanıtları. Bir tüketici buna bağlıysa, onu sürümlendir, doğrula ve kasıtlı olarak değiştir.

Şema Değişikliklerinin Türleri: Ekleme (Additive) vs Kıran (Breaking)

Şema değişiklikleri eşit değildir. İlk ve en kullanışlı soru: mevcut tüketiciler herhangi bir değişiklik yapmadan çalışmaya devam edecek mi? Eğer evet ise genellikle ekleyicidir. Hayır ise kırıcıdır ve koordine edilmiş bir dağıtım planı gerekir.

Ekleme türündeki değişiklikler (genellikle güvenli)

Ekleme değişiklikleri mevcut anlamı değiştirmeden üzerine ek yapar.

Veritabanı örnekleri:

• Varsayılan değeri olan veya NULL kabul eden yeni bir sütun eklemek (ör. preferred_language).
• Yeni bir tablo veya indeks eklemek.
• Bir sütunda saklanan JSON blob’a isteğe bağlı bir alan eklemek.

Veritabanı dışı örnekler:

• API yanıtına yeni bir özellik eklemek (bilinmeyen alanları görmezden gelen istemciler çalışmaya devam eder).
• Bir akış/kuyruğa yeni bir olay alanı eklemek.
• Varsayılan davranış korunurken yeni bir özellik bayrağı değeri eklemek.

Ekleme yalnızca eski tüketiciler bilinmeyen alanları görmezden geldiği ve yeni alanları zorunlu kılmadığı sürece “güvenlidir”.

Kırıcı değişiklikler (riskli)

Kırıcı değişiklikler, tüketicilerin zaten dayandığı bir şeyi değiştirir veya kaldırır.

Tipik veritabanı kırıcı değişiklikleri:

• Sütun tipini değiştirmek (string → integer, timestamp doğruluğu değişikliği).
• Bir alan/sütunu yeniden adlandırmak (eski adı okuyan kodlar başarısız olur).
• Hâlâ sorgulanan bir sütun/tabloyu silmek.

Veritabanı dışı kırıcı değişiklikler:

• JSON alanlarını istek/yanıt içinde yeniden adlandırmak/kaldırmak.
• Olay semantiğini değiştirmek (aynı alan adı, farklı anlam).
• Webhook yük yapısını sürüm zammı olmadan değiştirmek.

Tüketici etkisini her zaman yazıya dökün

Merge etmeden önce belgeleyin:

• Kim tüketiyor (servisler, panolar, veri pipeline’ları, ortaklar).
• Uyumluluk (geriye dönük/ileriye dönük, ve ne kadar süreyle).
• Hata modu (parsing hataları, sessiz veri bozulması, yanlış iş mantığı).

Bu kısa “etki notu” özellikle AI tarafından üretilen kodun şema değişikliklerini örtük olarak getirdiğinde netlik sağlar.

Şema ve Arayüzler için Sürümleme Stratejileri

Sürümleme, diğer sistemlere (ve gelecekteki size) “bu değişti ve risk düzeyi şu” demenin yoludur. Amaç evrak işi değil—istemciler, servisler veya veri pipeline’ları farklı hızlarda güncellenirken sessiz kırılmaları önlemektir.

Düz dilli semantik sürümleme zihniyeti

Gerçekte 1.2.3 yayınlamasanız bile major / minor / patch olarak düşünün:

• Major: kırıcı değişiklik. Eski tüketiciler değişiklik olmadan başarısız olabilir.
• Minor: güvenli ekleme. Eski tüketiciler çalışmaya devam eder; yeni tüketiciler yeni özellikleri kullanabilir.
• Patch: anlam değiştirmeyen hata düzeltmesi veya açıklama.

Ekipleri kurtaran basit kural: mevcut bir alanın anlamını sessizce değiştirmeyin. Eğer status="active" daha önce “ödeyen müşteri” anlamındaysa, onu “hesap var” anlamına çevirmeyin. Yeni bir alan veya yeni sürüm ekleyin.

Sürümlü endpoint’ler vs alan bazlı sürümleme

Pratikte iki seçenekiniz vardır:

1. Sürümlü endpoint’ler (ör. /api/v1/orders ve /api/v2/orders):

Kırıcı veya yaygın değişikliklerde iyidir. Açık olur ama birden fazla sürümün bakımı ve düplikasyon yaratabilir.

2. Alan bazlı sürümleme / eklemeli evrim (ör. new_field eklemek, old_field korumak):

Ekleme mümkünse iyidir. Eski istemciler anlamadıklarını görmezden gelir; yeni istemciler yeni alanı okur. Zamanla eski alanı deprecate edip planlı şekilde kaldırın.

Olay şemaları ve kayıtları

Akışlar, kuyruklar ve webhook’lar için tüketiciler genellikle dağıtım kontrolünüzün dışındadır. Bir şema kaydı (veya uyumluluk kontrolleri olan merkezi bir şema kataloğu) “sadece eklemelere izin ver” gibi kuralları dayatmaya yardımcı olur ve hangi üreticilerin/tüketicilerin hangi sürümlere bağımlı olduğunu görünür yapar.

Güvenli Dağıtımlar: Genişlet/Sonra Daralt (En Güvenilir Model)

Şema değişikliklerini göndermenin en güvenli yolu—özellikle birden fazla servis, job ve AI tarafından üretilen bileşen varsa—genişlet → backfill → geçiş → daralt modelidir. Bu, kesintiyi en aza indirir ve bir tüketicinin geride kalmasıyla prod’un bozulmasını önler.

Dört adım (ve neden işe yaradığı)

1) Genişlet: Yeni şemayı geriye dönük uyumlu şekilde tanıtın. Mevcut okuma/yazma yolları değişmeden çalışmalı.

2) Backfill: Geçmiş veriler için yeni alanları doldurun (veya mesajları yeniden işleyin) böylece sistem tutarlı hale gelsin.

3) Geçiş: Yazarları ve okuyucuları yeni alan/formatı kullanacak şekilde güncelleyin. Bu, canary veya yüzde bazlı dağıtım gibi kademeli yapılabilir çünkü şema her iki formatı da destekler.

4) Daralt: Hiç kimsenin eski alana bağımlı olmadığından emin olduktan sonra eski alan/formatı kaldırın.

İki aşamalı (genişlet → geçiş) ve üç aşamalı (genişlet → backfill → geçiş) roll-out’lar, yazma ve okuma yollarını bağımsız taşımanızı sağladığı için kesinti süresini azaltır.

Örnek: bir sütun ekle, backfill yap, sonra zorunlu yap

Diyelim customer_tier eklemek istiyorsunuz.

• Genişlet: customer_tier sütununu nullable olarak ekleyin; varsayılan NULL olsun.
• Backfill: Mevcut satırlar için tier hesaplayan bir job çalıştırın.
• Geçiş: Uygulamayı ve pipeline’ları her zaman customer_tier yazacak şekilde güncelleyin; okuyucular bunu tercih etsin.
• Daralt: İzleme sonrası emin olunca sütunu NOT NULL yapın (ve gerekirse eski mantığı kaldırın).

Koordinasyon: yazarlar ve okuyucular anlaşmalı olmalı

Her şemayı üreticiler (yazarlar) ile tüketiciler (okuyucular) arasında bir sözleşme olarak görün. AI ile üretilen sistemlerde bu kolayca gözden kaçabilir çünkü yeni kod yolları hızla ortaya çıkar. Rollout’ları açık hale getirin: hangi sürüm ne yazıyor, hangi servisler her iki sürümü de okuyabiliyor ve eski alanların kaldırılacağı kesin tarih nedir yazın.

Veritabanı Migrasyonları: Üretimi Bozmadan Veriyi Nasıl Değiştirirsiniz

Veritabanı migrasyonları, üretim verisini ve yapısını güvenli bir durumdan diğerine taşımanın “kılavuzu”dur. AI ile oluşturulan sistemlerde daha da önemlidir çünkü üretilen kod bir sütunun var olduğunu varsayabilir, alanları tutarsız şekilde yeniden adlandırabilir veya mevcut satırları göz önüne almadan kısıtlamaları değiştirebilir.

Migration dosyaları vs otomatik migrasyonlar

Migration dosyaları (kaynak kontrolde) “sütun X ekle”, “indeks Y oluştur” veya “A’dan B’ye veri kopyala” gibi açık adımlardır. İncelenir, denetlenir ve staging/production’da yeniden oynatılabilir.

Otomatik migrasyonlar (ORM/framework tarafından oluşturulan) erken geliştirme ve prototipleme için kullanışlıdır, ama üretime dokunan değişikliklerde tehlikeli operasyonlar (sütun silme, tablo yeniden inşa etme) veya beklenmeyen sıralama üretebilir.

Pratik kural: otomatik migrasyonları taslak için kullanın, ama üretimi etkileyen değişiklikler için gözden geçirilmiş migration dosyalarına çevirin.

Idempotans ve sıralama

Migrate işlemlerini mümkün olduğunca idempotent yapın: tekrar çalıştırmak veriyi bozmasın veya yarıda kalmasın. "create if not exists" tercih edin, yeni sütunları önce nullable ekleyin ve veri dönüşümlerini kontrollerle koruyun.

Ayrıca net bir sıraya sahip olun. Her ortam (yerel, CI, staging, prod) aynı migration dizisini uygulamalı. Üretimi manuel SQL ile “düzeltmeyin” unless sonrası bunu bir migration’a kaydedin.

Kilitlemeden uzun süren migrasyonlar

Bazı şema değişiklikleri büyük tabloları kilitleyebilir. Riski azaltmanın yolları:

• Veritabanınızın desteklediği online / kilit-minimizasyonu yapan operasyonları kullanın (ör. eşzamanlı indeks oluşturma).
• Değişiklikleri adımlara bölün: önce yeni yapıları ekleyin, toplu olarak backfill yapın, sonra uygulamayı değiştirin.
• Ağır işlemleri düşük trafik pencerelerine planlayın; zaman aşımları ve izleme koyun.

Çoklu tenant ve shard edilmiş yapı

Multi-tenant veritabanları için tenant başına kontrollü bir döngü ile migrasyon çalıştırın, ilerlemeyi takip edin ve güvenli yeniden denemeler yapın. Shard yapılarında her shard’ı ayrı bir üretim sistemi gibi davranarak adım adım migrate edin, sağlık doğrulaması yapın ve sonra devam edin. Bu patlama alanını sınırlar ve rollback’i mümkün kılar.

Backfill ve Yeniden İşleme: Mevcut Veriyi Güncelleme

Bir backfill, yeni eklenen alanları (veya düzeltilmiş değerleri) mevcut kayıtlar için doldurma işlemidir. Yeniden işleme ise geçmiş veriyi pipeline’dan yeniden geçirmek demektir—genellikle iş kuralları değiştiği, bir hata düzeltildiği veya model/çıktı formatı güncellendiği için yapılır.

Her ikisi de şema değişikliklerinden sonra yaygındır: yeni biçim yalnızca “yeni veriler” için yazılmaya başlanabilir, ama üretim sistemleri dünün verisinin de tutarlı olmasına ihtiyaç duyar.

Yaygın yaklaşımlar

Çevrimiçi backfill (prod ortamında, kademeli): Küçük partiler halinde kontrollü bir job çalıştırarak kayıtları güncellersiniz; bu, durumu duraklatma ve resume etme imkânı sağlar.

Toplu backfill (offline veya zamanlanmış işler): Büyük parçaları düşük trafik penceresinde işlersiniz. Operasyonel olarak basittir ama DB yükünde ani zirveler yaratabilir ve hatadan kurtulması daha uzun sürebilir.

Okurken tembel backfill: Eski bir kayıt okunduğunda uygulama eksik alanları hesaplayıp yazıyor. Bu maliyeti zamana yayar ve büyük bir job’dan kaçınır, ama ilk okuma daha yavaş olur ve bazı kayıtlar uzun süre dönüştürülmemiş kalabilir.

Pratikte ekipler genellikle bunları kombine eder: nadir kayıtlar için tembel backfill, sık erişilen veri için çevrimiçi job.

Bir backfill nasıl doğrulanır

Doğrulama açık ve ölçülebilir olmalı:

• Sayım: kaç satır/girdi güncellenmeli vs kaç güncellendi.
• Checksum/aggregate: toplamları karşılaştırın (ör. tutarların toplamı, benzersiz ID sayısı).
• Örnekleme: kenar durumları da içeren istatistiksel örneklemeler yapın.

Ayrıca panolar, arama indeksleri, önbellekler ve güncellenen alanlara bağımlı dışa aktarmaları da doğrulayın.

Maliyet, süre ve kabul kriterleri

Backfill hız (hızlı bitirme) ile risk/maliyet (yük, compute, operasyonel iş) arasında takas yapar. Başlangıçta şu soruları netleştirin: “tamam” ne demek, beklenen çalışma süresi, izin verilen maksimum hata oranı ve doğrulama başarısız olursa duraklatma/yeniden deneme/geri alma stratejisi.

Olay ve Mesaj Şeması Evrimi (Stream’ler, Kuyruklar, Webhook’lar)

Şemalar sadece veritabanlarında yaşamaz. Bir sistem başka birine veri gönderdiğinde—Kafka topic’leri, SQS/RabbitMQ kuyrukları, webhook yükleri, hatta nesne depolamaya yazılan “event”ler—bir sözleşme oluşur. Üreticiler ve tüketiciler bağımsız hareket ettiğinden, bu sözleşmeler tek bir uygulamanın tablolarından daha sık kırılır.

En güvenli varsayılan: olayları geriye dönük uyumlu geliştirin

Olay akışları ve webhook’larda, eski tüketicilerin görmezden gelebileceği ve yeni tüketicilerin benimseyebileceği değişiklikleri tercih edin.

Pratik kural: alan ekleyin, kaldırmayın veya yeniden adlandırmayın. Deprecate etmek gerekirse, bir süre daha göndermeye devam edin ve açıkça belgeleyin.

Örnek: OrderCreated olayına isteğe bağlı alanlar ekleyin.

{
  "event_type": "OrderCreated",
  "order_id": "o_123",
  "created_at": "2025-12-01T10:00:00Z",
  "currency": "USD",
  "discount_code": "WELCOME10"
}

Eski tüketiciler order_id ve created_at alanlarını okur, geri kalanları görmezden gelir.

Tüketici odaklı sözleşmeler (düz Türkçe versiyon)

Üreticinin başkalarını neyin kıracağını tahmin etmesi yerine, tüketiciler hangi alanlara dayandıklarını yayımlasın. Üretici, değişiklikleri göndermeden önce bu beklentilere karşı doğrulama yapsın. Bu, modelin “yardımcı olarak” bir alanı yeniden adlandırabileceği veya tipini değiştirebileceği AI üretilen kod tabanlarında özellikle faydalıdır.

“Bilinmeyen alanlar”ı güvenli şekilde ele almak

Parser’ları toleranslı yapın:

• Bilinmeyen alanları varsayılan olarak görmezden gelin (yeni bir anahtar geldi diye hata vermeyin).
• Yeni alanları gerçekten gerekli olana kadar isteğe bağlı kabul edin.
• Beklenmeyen alanları alarm vermeden düşük seviyede loglayın, böylece benimsenmeyi görebilirsiniz.

Kırıcı değişiklik gerektiğinde yeni bir olay türü veya sürümlü ad kullanın (ör. OrderCreated.v2) ve tüm tüketiciler migrate olana kadar paralel çalıştırın.

AI Çıktılarını Bir Şema Olarak Görmek: Prompt’lar, Modeller ve Yapılandırılmış Yanıtlar

Bir LLM eklediğinizde, çıktılar hızla yazılı bir şema haline gelebilir—hiç kimse resmi bir spesifikasyon yazmamış olsa bile. Aşağı akıştaki kod “bir summary alanı olacak”, “ilk satır başlık”, veya “madde işaretleri tire ile ayrılır” gibi varsayımlarda bulunur. Bu varsayımlar katılaşır ve model davranışındaki küçük bir kayma bunları veritabanı sütunu yeniden adlandırması gibi kırabilir.

Açık yapı tercih edin (ve doğrulayın)

"Güzel metin"i parse etmek yerine, yapılandırılmış çıktılar (genellikle JSON) isteyin ve bunları sistemin geri kalanına sokmadan önce doğrulayın. Bunu "bir sözleşmeye geçme" olarak düşünün.

Pratik yaklaşım:

• Model yanıtı için bir JSON şeması (veya tipli bir arayüz) tanımlayın.
• Geçersiz yanıtları reddedin veya karantinaya alın (sessizce zorlamayın).
• Değişiklikleri görebilmek için doğrulama hatalarını loglayın.

Bu, LLM yanıtlarının veri pipeline’larına, otomasyona veya kullanıcıya yönelik içeriğe beslendiği durumlarda özellikle önemlidir.

Model drift’e hazırlıklı olun

Aynı prompt ile bile çıktı zaman içinde kayabilir: alanlar atlanabilir, ekstra anahtarlar görünebilir ve tipler değişebilir ("42" vs 42, dizi vs string). Bunları bir şema evrimi olayı gibi ele alın.

Etkili hafifletmeler:

• Mümkünse alanları isteğe bağlı yapın ve varsayılanları açıkça belirleyin.
• Bilinmeyen anahtarlara izin verin ama güvenli şekilde yoksayma (uygulama katmanında).
• "Guardrail" kontrolleri ekleyin (zorunlu alanlar, maksimum uzunluk, enum değerleri).

Prompt değişikliklerini API değişikliği gibi ele alın

Bir prompt bir arayüzdür. Eğer düzenlerseniz, onu sürümlendirin. prompt_v1, prompt_v2 tutun ve kademeli olarak yayınlayın (özellik bayrakları, canary’ler veya tenant bazlı geçişler). Değişiklikleri terfi ettirmeden önce sabit bir değerlendirme setiyle test edin ve aşağı akış tüketicileri adapte olana kadar eski sürümü çalışır tutun. Güvenli dağıtım mekanikleri hakkında daha fazla bilgi için yaklaşımınızı safe-rollouts-expand-contract ile ilişkilendirin.

Şema Değişiklikleri için Test ve Doğrulama

Şema değişiklikleri genellikle sıkıcı ama pahalı şekillerde başarısız olur: yeni bir sütun bir ortamda eksik olur, bir tüketici eski alanı beklemeye devam eder veya bir migration boş veriyle sorunsuz çalışır ama prod’da zaman aşımına uğrar. Test, bu "sürprizleri" tahmin edilebilir ve düzeltilebilir işe çevirir.

Üç seviye test (ve her biri hangi hatayı yakalar)

Birim testleri yerel mantığı korur: mapping fonksiyonları, serileştiriciler/deserileştiriciler, doğrulayıcılar ve sorgu oluşturucular. Bir alan yeniden adlandırıldığında veya tipi değiştiğinde birim testler ilgili koda yakın yerde başarısız olmalı.

Entegrasyon testleri uygulamanızın gerçek bağımlılıklarla (gerçek veritabanı motoru, gerçek migration aracı, gerçek mesaj formatları) çalıştığını doğrular. ORM model değişmiş ama migration olmamış gibi sorunlar burada yakalanır.

Uçtan uca testler hizmetler arası iş akışlarını taklit eder: veri oluştur, migrate et, API’ler üzerinden geri oku ve aşağı akış tüketicilerin hala doğru davrandığını doğrula.

Üretici-tüketici sözleşme testleri

Şema evrimi sınırlarda bozulma yaratır. Hem taraflarda çalışacak sözleşme testleri ekleyin:

• Üreticiler, anlaşmaya uygun olay/yanıt üretebildiklerini kanıtlasın.
• Tüketiciler, rollout sırasında hem eski hem yeni sürümleri parse edebildiklerini doğrulasın.

Migration testi: temiz ortamlarda apply ve rollback

Migrasyonları deploy edeceğiniz gibi test edin:

• Temiz bir veritabanı snapshot’ı ile başlayın.
• Tüm migration’ları sırayla uygulayın.
• Uygulamanın okuma/yazma yapabildiğini doğrulayın.
• Rollback (destekleniyorsa) çalıştırın veya “down” migration ile geri dönülebildiğini teyit edin.

Eski ve yeni şema sürümleri için fixture’lar

Küçük bir fixture seti saklayın:

• Önceki şema altında yazılmış veri (legacy satırlar/olaylar).
• Yeni şema altında yazılmış veri.

Bu fixture’lar gerilemeleri görünür kılar, özellikle AI tarafından üretilen kod alan adlarını, istekliliği veya formatı ince ince değiştirdiğinde.

Gözlemlenebilirlik: Bozulmayı Erken Tespit Etme

Şema değişiklikleri nadiren dağıtıldıkları anda yüksek sesle başarısız olur. Genellikle başarısızlık, parsing hatalarında artış, bilinmeyen alan uyarıları, eksik veri veya arka plan job’larının geride kalması şeklinde yavaşça görünür. İyi gözlemlenebilirlik, bu zayıf sinyalleri hâlâ rollout’u durdurabileceğiniz zamanda eyleme dönüştürür.

Rollout sırasında ne izlemeli

Temel uygulama sağlığının yanında şema-özgü sinyaller ekleyin:

• Hatalar: 4xx/5xx yükselişleri, ayrıca JSON parsing hataları, deserileştirme hataları ve retry’ler.
• Gecikme: p95/p99 cevap süreleri ve kuyruk işleme süreleri.
• Veri kalitesi sinyalleri: önemli sütunlarda null oranı artışı, olay hacminde ani düşüş, yeni "varsayılan" değerlerin çok sık görünmesi veya eski/yeni temsil arasında tutarsızlıklar.
• Pipeline gecikmesi: stream/queue tüketici gecikmesi, webhook teslim yığılması ve migration job throughput’u.

Anahtar nokta, önceki vs sonraki karşılaştırması yapmak ve istemci sürümü, şema sürümü ve trafik segmenti (canary vs stable) bazında dilimlemektir.

Faydalı panolar

İki pano görünümü oluşturun:

1. Uygulama davranışı panosu

   • İstek oranı, hata oranı, gecikme (RED)
   • En sık görülen istisnalar (mesaja göre gruplanmış)
   • Doğrulama/parsing hata sayısı ve oranı
   • Yük dağılımı (payload boyutu)

2. Migration ve arka plan job panosu

   • Migration job ilerlemesi (% tamamlandı), satır/saniye, ETA
   • Hata oranı ve retry sayısı
   • Kuyruk derinliği / tüketici gecikmesi
   • Dead-letter kuyruk hacmi

Eğer expand/contract rollout yapıyorsanız, eski vs yeni şema ile okuma/yazma ayrımını gösteren bir panel ekleyin ki bir sonraki faza geçmek güvenli olsun.

Şema-özgü başarısızlıklar için uyarılar

Verinin düşürüldüğünü veya yanlış okunduğunu gösteren durumlarda sayfa açın:

• Şema doğrulama hata oranı düşük bir eşik üzerinde (çoğu durumda %0.1’den az zaten anlamlıdır)
• Parse/deserileştirme hataları (özellikle tek bir üretici/tüketiciye yoğunlaşıyorsa)
• Beklenmeyen alan / eksik zorunlu alan uyarıları trendleniyorsa
• Migration job takıldı (N dakika boyunca ilerleme yok) veya lag artışı throughput’tan hızlıysa

Ham 500’ler üzerine gürültülü alarmlar yerine, uyarıları şema sürümü ve endpoint gibi etiketlerle ilişkilendirin.

Hızlı hata ayıklama için sürümü loglayın

Geçiş sırasında loglara şunları dahil edin:

• Şema sürümü (ör. X-Schema-Version header, mesaj meta verisi alanı)
• Üretici ve tüketici uygulama sürümü
• Model sürümü / prompt sürümü (AI tarafından üretilen çıktılar yapılandırılmış veriye besleniyorsa)

Bu tek detay, farklı servisler veya model sürümleri aynı anda çalışırken "bu payload neden başarısız oldu?" sorusunun yanıtını dakikalar içinde verir.

Geri Alma, Kurtarma ve Değişim Yönetimi

Şema değişiklikleri iki şekilde başarısız olur: değişiklik kendisi yanlış olabilir veya çevresindeki sistem beklenenden farklı davranır (özellikle AI tarafından üretilen kod ince varsayımları getirdiğinde). Her durumda, her migration göndermeden önce bir geri alma hikâyesi olmalı—hatta bu hikâye “geri alma yok” olsa bile.

"Geri alma yok" seçimi, kolon düşürme, kimlikleri yeniden yazma veya kayıplı normalizasyon gibi geri döndürülemez değişikliklerde geçerli olabilir. Ancak "geri alma yok" bir planın olmadığı anlamına gelmez; forward fix, restore ve containment yönünde bir plan gerektirir.

Gerçekten işe yarayan pratik geri alma seçenekleri

Özellik bayrakları / konfigürasyon kapıları: Yeni okuyucuları, yazarları ve API alanlarını bir bayrakla sarmalayın ki yeni davranışı redeploy etmeden kapatabilesiniz. Bu, AI tarafından üretilen kod doğru sözdizimsel ama anlamsal olarak yanlış olduğunda özellikle faydalıdır.

Dual-write’ı devre dışı bırakın: Expand/contract aşamasında hem eski hem yeni şemaya yazıyorsanız bir kill switch tutun. Yeni yazma yolunu kapatmak, farkı büyütmeyi durdurur.

Sadece yazarları değil okuyucuları da geri alın: Birçok olay, tüketicilerin yeni alanları veya tabloları erken okumaya başlamasıyla olur. Servisleri önceki şema sürümüne veya yeni alanları yoksayacak şekilde kolayca döndürebilin.

Geri döndürülebilirliğin sınırlarını bilin

Bazı migrasyonlar temizce geri alınamaz:

• Kayıplı dönüşümler (örn. hashing, lossy normalization).
• Kopyası alınmamış silmeler/yeniden adlandırmalar.
• Kaynak değeri üzerine yazan backfill’ler.

Bunlar için yedekten geri yükleme, olaylardan yeniden oynatma veya ham girdilerden yeniden hesaplama planları yapın—ve bu girdilerin gerçekten mevcut olduğunu doğrulayın.

Yayın öncesi kontrol listesi (shipping’den önce)

• Geri alma kararı belgelenmiş (“revert”, “forward fix” veya “no rollback + restore path”).
• Net bir stop düğmesi: bayraklar ve/veya dual-write disable anahtarı.
• Yedekler/snapshot’lar doğrulandı; restore en az bir kez test edildi.
• Migration idempotent; yeniden çalıştırma veriyi bozmaz.
• İzleme ve uyarılar: hata oranları, şema doğrulama hataları ve lag için.
• Sahiplik: kim onaylıyor, kim çalıştırıyor, kim rollout boyunca on-call.

İyi değişim yönetimi geri alma olasılığını nadir yapar—ve geri alma gerektiğinde kurtarmayı sıkıcı işler haline getirir.

Eğer ekibiniz AI destekli hızlı iterasyon yapıyorsa, bu uygulamaları güvenli deneyimi destekleyen araçlarla eşleştirmek faydalıdır. Örneğin, Koder.ai, değişiklik tasarımı için planning mode ve yanlışlıkla bir sözleşmeyi kaydıran değişiklikte hızlı kurtarma için snapshots/rollback özellikleri sunar. Hızlı kod üretimi ile disiplinli şema evrimi birlikte kullanıldığında, üretimi bir test ortamı gibi değerlendirmeden daha hızlı ilerlemenizi sağlar.