KoderKoder.ai
FiyatlandırmaKurumsalEğitimYatırımcılar için
Giriş YapBaşla

Ürün

FiyatlandırmaKurumsalYatırımcılar için

Kaynaklar

Bize UlaşınDestekEğitimBlog

Yasal

Gizlilik PolitikasıKullanım KoşullarıGüvenlikKabul Edilebilir Kullanım PolitikasıKötüye Kullanımı Bildir

Sosyal

LinkedInTwitter
Koder.ai
Dil

© 2026 Koder.ai. Tüm hakları saklıdır.

Ana Sayfa›Blog›Claude Code PostgreSQL migrasyonları: güvenli değişiklikler için prompt'lar
05 Ara 2025·6 dk

Claude Code PostgreSQL migrasyonları: güvenli değişiklikler için prompt'lar

Claude Code ile PostgreSQL migrasyonlarında expand-contract desenini, backfill, rollback planları ve release öncesi staging'de doğrulanması gerekenleri öğrenin.

Claude Code PostgreSQL migrasyonları: güvenli değişiklikler için prompt'lar

PostgreSQL şema değişikliğini riskli yapan nedir?

Bir PostgreSQL şema değişikliği gerçek trafik ve gerçek veriyle karşılaşana kadar basit görünür. Riskli olan kısmı genellikle SQL'in kendisi değildir. Asıl problem, uygulama kodu, veritabanı durumu ve dağıtım zamanlaması eşleşmeyi bıraktığında başlar.

Çoğu başarısızlık pratik ve acı vericidir: bir deploy eski kodun yeni bir kolona dokunması yüzünden bozulur, bir migration sıcak bir tabloyu kilitler ve timeout'lar patlar, ya da bir “hızlı” değişiklik sessizce veriyi siler veya yeniden yazar. Hiçbir şey çökmediğinde bile yanlış varsayılanlar, bozuk kısıtlar veya tamamlanmamış indeksler gibi ince hatalar gönderebilirsiniz.

AI tarafından üretilen migration'lar ayrıca ayrı bir risk katmanı getirir. Araçlar geçerli SQL üretebilir ama iş yükünüz, veri hacminiz veya yayın süreciniz için güvensiz olabilir. Tablo isimlerini tahmin edebilir, uzun süren kilitleri atlayabilir veya geri alma konusunda belirsiz davranabilirler çünkü down migration’lar zordur. Eğer migration’lar için Claude Code kullanıyorsanız, koruyucu kurallara ve somut bağlama ihtiyacınız var.

Bu yazı bir değişiklikten "güvenli" söz ederken üç şeyi kasteder:

  • Geriye dönük uyumluluk: eski ve yeni uygulama sürümleri rollout sırasında birlikte çalışabilir.
  • Gözlemlenebilirlik: ilerlemeyi ölçebilir ve sorunları hızlıca fark edebilirsiniz.
  • Geri alınabilirlik: baskı altında uygulayabileceğiniz bir rollback planına sahipsiniz.

Amaç, migration'ları rutin hale getirmek: öngörülebilir, test edilebilir ve sıkıcı.

Herhangi bir prompt yazmadan önce uymanız gereken güvenlik kuralları

Modeli odaklı tutmak ve sadece laptopunuzda çalışan bir değişikliği göndermemeniz için birkaç tartışılmaz kuralla başlayın.

İşi küçük adımlara bölün. Bir şema değişikliği, bir veri backfill'i, bir uygulama değişikliği ve bir temizlik adımı farklı risklerdir. Bunları birleştirmek neyin bozulduğunu görmeyi ve geri almayı zorlaştırır.

Yıkıcı olanlardan önce ekleyici değişiklikleri tercih edin. Bir sütun, indeks veya tablo eklemek genelde düşük risklidir. Yeniden adlandırma veya nesne silme kesintilerin olduğu yerdir. Önce güvenli kısmı yapın, uygulamayı taşıyın, ve eski şeyi yalnızca kullanılmadığından emin olduktan sonra kaldırın.

Uygulamanın bir süre iki biçimi de tolere etmesini sağlayın. Kod, rollout sırasında ya eski sütunu ya da yeni sütunu okuyabilmeli. Bu, bazı sunucular yeni kodu çalıştırırken veritabanının hâlâ eski olduğu (veya tersine) yaygın yarış durumunu önler.

Migration'ları hızlı bir betik değil, production kodu gibi ele alın. Koder.ai (Go backend ile PostgreSQL, ayrıca React veya Flutter istemciler) gibi bir platformla inşa ediyor olsanız bile, veritabanı her şey tarafından paylaşılır. Hatalar pahalıdır.

SQL isteğinin başına koymak için kompakt bir kural seti isterseniz şöyle bir şey kullanın:

  • Migration başına bir değişiklik: önce expand, sonra backfill, sonra kod geçişi, sonra cleanup.
  • Uzun kilitlerden kaçının: concurrent index oluşturma ve güncellemeler için küçük partiler kullanın.
  • Her adım için bir rollback planı zorunlu olsun; backfill ortasında nasıl durdurulacağını da dahil edin.
  • Doğrulama sorguları ve başarı metrikleri isteyin (satır sayıları, null oranları, zamanlama).
  • Bir runbook isteyin: nasıl çalıştırılır, neye bakılmalı ve kimi aramalı.

Pratik bir örnek: uygulamanızın bağlı olduğu bir kolonu yeniden adlandırmak yerine yeni kolonu ekleyin, yavaşça backfill edin, yeni sonra eskiyi kaldırın.

Claude Code'u gerçeğe bağlamak için prompt'a neler eklemelisiniz

Claude belirsiz bir isteğe göre makul SQL yazabilir, ama güvenli migration'lar bağlam ister. Prompt'unuzu küçük bir tasarım brifi gibi ele alın: ne olduğunu gösterin, hangi şeyin bozulmaması gerektiğini açıklayın ve rollout için "güvenli"nin ne anlama geldiğini tanımlayın.

Sadece önemli veritabanı gerçeklerini yapıştırarak başlayın. Tablo tanımını ve ilgili indeksleri ve kısıtları (primary key, unique, foreign key, check constraint, trigger) ekleyin. İlgili tablolar varsa, onların snippet'lerini de koyun. Küçük, doğru bir kesit modelin isimleri tahmin etmesini veya önemli bir kısıtı kaçırmasını önler.

Gerçek dünya ölçeğini ekleyin. Satır sayıları, tablo boyutu, yazma hızı ve zirve trafik planı değişikliği etkiler. "200M satır ve 1k yazma/sn" ile "20k satır ve çoğunlukla okuma" çok farklıdır. Ayrıca Postgres sürümünüzü ve migration'ların sisteminizde nasıl çalıştığını (tek transaction mı yoksa birden fazla adım mı) belirtin.

Uygulamanın veriyi nasıl kullandığını açıklayın: önemli okuma, yazma ve background job'lar. Örnekler: "API email ile okur", "workerlar durum günceller" veya "raporlar created_at'e göre tarar". Bu, expand/contract, feature flag ve backfill güvenliğinin nasıl olması gerektiğini belirler.

Son olarak, kısıtlar ve teslimatlar konusunda açık olun. Basit bir yapı iyi çalışır:

  • Geçerli şema snippet'leri ve hedef
  • Ölçek varsayımları (satır sayısı, yazma/sn, bakım penceresi varsa)
  • Uygulama bağımlılıkları (sorgular/endpoint'ler/job'lar)
  • Sert kısıtlar (sıfır kesinti, uzun kilitlerden kaçınma, tam tablo yeniden yazmadan kaçınma)
  • Teslimatlar: SQL artı düz dil ile çalışma planı, doğrulama ve rollback

Hem SQL hem de run planı istemek modeli sıralama, risk ve kontrol edilecekler hakkında düşünmeye zorlar.

Expand/contract basitçe (ve ne zaman kullanılmalı)

Expand/contract migration deseni PostgreSQL veritabanını değiştirirken uygulamanın kırılmamasını sağlar. Tek riskli anahtar yerine, veritabanının eski ve yeni biçimleri bir süre desteklemesini sağlarsınız.

Bunu şu şekilde düşünün: önce yeni şeyleri güvenle ekleyin (expand), trafiği ve veriyi kademeli taşıyın, ve sadece sonra eski parçaları kaldırın (contract). Bu, AI destekli çalışmalarda özellikle faydalıdır çünkü karmaşık süreç için plan yapmanızı zorlar.

Dört aşama

Pratik bir akış şöyle görünür:

  • Expand: yeni nullable sütun veya tablo ekleyin, gerekiyorsa indeks ekleyin ve engelleme yapmayacak şekilde kısıtlar ekleyin (örneğin uygun yerde NOT VALID kullanmak).
  • Compatibility: uygulamayı hem eski hem yeni alanları idare edecek şekilde güncelleyin. Bu dual-write (ikili yazma) veya read-fallback (yeni oku, yoksa eski) olabilir.
  • Backfill: eski veriyi yeniye küçük partilerle taşıyın, checkpoint'ler ve yeniden başlatma yolları olsun.
  • Contract: her şeyin yeni yolu kullandığından emin olduktan sonra kuralları sıkılaştırın (NOT NULL yapmak, kısıtları doğrulamak), sonra eski sütunu veya tabloyu silin.

Bu deseni, kullanıcılar veritabanını değiştirirken hala eski uygulama sürümünde olabilirlerse her zaman kullanın. Çok örnekli dağıtımlar, yavaş güncellenen mobil uygulamalar veya migration'ın dakikalar/ saatler sürebileceği herhangi bir yayın için uygundur.

Yararlı bir taktik iki sürüm planlamaktır. Sürüm 1 expand + compatibility yapar, böylece backfill eksik olsa bile bir şey kırılmaz. Sürüm 2 yalnızca contract yapar, yeni kod ve verinin yerinde olduğundan emin olduktan sonra.

Expand/contract migration'lar için güvenli bir prompt şablonu

Bu şablonu kopyalayıp köşeli parantezleri doldurun. Claude Code'u çalıştırılabilir SQL, doğrulama ve gerçekçi bir rollback planı üretmeye zorlar.

You are helping me plan a PostgreSQL expand-contract migration.

Context
- App: [what the feature does, who uses it]
- Database: PostgreSQL [version if known]
- Table sizes: [rough row counts], write rate: [low/medium/high]
- Zero/near-zero downtime required: [yes/no]

Goal
- Change: [describe the schema change]
- Current schema (relevant parts):
  [paste CREATE TABLE or \d output]
- How the app will change (expand phase and contract phase):
  - Expand: [new columns/indexes/triggers, dual-write, read preference]
  - Contract: [when/how we stop writing old fields and remove them]

Hard safety requirements
- Prefer lock-safe operations. Avoid full table rewrites on large tables when possible.
- If any step can block writes, call it out explicitly and suggest alternatives.
- Use small, reversible steps. No “big bang” changes.

Deliverables
1) UP migration SQL (expand)
   - Use clear comments.
   - If you propose indexes, tell me if they should be created CONCURRENTLY.
   - If you propose constraints, tell me whether to add them NOT VALID then VALIDATE.

2) Verification queries
   - Queries to confirm the new schema exists.
   - Queries to confirm data is being written to both old and new structures (if dual-write).
   - Queries to estimate whether the change caused bloat/slow queries/locks.

3) Rollback plan (realistic)
   - DOWN migration SQL (only if it is truly safe).
   - If down is not safe, write a rollback runbook:
     - how to stop the app change
     - how to switch reads back
     - what data might be lost or need re-backfill

4) Runbook notes
   - Exact order of operations (including app deploy steps).
   - What to monitor during the run (errors, latency, deadlocks, lock waits).
   - “Stop/continue” checkpoints.

Output format
- Separate sections titled: UP.sql, VERIFY.sql, DOWN.sql (or ROLLBACK.md), RUNBOOK.md

İki ek satır pratikte yardımcı olur:

  • Her yazma-engelleyici (write-blocking) adımı RISK: blocks writes olarak etiketle ve ne zaman çalıştırılacağını söyle (off-peak vs anytime).
  • Kilitler konusunda dürüst olmaya zorla: "Eğer bir ifadenin ACCESS EXCLUSIVE kilidi alıp almayacağından emin değilsen, söyle ve daha güvenli bir seçenek öner."

Yaygın şema işlemleri ve daha güvenli SQL istemek için nasıl prompt atılır

Bring a teammate along
Invite others to try Koder.ai and earn credits through your referral link.
Refer Friend

Küçük şema değişiklikleri bile uzun kilitler, büyük tablo yeniden yazımları veya yarıda başarısız olma riskiyle zarar verebilir. Claude Code kullandığınızda, yeniden yazımlardan kaçınan ve uygulamanız çalışırken veritabanının yetişmesini sağlayan SQL isteyin.

Varsayılan olmadan sütun ekleme (uzun kilitler olmadan)

Nullable bir sütun eklemek genelde güvenlidir. Non-null ve varsayılan bir değer eklemek bazı eski Postgres sürümlerinde tabloyu yeniden yazdırabileceği için risklidir.

Daha güvenli yaklaşım iki aşamalıdır: sütunu önce NULL ve varsayılan olmadan ekleyin, partiler halinde backfill yapın, sonra yeni satırlar için varsayılanı ayarlayın ve veri temizse NOT NULL yapın.

Hemen bir varsayılan gerekiyorsa, Postgres sürümünüz için kilit davranışı hakkında açıklama ve beklenenden uzun sürerse bir fallback planı isteyin.

İndeksler, FK'lar, kısıtlar, drop'lar

Büyük tablolarda indeksler için CREATE INDEX CONCURRENTLY isteyin ki okuma ve yazma akmaya devam etsin. Ayrıca bunun bir transaction bloğu içinde çalıştırılamayacağını (non-transactional adım gerektiğini) belirtin.

Foreign key'ler için daha güvenli yol genellikle önce NOT VALID olarak eklemek, sonra doğrulamaktır. Bu başlangıçtaki değişikliği hızlı tutar ama yeni yazımları yine de kısıtlar.

Daha katı kısıtlar (NOT NULL, UNIQUE, CHECK) eklerken "önce temizle, sonra zorla" isteyin. Migration kötü satırları tespit etmeli, bunları düzeltmeli ve yalnızca sonra daha katı kuralı etkinleştirmelidir.

Kısa bir kontrol listesi gerektiğinde:

  • Kilitler ve beklenen çalışma süresi hakkında notlar ekleyin.
  • Büyük indeksler için CONCURRENTLY kullanın ve transaction sınırlarını belirtin.
  • Yeni foreign key'ler için NOT VALID sonra VALIDATE tercih edin.
  • Backfill'i NOT NULL/UNIQUE uygulamaktan ayırın.
  • Bir nesneyi düşürmeden önce tam bir yayın döngüsü bekleyin ve kimsenin onu okumadığını doğrulayın.

Yavaş, dengeli ve kurtarılabilir backfill'ler için prompt atma

Backfill'ler çoğu migration acısını gösterir, ALTER TABLE değil. En güvenli prompt'lar backfill'leri kontrollü işler gibi ele alır: ölçülebilir, yeniden başlatılabilir ve production'a nazik.

Başlangıç olarak kabul kriterleri ekleyin: beklenen satır sayıları, hedef null oranı ve birkaç spot kontrol (örneğin 20 rastgele ID için eski ve yeni değerleri karşılaştırma).

Sonra bir batching planı isteyin. Partiler kilitleri kısa tutar ve sürprizleri azaltır. İyi bir istek şunu belirtir:

  • Nasıl batchlenecek (primary key aralıkları veya created_at gibi zaman pencereleri)
  • Hedef batch büyüklüğü (örneğin 5.000 ile 50.000 satır)
  • Sıcak tablolarda partiler arası bekleme (sleep) gerekip gerekmediği
  • Her partinin tek bir net transaction olması (tek büyük işlem yerine)

Idempotency isteyin çünkü backfill'ler yarıda başarısız olur. SQL tekrar çalıştırılabilir olmalı, çoğaltma veya veri bozulması yapmamalı. Tipik desenler UPDATE ... WHERE new_col IS NULL veya deterministik kurallar kullanmaktır.

Uygulamanın backfill çalışırken doğru kalmasını nasıl sağlayacağınızı da yazın. Yeni yazımlar devam ediyorsa köprü gerekir: uygulamada dual-write, geçici trigger veya read-fallback mantığı. Hangi yaklaşımı güvenle dağıtabileceğinizi söyleyin.

Ayrıca durdurma ve yeniden başlatma tasarlayın. İlerlemeyi izleyen küçük bir tablo (son işlenen ID) ve ilerlemeyi raporlayan bir sorgu (güncellenen satırlar, son ID, başlama zamanı) isteyin.

Örnek: users.full_name ekliyorsunuz ve bunu first_name + last_name'den türetiyorsunuz. Güvenli backfill yalnızca full_name IS NULL olanları günceller, ID aralıklarında çalışır, son işlenen ID'yi kaydeder ve yeni kayıtlar için dual-write tutar.

Gerçekçi rollback planları nasıl istenir

Get safer SQL drafts
Ask Koder.ai for migration SQL plus verification queries and a rollback runbook.
Generate SQL

Rollback planı sadece "down migration yaz" demek değildir. İki problem vardır: şema değişikliğini geri almak ve yeni sürüm yayındayken değişen veriyi ele almak. Şema rollback genelde mümkündür. Veri rollback genelde değil, eğer önceden plan yapmadıysanız.

Rollback'un ne anlama geldiğini açıkça belirtin. Eğer bir sütunu siliyorsanız veya verileri yerinde yeniden yazıyorsanız, gerçekçi bir yanıt isteyin: "Rollback uygulama uyumluluğunu geri sağlar, ancak orijinal veri bir snapshot olmadan kurtarılamaz." Bu dürüstlük sizi güvende tutar.

Net rollback tetikleyicileri isteyin ki bir olay sırasında tartışma çıkmasın. Örnekler:

  • Hata oranı veya gecikme 10 dakika boyunca tanımlı eşiklerin üstüne çıkarsa
  • Kritik bir sorgu planı gerilemesi (örneğin sıcak tabloda seq scan) görülürse
  • Backfill işi N saatten fazla geride kalırsa
  • Veri kontrolleri başarısız olursa (beklenmeyen null'lar, çoğaltmalar, eksik satırlar)
  • Bir migration adımı yazmaları X saniyeden fazla engelliyorsa

Tüm rollback paketini isteyin: down migration SQL (yalnızca güvenliyse), uygulama adımlarıyla uyumluluk için gerekli kod/konfigürasyon değişiklikleri ve arka plan işlerini durdurma talimatları.

Bu prompt kalıbı genelde yeterlidir:

Produce a rollback plan for this migration.
Include: down migration SQL, app config/code switches needed for compatibility, and the exact order of steps.
State what can be rolled back (schema) vs what cannot (data) and what evidence we need before deciding.
Include rollback triggers with thresholds.

Göndermeden önce hafif bir "güvenlik snapshot'u" alın ki karşılaştırma yapabilesiniz:

  • Etkilenen tabloların satır sayıları (ve ana alt kümeler)
  • Beklenen sonuçlarla birlikte birkaç örnek sorgu
  • Dokunulan sütunlar için basit agregatlar (sum, min/max)
  • Önce ve sonra elle kontrol edilecek kısa bir ID listesi

Ayrıca ne zaman geri dönmemeniz gerektiğini belirtin. Eğer yalnızca nullable bir sütun eklediyseniz ve uygulama dual-write yapıyorsa, ileri yönde bir düzeltme (hotfix kodu, backfill'i durdurup yeniden başlatma) genelde geri almaktan daha güvenlidir.

AI destekli migration'larda sık yapılan hatalar

AI hızlı SQL yazabilir, ama production veritabanınızı göremez. Çoğu hata prompt belirsiz olduğunda ve model boşlukları doldurduğunda ortaya çıkar.

Yaygın tuzak, mevcut şemayı atlamaktır. Tablo tanımını, indeksleri ve kısıtları yapıştırmazsanız, SQL olmayan kolonlara hedeflenebilir veya uniqueness kuralını kaçırıp backfill'i kilit-ağır bir işe dönüştürebilir.

Başka bir hata expand, backfill ve contract'ı tek deploy'ta paketlemektir. Bu kaçış yolunuzu kaldırır. Backfill uzun sürerse veya yarıda hata verirse, uygulama final durumu bekliyorsa sıkışırsınız.

En sık görülen sorunlar:

  • İdempotent olmayan ve ilerleme takibi olmayan backfill'ler
  • Veri temizlenmeden önce NOT NULL, UNIQUE veya foreign key eklemek
  • Kilit zaman aşımı veya statement timeout olmadan uzun süren transaction'lar
  • Doğrulama sorgularının olmaması, bu yüzden sorunların kullanıcılar ortaya çıkana kadar gizlenmesi

Somut örnek: "bir kolonu yeniden adlandır ve uygulamayı güncelle." Eğer üretilen plan yeniden adlandırma ve backfill'i tek bir transaction'da yapıyorsa, yavaş bir backfill kilit tutar ve canlı trafiği bozar. Daha güvenli bir prompt küçük partiler, açık zaman aşımı ve kaldırmadan önce doğrulama sorguları zorunlu kılmalıdır.

Göndermeden önce staging'de neyi doğrulamalısınız

Staging, küçük dev veritabanında hiç ortaya çıkmayan sorunları bulduğunuz yerdir: uzun kilitler, sürpriz null'lar, eksik indeksler ve unutulan kod yolları.

Önce migration sonrası şemanın planla eşleştiğini kontrol edin: sütunlar, tipler, varsayılanlar, kısıtlar ve indeksler. Hızlı bir göz atma yeterli değildir. Bir eksik indeks güvenli backfill'i yavaş bir felakete çevirebilir.

Ardından migration'ı gerçekçi bir veri kümesine karşı çalıştırın. İdeali production'un yakın tarihli bir kopyasıdır (gizli alanlar maskelerek). Bunu yapamıyorsanız, en azından production hacmini ve hotspot'ları (büyük tablolar, geniş satırlar, yoğun indeksli tablolar) eşleştirin. Her adım için zaman kaydı alın ki production'da ne bekleyeceğinizi bilin.

Kısa bir staging kontrol listesi:

  • Şema planla eşleşiyor mu (sütunlar, tipler, kısıtlar, indeksler)
  • Gerçekçi veri hacminde zamanlamalar kaydedildi mi
  • Uyumluluk test edildi: eski uygulama yeni şemayla ve yeni uygulama eski şemayla (plan böyle diyorsa)
  • Doğrulama sorguları çalıştırıldı: null oranları, satır sayıları, yeni FK'lar için orphan kontrolü, örnek okuma
  • Çalışma zamanı sinyalleri izlendi: kilitler, deadlock'lar, timeout'lar, yavaş sorgular

Son olarak, sadece SQL değil gerçek kullanıcı akışlarını test edin. Oluşturma, güncelleme ve okuma işlemlerini çalıştırın. Eğer expand/contract planı varsa, her iki şemanın final temizliğe kadar çalıştığını doğrulayın.

Kullanıcıları bozmadan bir kolonu değiştirme: gerçekçi örnek

Add a rollback safety net
Use snapshots so you can recover quickly if a schema change behaves badly.
Take Snapshot

Diyelim users.name sütununda "Ada Lovelace" gibi tam isimler saklıyorsunuz. first_name ve last_name istiyorsunuz ama signup, profil veya admin ekranlarını değişiklik sırasında bozmak istemiyorsunuz.

Önce hiçbir kod değişikliği olmasa bile güvenli olacak bir expand adımıyla başlayın: nullable sütunları ekleyin, eski sütunu tutun ve uzun kilitlerden kaçının.

ALTER TABLE users ADD COLUMN first_name text;
ALTER TABLE users ADD COLUMN last_name text;

Sonra uygulama davranışını her iki şemayı da destekleyecek şekilde güncelleyin. Sürüm 1'de uygulama yeni sütunları varsa onlardan okur, yoksa name'e düşer ve yazma sırasında her iki yere de yazar ki yeni veriler tutarlı kalsın.

Ardından backfill gelir. Her çalıştırmada küçük bir parça güncelleyen, ilerlemeyi kaydeden ve güvenle durdurulup yeniden başlatılabilen bir batch işi çalıştırın. Örneğin: first_name null olanları ID sırasına göre 1.000'erlik bloklarla güncelleyin ve kaç satır değiştiğini loglayın.

Kuralları sıkılaştırmadan önce staging'de doğrulayın:

  • Yeni kayıtlar first_name ve last_name dolduruyor ve yine name de set ediliyor
  • Mevcut kullanıcılar yalnızca name var olsa bile doğru görüntüleniyor
  • Backfill durdurulup yeniden başlatılabiliyor, tekrar tekrar çalıştırılabilir
  • Backfill tamamlandıktan sonra beklenmeyen null kalmadı
  • users üzerindeki temel sorgular belirgin şekilde yavaşlamadı

Sürüm 2 okumaları yalnızca yeni sütunlara çevirir. Ancak bunun ardından kısıtları (ör. SET NOT NULL) eklemeli ve name'i kaldırmalısınız; bunlar ayrı bir deploy olmalı.

Rollback için sıkıcı kalın. Geçiş sırasında uygulama name okumaya devam etsin ve backfill durdurulabilir olsun. Sürüm 2'yi geri almak gerekirse, okumaları tekrar name'e çevirin ve yeni sütunları olduğu gibi bırakın.

Sonraki adımlar: prompt'larınızı tekrarlanabilir bir migration rutinine dönüştürün

Her değişikliği küçük bir runbook gibi ele alın. Amaç mükemmel prompt değil; doğru detayları zorlayan bir rutin: şema, kısıtlar, çalışma planı ve rollback.

Her migration isteğinin standart olarak içermesini zorunlu kılın:

  • Geçerli şema ve tam değişiklik (tablolar, sütunlar, indeksler)
  • Kısıtlar ve trafik bilgileri (tablo büyüklüğü, yazma hızı, izin verilen downtime)
  • Yayın sırası (expand, uygulama deploy, backfill, contract)
  • İlerlemeyi nasıl gözlemleyeceğiniz (sorgular/metrikler, beklenen süre)
  • Rollback adımları (önce neyi geri almalı, hangi veri geride kalabilir)

Her adımın sahibini dağıtın ki "herkes başkası yaptı sanıyordu" durumu olmasın: geliştiriciler prompt ve migration kodundan sorumlu olsun, ops production zamanlaması ve izlemeden sorumlu olsun, QA staging davranışı ve kenar durumları doğrulasın, ve bir kişi son go/no-go kararı versin.

Chat üzerinden uygulama inşa ediyorsanız, herhangi bir SQL üretmeden önce diziyi planlamak yardımcı olur. Koder.ai kullanan ekipler için Planning Mode bu sırayı yazmak için doğal bir yer olabilir ve snapshotlar ile rollback blast radius'u azaltabilir.

Gönderdikten sonra, bağlam tazeyken contract cleanup'i hemen planlayın ki eski sütunlar ve geçici uyumluluk kodu aylarca kalmasın.

SSS

Why do PostgreSQL schema changes break production even when the SQL looks simple?

A schema change is risky when app code, database state, and deployment timing stop matching.

Common failure modes:

  • Old app code hits a new column/constraint and crashes
  • A migration takes a strong lock on a busy table and requests time out
  • A “small” change rewrites or drops data quietly
  • Index/constraint work runs longer than expected and causes slow queries
What’s the safest default way to change a schema without downtime?

Use an expand/contract approach:

  • Expand: add new nullable columns/tables/indexes in a compatible way
  • Compatibility: deploy app code that can read/write both shapes
  • Backfill: copy data in small batches with checkpoints
  • Contract: tighten constraints and drop old fields only after a full release cycle

This keeps both old and new app versions working during rollout.

What extra risks do AI-generated migrations introduce?

Because the model can generate SQL that is valid but unsafe for your workload.

Typical AI-specific risks:

  • Guessing table/column names or missing an important constraint
  • Proposing a single “big bang” migration that removes your rollback options
  • Ignoring lock behavior, transaction limits, and long-running index builds
  • Hand-waving rollback (especially when data is transformed or removed)

Treat AI output as a draft and require a run plan, checks, and rollback steps.

What should I paste into my prompt so Claude Code doesn’t guess?

Include only the facts the migration depends on:

  • Relevant CREATE TABLE snippets (plus indexes, FKs, UNIQUE/CHECK constraints, triggers)
  • Postgres version and how migrations run (single transaction vs multi-step)
  • Scale: row counts, table size, write rate, peak traffic
  • How the app uses the data (critical reads/writes/jobs)
Should I combine schema changes and backfills in one migration?

Default rule: separate them.

A practical split:

  • Migration 1: schema expand (new columns/tables, maybe NOT VALID constraints)
  • App deploy: compatibility code (read-fallback or dual-write)
  • Backfill job: batched updates with progress tracking
  • Migration 2: contract (validate constraints, set NOT NULL, drop old columns)

Bundling everything makes failures harder to diagnose and roll back.

How do I add a new column with a default without causing long locks?

Prefer this pattern:

  1. ADD COLUMN ... NULL with no default (fast)
  2. Backfill in batches
  3. Set a default for new rows
  4. Add NOT NULL only after verification

Adding a non-null default can be risky on some versions because it may rewrite the whole table. If you need an immediate default, ask for lock/runtime notes and a safer fallback.

When should I use CREATE INDEX CONCURRENTLY, and what’s the catch?

Ask for:

  • CREATE INDEX CONCURRENTLY for large/hot tables
  • A note that it can’t run inside a transaction block (your tooling must support that)
  • Expected runtime and what to monitor (lock waits, query latency)

For verification, include a quick check that the index exists and is used (for example, compare an EXPLAIN plan before/after in staging).

What’s the safest way to add a foreign key on a large table?

Use NOT VALID first, then validate later:

  • Add the FK as NOT VALID so the initial step is less disruptive
  • Run VALIDATE CONSTRAINT in a separate step when you can watch it

This still enforces the FK for new writes, while letting you control when the expensive validation happens.

How do I prompt for a backfill that won’t melt production and can resume?

A good backfill is batched, idempotent, and restartable.

Practical requirements:

  • Batch by primary key ranges or time windows
  • Update only rows that still need work (e.g., WHERE new_col IS NULL)
  • Keep batches in short transactions; optionally sleep between batches
What does a realistic rollback plan look like for schema changes?

Default rollback goal: restore app compatibility fast, even if data isn’t perfectly undone.

A workable rollback plan should include:

  • Whether DOWN SQL is truly safe; if not, a runbook instead
  • The exact order: stop/pause backfill jobs, deploy app code change, then schema steps
  • Clear rollback triggers (error rate, latency, lock waits, failed data checks)
  • A statement of what can be rolled back (schema) vs what can’t (data)

Often the safest rollback is switching reads back to the old field while leaving new columns in place.

İçindekiler
PostgreSQL şema değişikliğini riskli yapan nedir?Herhangi bir prompt yazmadan önce uymanız gereken güvenlik kurallarıClaude Code'u gerçeğe bağlamak için prompt'a neler eklemelisinizExpand/contract basitçe (ve ne zaman kullanılmalı)Expand/contract migration'lar için güvenli bir prompt şablonuYaygın şema işlemleri ve daha güvenli SQL istemek için nasıl prompt atılırYavaş, dengeli ve kurtarılabilir backfill'ler için prompt atmaGerçekçi rollback planları nasıl istenirAI destekli migration'larda sık yapılan hatalarGöndermeden önce staging'de neyi doğrulamalısınızKullanıcıları bozmadan bir kolonu değiştirme: gerçekçi örnekSonraki adımlar: prompt'larınızı tekrarlanabilir bir migration rutinine dönüştürünSSS
Paylaş
Koder.ai
Build your own app with Koder today!

The best way to understand the power of Koder is to see it for yourself.

Start FreeBook a Demo
  • Hard constraints (no downtime, avoid table rewrites, lock limits)
  • Deliverables: UP SQL + verification queries + rollback plan + runbook
  • This prevents guessing and forces the right ordering.

  • Track progress (last processed ID, rows updated, start time)
  • Ensure the app stays correct while backfill runs (dual-write, trigger, or read-fallback)
  • This makes backfills survivable under real traffic.