Bu yazıda, Tilt + K8s ortamında en sık karşılaşılan Flyway problemlerini, neden oluştuklarını ve bunları kalıcı olarak nasıl çözebileceğimizi ele alacağım.

Sorun Neden Oluşuyor?

Tilt ve Kubernetes tabanlı geliştirme ortamlarında Flyway hatalarının en yaygın nedenleri genellikle şu başlıklarda toplanır:

1. Checksum mismatch

Bu hata, daha önce çalıştırılmış bir migration dosyasının sonradan değiştirilmesi durumunda ortaya çıkar. Flyway, migration dosyasının içeriğini checksum ile takip eder. Eğer dosya sonradan düzenlenirse, veritabanındaki kayıt ile dosyanın güncel hali uyuşmaz.

2. Out-of-order migration

Ekip içinde iki geliştirici aynı anda migration yazdığında, örneğin biri V3, diğeri V2 oluşturursa, daha geç gelen daha küçük versiyonlu migration “out-of-order” hatasına neden olabilir.

3. Dirty database

Migration işlemi sırasında uygulama kapanırsa, pod yeniden başlarsa ya da süreç yarıda kesilirse, flyway_schema_history tablosunda başarısız kayıt kalabilir. Bu durumda veritabanı “dirty” duruma düşer ve yeni migration’lar çalışmaz.

4. Duplicate version

İki geliştiricinin aynı anda aynı versiyon numarasıyla migration oluşturması da oldukça yaygın bir problemdir. Özellikle klasik V1, V2, V3 şeklindeki sıralı yaklaşım ekip çalışmasında çakışma üretmeye çok müsaittir.

Kalıcı Çözüm: Timestamp Tabanlı Versiyonlama

Bu problemleri azaltmanın en etkili yolu, klasik sıralı versiyonlama yerine timestamp tabanlı migration isimlendirmesi kullanmaktır.

Örnek:

V20240315143000__create_product_table.sql

V20240316091500__add_tenant_id_column.sql

Bu yaklaşımın en büyük avantajı, iki geliştiricinin aynı anda migration yazsa bile versiyon çakışmasının neredeyse ortadan kalkmasıdır. Ayrıca migration sıralaması da çok daha doğal ve izlenebilir hale gelir.

Takım içinde bir convention olarak şu format benimsenmelidir:


V{yyyyMMddHHmmss}__{description}.sql

Örneğin:


V20240315143022__add_product_status_column.sql

application.yml Konfigürasyonu Nasıl Olmalı?

Flyway yapılandırmasında bazı ayarlar özellikle lokal geliştirme ortamında çok faydalıdır. Ancak production ortamında daha kontrollü kullanılmalıdır.

Örnek yapılandırma:


spring:
  flyway:
    enabled: true
    locations: classpath:db/migration
    table: flyway_schema_history
    default-schema: ${SERVICE_SCHEMA}
    out-of-order: true
    baseline-on-migrate: true
    validate-on-migrate: true
    repair-on-migrate: false

Bu ayarlar ne işe yarar?

out-of-order: true
Lokal ortamda eski versiyonlu migration’ların da uygulanmasına izin verir. Özellikle ekipte paralel geliştirme varsa faydalıdır. Ancak production’da dikkatli kullanılmalıdır.

baseline-on-migrate: true
İlk kurulum sırasında mevcut veritabanını baseline alarak migration sürecini başlatır.

validate-on-migrate: true
Migration dosyaları ile veritabanı geçmişini her çalışmada doğrular. Bu ayarın açık kalması oldukça önemlidir.

repair-on-migrate: false
Production ortamında otomatik repair riskli olabilir. Bu yüzden kapalı tutulması daha güvenlidir.

Eğer tüm servisler aynı PostgreSQL instance’ını kullanıyor ama farklı schema’larda çalışıyorsa, default-schema tanımını açıkça vermek kritik önem taşır. Böylece her servis kendi migration geçmişini kendi schema’sında yönetir.

Dirty Database Problemi Nasıl Çözülür?

Dirty state oluştuğunda Flyway yeni migration’ları çalıştırmayı durdurur. Bu durumda genellikle çözüm repair komutudur.

Bu işlemi ekip için standart hale getirmek adına, Kubernetes tarafında bir repair job ya da Tilt komutu tanımlamak iyi bir yaklaşımdır.

Kubernetes Job Örneği


apiVersion: batch/v1
kind: Job
metadata:
  name: flyway-repair-content-api
spec:
  template:
    spec:
      containers:
        - name: flyway-repair
          image: flyway/flyway:10
          args:
            - repair
          env:
            - name: FLYWAY_URL
              value: jdbc:postgresql://postgres:5432/content_db
            - name: FLYWAY_USER
              valueFrom:
                secretKeyRef:
                  name: db-secret
                  key: username
            - name: FLYWAY_PASSWORD
              valueFrom:
                secretKeyRef:
                  name: db-secret
                  key: password
      restartPolicy: Never

Bu yapı sayesinde gerektiğinde ilgili servis için repair işlemi tek bir job ile tetiklenebilir.

Tilt İçinde Repair Tetiklemek

Tilt kullanan ekiplerde, repair sürecini kolaylaştırmak için Tiltfile içine özel komutlar eklenebilir.

Örnek:


local_resource(
  'repair-content-api',
  cmd='kubectl apply -f k8s/jobs/flyway-repair-content-api.yaml',
  labels=["flyway-repair"]
)

local_resource(
  'repair-warehouse-api',
  cmd='kubectl apply -f k8s/jobs/flyway-repair-warehouse-api.yaml',
  labels=["flyway-repair"]
)

Bu sayede geliştirici gerektiğinde ilgili servisin repair job’unu kolayca tetikleyebilir.

Takım İçin En Pratik Yol: Makefile

Ekip içinde herkesin aynı komutlarla aynı işlemleri yapabilmesi için en temiz çözümlerden biri Makefile kullanmaktır. Özellikle repair gibi operasyonlar tek komutla erişilebilir hale gelir.

Aşağıda web sitende paylaşabileceğin şekilde temizlenmiş bir Makefile örneği bulunuyor:


SERVICE ?= content-api

.PHONY: db-repair db-repair-all db-status

# Tek servis için Flyway repair job çalıştır
db-repair:
	kubectl apply -f k8s/jobs/flyway-repair-$(SERVICE).yaml
	@echo "✅ Repair triggered for $(SERVICE)"

# Tüm servisler için repair işlemini sırayla tetikle
db-repair-all:
	$(MAKE) db-repair SERVICE=content-api
	$(MAKE) db-repair SERVICE=warehouse-api
	$(MAKE) db-repair SERVICE=order-api

# İlgili servis için migration durumunu kontrol et
db-status:
	kubectl exec deploy/$(SERVICE) -- \
	  java -jar app.jar --spring.flyway.validate-on-migrate=false

Kullanım örnekleri

Tek servis repair etmek için:


make db-repair SERVICE=content-api

Tüm servisler için repair tetiklemek için:


make db-repair-all

Migration durumunu kontrol etmek için:


make db-status SERVICE=order-api

Bu yapı, hem yeni ekip üyeleri için öğrenme sürecini kolaylaştırır hem de operasyonel hataları azaltır.

Duplicate Version Problemi İçin Pre-commit Hook

Migration versiyon çakışmalarını daha commit aşamasında yakalamak için basit bir Git pre-commit hook kullanılabilir.

Örnek:


#!/bin/bash

DUPLICATES=$(ls src/main/resources/db/migration/ | grep -oP 'V\d+' | sort | uniq -d)

if [ -n "$DUPLICATES" ]; then
  echo "❌ Duplicate Flyway version detected: $DUPLICATES"
  exit 1
fi

Bu script, aynı versiyon numarasına sahip birden fazla migration dosyası varsa commit’i engeller. Böylece sorun daha repo’ya gitmeden yakalanmış olur.

Ekip Convention’ları Neden Şart?

Teknik çözüm kadar önemli olan bir diğer konu da takım disiplini. Flyway problemlerinin büyük kısmı doğru convention’lar ile daha oluşmadan önlenebilir.

README’ye şu kurallar net biçimde eklenebilir:

Migration Kuralları

Yeni migration yazarken

Önce git pull --rebase yap
Dosya adını şu formatta ver:
V{yyyyMMddHHmmss}__{ne_yaptın}.sql
Mevcut migration dosyasını asla düzenleme
Değişiklik gerekiyorsa yeni migration oluştur

Hata aldığında

Dirty state varsa make db-repair SERVICE=<servis-adı> çalıştır
Checksum mismatch varsa düzenlenen eski dosyayı geri al ve gerekiyorsa repair çalıştır
Out-of-order problemi varsa ilgili ortam konfigürasyonunu kontrol et

Bu kurallar küçük görünse de ekip içinde ciddi fark yaratır.

Önerilen Akış

Sağlıklı bir migration süreci için ekip akışı şu şekilde olabilir:

Geliştirici migration eklemeden önce git pull --rebase yapar
Yeni migration dosyasını timestamp tabanlı isimle oluşturur
Mevcut migration dosyalarına dokunmaz
Tilt reload sonrası migration otomatik çalışır
Hata varsa make db-repair ile recovery yapılır
Gerekirse migration durumu db-status ile kontrol edilir

Bu akış, özellikle çok servisli ve ekipli yapılarda Flyway kaynaklı sorunları belirgin biçimde azaltır.

Sonuç

Tilt + Kubernetes ortamında Flyway kullanırken yaşanan sorunlar çoğunlukla teknik bir bug’dan çok süreç ve convention eksikliğinden kaynaklanır. Özellikle şu dört başlık en kritik önlemlerdir:

Timestamp tabanlı migration versiyonlama kullanmak
Lokal ve production için Flyway ayarlarını bilinçli yönetmek
Dirty state için standart repair akışı oluşturmak
Takım içinde net migration kuralları belirlemek

Kısacası, Flyway problemlerini tamamen ortadan kaldırmak her zaman mümkün olmayabilir; ancak doğru yapılandırma, doğru araçlar ve iyi tanımlanmış ekip kuralları ile bu problemleri oldukça yönetilebilir hale getirmek mümkündür.