Kesintisiz Şema Değişikliği — Genişlet, Taşı, Daralt

Bir koridorun adını değiştirmek küçük bir iş gibi görünür. Eski haritayla gelenler için ise değildir.

Küçük bir iyileştirme: name sütununun adı full_name oldu. Yeni sürüm yayılırken bir şeyler ters gitti; üstelik eskisine dönmek de mümkün değildi.

Eski kod ve yeni tablo bir arada

Rolling deploy?Terimin tanımını açrolling deployUygulama kopyalarını tek tek yeni sürüme geçiren dağıtım. Bir süre eski ve yeni kod aynı veritabanıyla birlikte çalışır.Sözlükte gör →, pod’ları tek tek yeni sürüme geçirir. Bir süre eski ve yeni kod yan yana çalışır. Migration uygulama açılırken (ör. Flyway ile) çalışıyorsa, şema ilk yeni pod’la birlikte değişir; eski pod’lar hâlâ trafik alırken.

Bu yüzden tek bir kural var: her migration, bir önceki kod sürümüyle de çalışmalıdır. Kolon eklemek bu kurala uyar; kolon silmek ya da adını değiştirmek uymaz.

Genişlet, taşı, daralt

Genişlet-daralt?Terimin tanımını açgenişlet-daraltUyumsuz bir şema değişikliğini, her biri önceki kodla da çalışan adımlara bölmek: yeni yapıyı ekle, veriyi taşı, kodu geçir, eski yapıyı kaldır.Sözlükte gör → değişikliği uyumlu adımlara böler:

1. Genişlet: yeni kolonu ekle; kod iki kolona yazar, eskisinden okur.
2. Doldur: eski satırları küçük parçalar hâlinde kopyala (backfill?Terimin tanımını açbackfillYeni eklenen bir kolonu ya da tabloyu mevcut satırlar için geriye dönük doldurmak. Büyük tablolarda küçük parçalar hâlinde yapılır.Sözlükte gör →).
3. Okumaları taşı: kod yeni kolondan okur, hâlâ ikisine yazar.
4. Daralt: eski kolonu okuyan kod kalmayınca yazmayı bırak, sonra kolonu sil.

Bir bankanın eski transfer tablosunda tutar double olarak saklanmış. Onu numeric’e taşımak, bu dört adımı gerçek bir tabloda izlemek için güzel bir fırsat.

1
-- Expand. Old pods keep reading and writing "amount"; nothing they use changes.
2
SET LOCAL lock_timeout = '5s';   -- give up rather than queue every query behind a long transaction
3

4
ALTER TABLE transfer ADD COLUMN amount_exact numeric(19,2);   -- nullable: no rewrite, brief lock
5

6
-- A later release stops writing the old column; it must not be NOT NULL by then.
7
ALTER TABLE transfer ALTER COLUMN amount DROP NOT NULL;

1
@Entity
2
@Table(name = "transfer")
3
class Transfer {
4

5
    @Id
6
    private Long id;
7
    private String fromIban;
8
    private String toIban;
9
    private String currency;
10

11
    @Column(name = "amount")                 // legacy double precision column, still read by old pods
12
    private Double legacyAmount;
13

14
    @Column(name = "amount_exact", precision = 19, scale = 2)
15
    private BigDecimal amount;
16

17
    // Expand phase: write both columns so old and new pods see the same transfer.
18
    void setAmount(BigDecimal value) {
19
        this.amount = value.setScale(2, RoundingMode.UNNECESSARY);   // refuses fractions of a kuruş
20
        this.legacyAmount = this.amount.doubleValue();
21
    }
22

23
    // Reads the old column until the backfill is done; the next release reads amount_exact.
24
    BigDecimal amount() {
25
        return BigDecimal.valueOf(legacyAmount).setScale(2, RoundingMode.HALF_EVEN);
26
    }
27
}

1
@Component
2
class TransferAmountBackfill {
3

4
    private static final int BATCH = 5_000;
5
    private final JdbcTemplate jdbc;
6

7
    TransferAmountBackfill(JdbcTemplate jdbc) {
8
        this.jdbc = jdbc;
9
    }
10

11
    // Runs once every pod writes both columns. No surrounding transaction:
12
    // each UPDATE commits on its own, so row locks are short.
13
    void run() {
14
        long maxId = jdbc.queryForObject("SELECT coalesce(max(id), 0) FROM transfer", Long.class);
15
        for (long from = 0; from < maxId; from += BATCH) {
16
            jdbc.update("""
17
                    UPDATE transfer
18
                       SET amount_exact = round(amount::numeric, 2)
19
                     WHERE id > ? AND id <= ? AND amount_exact IS NULL
20
                    """, from, from + BATCH);
21
        }
22
    }
23

24
    // It could also be one UPDATE over the whole table. On a large table that is one
25
    // long transaction: every touched row stays locked until the end, and all the
26
    // dead row versions pile up at once.
27
}

1
-- Contract. Ships in a later deploy, once no running version reads or writes "amount".
2
SET LOCAL lock_timeout = '5s';
3

4
ALTER TABLE transfer DROP COLUMN amount;   -- catalog-only: a brief exclusive lock, no rewrite
5

6
-- Making amount_exact NOT NULL is its own small step on a big table:
7
-- CHECK (amount_exact IS NOT NULL) NOT VALID, then VALIDATE CONSTRAINT in a separate
8
-- migration, then SET NOT NULL, which PostgreSQL 12+ proves from that CHECK without a scan.

Kendin gör

1. Varsayılanla oynat. Tek adımda yeniden adlandırma: eski pod’lar düştü, geri dönüş kapandı.
2. Yöntemi “kesintisiz” yap. Dört adım, üç deploy, sıfır hata.
3. Değişikliği index yap, “tek adımda”. Yazmalar durdu, istekler timeout aldı.
4. “Kesintisiz” seç. Index yazmaları engellemeden oluştu.

Tabloyu kilitleyen değişiklikler

Bazı şema değişiklikleri tabloyu kısa ya da uzun süre kilitler. Büyük tablolarda online karşılıklarını kullan:

Kısa kilit alan bir ALTER TABLE bile, uzun bir transaction’ın arkasında beklerken arkasındaki bütün sorguları bekletir. PostgreSQL’de migration’dan önce SET lock_timeout ile beklemeye bir üst sınır koy.

Tuzaklar

Tek dev UPDATE ile doldurmak. Milyonlarca satırı tek transaction’da güncellemek uzun kilitler, şişme ve dev bir geri alma demektir. Parçalara böl.

CONCURRENTLY transaction içinde. Flyway’de o migration’ı transaction dışında çalışacak şekilde ayarla; başarısız olursa geride kalan INVALID index’i temizle.

Daraltmayı unutmak. Yazılmayan ama silinmeyen kolonlar birikir ve bir gün biri onları yeniden kullanır.

Geri alınamaz migration’ı geri dönüşle birlikte düşünmemek. Kolon silindikten sonra eski koda dönmek yalnızca veriyi geri yükleyerek mümkündür.

Kendini sına