Flask’ta Veritabanı Migration Yönetimi: Güvenli, Kontrollü ve Production Uyumlu Rehber

Flask ile geliştirilen uygulamalarda veritabanı şeması statik değildir; sürekli evrilir. Yeni alanlar eklenir, bazıları kaldırılır, veri tipleri değişir. Bu değişimleri doğrudan SQL komutlarıyla veritabanında yapmak yerine migration sistemi ile yönetmek, veri bütünlüğü ve ekip çalışması açısından kritik öneme sahiptir.

1. Migration Nedir?

Migration, veritabanı şemasındaki değişikliklerin bir versiyon kontrol sistemi (Git gibi) mantığıyla:

• Versiyonlanması,

• Kayıt altına alınması,

• Geri döndürülebilir şekilde uygulanması sürecidir.

Flask dünyasında bu standart, Flask-Migrate (Alembic üzerine inşa edilmiştir) kütüphanesi ile sağlanır.

2. Temel Komutlar ve Gerçek İşlevleri

flask db init

• migrations/ klasörünü ve yapılandırma dosyalarını oluşturur.

• Kritik: Proje ömrü boyunca sadece 1 kez (başlangıçta) çalıştırılır.

flask db migrate -m "mesaj"

• SQLAlchemy modellerinizi tarar ve mevcut DB şemasıyla karşılaştırır.

• Aradaki farkı bir Python scripti olarak versions/ klasörüne yazar.

• Dikkat: Sadece plan oluşturur, veritabanında hiçbir değişiklik yapmaz.

flask db upgrade

• Hazırlanan migration scriptini veritabanına uygular.

• Uyarı: Gerçek tablo değişiklikleri ve veri riskleri bu aşamada gerçekleşir.

flask db downgrade

• Veritabanı şemasını bir önceki versiyona döndürür.

• Büyük Yanılgı: Şema geri gelse de, silinen veriler (örneğin bir kolon silindiyse) asla geri gelmez.

3. SQLite Kullanıcıları İçin Hayati İpucu: "Batch Mode"

SQLite, ALTER TABLE komutunda kısıtlıdır (doğrudan kolon silemez veya tip değiştiremez). Bu hataları önlemek için app.py veya extensions.py dosyanızda Flask-Migrate'i şu şekilde yapılandırmalısınız:

from flask_migrate import Migrate
# ...
migrate = Migrate(app, db, render_as_batch=True)

Bu ayar, SQLite üzerinde geçici tablolar oluşturarak veriyi taşıyan güvenli bir köprü kurar.

4. Veriye Etkiler ve Kritik Senaryolar

✔️ Kolon Ekleme (Güvenli)

Yeni bir kolon eklediğinizde mevcut veriler korunur. Ancak, nullable=False (boş bırakılamaz) bir kolon ekliyorsanız, mevcut satırlar için bir server_default (varsayılan değer) belirlemelisiniz.

🔥 Kolon Silme (Tehlikeli)

Koddan bir kolonu sildiğinizde ve upgrade yaptığınızda;

1. Veritabanı motoru DROP COLUMN komutunu çalıştırır.

2. O kolondaki tüm geçmiş veriler kalıcı olarak yok olur.

5. Canlı Sistemde (Production) Güvenli Stratejiler

Canlı sistemde "kırılmaları" önlemek için Backward Compatible (Geriye Uyumlu) ilerlemek gerekir.

Senaryo: Bir Kolonun İsmini Değiştirmek

Yanlış: Kolon ismini modelde değiştirip migrate & upgrade yapmak. (Veri kaybına ve uygulamanın o an çökmesine neden olur).

Doğru (Zero Downtime):

1. Ekle: Yeni isimle kolonu ekle ve migration uygula.

2. Yaz: Uygulama kodunu hem eski hem yeni kolona yazacak şekilde güncelle.

3. Taşı: Mevcut verileri eski kolondan yeniye bir script ile aktar.

4. Sil: Eski kolonu koddan ve DB'den kaldır.

6. Alembic'in Göremediği Değişiklikler

Alembic her şeyi otomatik yakalayamaz. Şu durumlarda migration dosyasını manuel düzenlemeniz gerekir:

• Kolon İsmi Değişikliği: Alembic bunu genellikle "bir kolonu sil, yenisini ekle" olarak görür. Dosyayı açıp op.drop_column ve op.add_column yerine op.alter_column kullanacak şekilde düzenlemelisiniz.

• Constraint (Kısıtlama) Değişiklikleri: Mevcut bir kolonun check kısıtlamalarını her zaman fark etmeyebilir.

7. Özet ve Profesyonel İş Akışı

1. Modeli Güncelle

2. Migration Oluştur: flask db migrate -m "açıklama"

3. Dosyayı İncele: migrations/versions/ altındaki dosyayı aç, upgrade ve downgrade fonksiyonlarını kontrol et.

4. Test Et: Önce yerelde veya staging ortamında flask db upgrade yap.

5. Canlıya Al: Production sunucusunda yedek aldıktan sonra upgrade komutunu çalıştır.

Altın Kural: Production veritabanı üzerinde işlem yapmadan önce mutlaka bir SQL yedeği (mysqldump vb.) alın. Migration sistemi bir yedekleme sistemi değil, bir versiyon kontrol sistemidir.

Kaynakça

• Flask-Migrate Documentation

• Alembic Operations Reference

• Miguel Grinberg - The Flask Mega-Tutorial