Azure Cosmos DB Design Patterns: Çalışan Örnekler
Azure Cosmos DB gibi NoSQL veritabanlarında iyi bir veri modeli, çoğu zaman birkaç temel desenin doğru uygulanmasına bağlıdır: bölümlemeyi (partitioning) nasıl kurduğunuz, sürüm yönetimini nasıl ele aldığınız, işi nasıl dağıttığınız ve eş zamanlı yazıcıların birbirine nasıl çarpmadığı. Microsoft’un yakın zamanda büyük bir güncelleme aldığı Azure Cosmos DB Design Patterns deposu, tam olarak bu soruların üzerine gidiyor. Her deseni okumak yerine çalıştırıp izlemenizi sağlıyor.
Deponun Felsefesi: Okumak Değil, Görmek
Klasik desen kataloglarının aksine bu depoda her desen; küçük, odaklı ve çalıştırılabilir bir örnek olarak geliyor. Her örnekte interaktif bir Blazor tabanlı web arayüzü var. Yani dağıtık bir kilidin fencing token ile nasıl çalıştığını yalnızca okumuyor; birkaç worker başlatıp aralarındaki yarışı canlı izleyebiliyor, kilidi tutan işlemi çökertip TTL üzerinden otomatik release’i gözlemleyebiliyorsunuz.
Depo üç temel prensip üzerine kurulu:
- Emulator öncelikli: Her örnek, Azure Cosmos DB Linux (vNext) emülatörü üzerinde tamamen yerelde çalışıyor. Abonelik, hesap veya anahtar gerekmiyor;
docker compose up -dvedotnet runyeterli. - Her desen için interaktif web arayüzü: Soyut kavramlar, tıklanabilir ve kırılabilir bir yüzeyde somutlaşıyor. “Neden önemli” notları sayfada yer alıyor.
- Güvenli ve opsiyonel bulut: Örneği Azure’a taşımak istediğinizde, Azure Developer CLI (
azd) şablonu ile Microsoft Entra ID ve managed identity temelli, keyless bir dağıtım tek komutla kuruluyor.
Yeni Eklenen Beş Desen
1. Vector Search
Azure Cosmos DB’nin yerleşik vektör indeksleme özelliği ve VectorDistance() fonksiyonu ile operasyonel veri üzerinde anlamsal arama kurmayı gösteriyor. Örneğin ayırt edici tarafı, metinleri küçük bir yerel model ile gömüyor olması: API anahtarı ya da harici servis gerekmiyor. Bu sayede embedding kullanan bir uygulamayı, foundation model dağıtmadan veya GitHub secrets içine anahtar koymadan CI/CD sürecine dahil edebiliyorsunuz.
2. Loop-Safe Change Feed
Change feed ile bir dokümandan değer türetip aynı dokümana geri yazdığınızda, yazma işleminin feed’i tekrar tetiklemesi klasik bir tuzaktır. Bu örnek standart çözümü uyguluyor: kaynak alanların bir hash‘i saklanıyor, hash değişmediyse gelen değişiklik atlanıyor. Böylece gerçek bir düzenleme başına tam olarak bir zenginleştirme ve bir “echo” atlaması oluyor; döngü sınırlı kalıyor. Arayüzde her dokümana metinden türetilmiş bir identicon üretiliyor ve “zenginleştirme yazma” ile “atlanan echo” sayaçları birlikte artıyor; bu da döngü güvenliğini görünür kılıyor.
3. Hierarchical Partition Key
Tek bir bölüm anahtarı yetmediğinde, hiyerarşik (alt) bölümleme veriyi birden fazla anahtar seviyesine dağıtırken ilişkili öğeleri bir arada tutmayı sağlıyor. Örnek gerçekçi bir çok kiracılı (multi-tenant) modeli işliyor ve doğru bölümleme stratejisinin maliyet ile performansa etkisini gösteriyor.
4. Transactional Outbox
Bir sipariş oluşturmak hem durumu değiştirmeyi hem de başka sistemlerin tükettiği bir olayı yayımlamayı gerektirir. Bunları iki ayrı yazma ile yapmak “dual-write” problemidir; arada bir çökme olursa olay kaybolur. Bu örnekte sipariş ve olay tek bir atomik TransactionalBatch içinde yazılıyor, ardından olay change feed üzerinden aktarılıyor. Uygulamanın commit’ten hemen sonra ölmesi durumunda bile olay kaybolmuyor. Arayüzdeki bir “crash-toggle” alanı ile naif yaklaşımın olay kaybettiğini, outbox’ın ise kaybetmediğini karşılaştırabiliyorsunuz.
5. Patch API (Partial Document Update)
Tek bir alanı güncellemek genellikle “read-modify-write” gerektirir: dokümanın tamamını okuyup değiştirip yeniden yazmak. Patch API ise yalnızca yapılacak işlemi gönderir; daha ucuz, düşük gecikmeli ve farklı servisler farklı alanları güncellediğinde kayıp güncellemeye izin vermez. Örnek, üç yollu bir eş zamanlılık yarışını emülatör üzerinde ölçümlerle karşılaştırıyor:
| Yaklaşım | Sonuç | Çakışma | RU |
|---|---|---|---|
| Read-modify-write, ETag yok | Bir güncelleme kayboluyor | 0 | 4 |
| Read-modify-write + ETag | Yeniden okuma + retry sonrası doğru | 1 | 6 |
| Patch | Doğru | 0 | 2 |
Buradaki dürüst çıkarım şu: ETag, read-modify-write’ı doğru hale getirir; ama dokümanın tamamını koruduğu için farklı alanlara dokunan iki servi hâlâ gereksiz bir 412 çakışmasıyla karşılaşır ve retry maliyeti öder. Patch bu sorunu tamamen ortadan kaldırıyor.
Baştan Yazılan Distributed Lock Örneği
Distributed Lock deseni depoda zaten vardı, ancak bu döngüde tümüyle yeniden yazıldı ve canlı bir web playground kazandı. “Görerek anlama” felsefesini en iyi bu örnek özetliyor: gördüğünüz her acquire, renewal ve release işlemi Azure Cosmos DB üzerinde gerçek bir operasyon.
Aynı anda yalnızca tek worker kilidi tutuyor. Kilidi tutan, bir fencing token taşıyor; korunan kaynak yalnızca güncel token’ı kabul ediyor, dolayısıyla eski/stale bir yazıcının güncellemeleri reddediliyor. Kilit tutucusu çökerse TTL üzerinden lease otomatik serbest kalıyor; deadlock olmuyor. Bir worker’ın “Work” süresini TTL’den uzun tutup auto-renew’in kirayı canlı tuttuğunu; auto-renew’i kapatıp lease’in iş ortasında sona erdiğini, başka bir worker’ın devraldığını ve eski holder’ın yazmalarının fencing token tarafından reddedildiğini tarayıcıda gözlemleyebiliyorsunuz.
Kaputun Altındaki Kalite İyileştirmeleri
Yeni desenlerle birlikte deponun altyapısı da güncellendi:
- Her örnekte .NET 10 kullanılıyor.
- CI üzerinde emülatör tabanlı entegrasyon testleri çalışıyor. Test seti her pull request’te Cosmos DB Linux emülatörüne karşı, secret olmadan koşuyor; yani desenlerin gerçekten çalıştığı doğrulanmış oluyor.
- Her örnek için keyless
azddağıtımı: managed identity, local key auth kapalı, hassas veri saklanmıyor. - README’ler birleşik ve sadeleştirilmiş bir şablona geçti: kodu al → konfigüre et → yerelde çalıştır → isteğe bağlı olarak dağıt. Tekrar eden portal talimatları yerine ortak bir kurulum kılavuzuna bağlanıyor.
Kısa Yoldan Deneme
git clone https://github.com/Azure-Samples/cosmos-db-design-patterns.git
cd cosmos-db-design-patterns
docker compose up -d
# yerel emülatörü başlatır
cd loop-safe-change-feed/source/Website
dotnet run
# yazdırılan URL'i açınHerhangi bir desen klasörünü seçip web arayüzünü çalıştırabilir, tıklayarak deneyebilirsiniz. Bölümleme stratejisi belirlerken, güvenilir olay yayınlama akışları kurarken veya vektör aramaya yönelirken, gerçek bir uygulamaya geçmeden önce davranışı görebileceğiniz küçük ve dürüst örnekler artık elinizin altında.
Kaynaklar ve İleri Okuma
- Orijinal duyuru: See our new Azure Cosmos DB Design Patterns (Mark Brown)
- Azure-Samples/cosmos-db-design-patterns GitHub deposu
- Azure Cosmos DB Linux (vNext) Emulator dokümantasyonu
- Azure Cosmos DB Vector Search
- Hierarchical Partition Keys
- Partial Document Update (Patch API)
- Azure Cosmos DB vNext Emulator: Yerelde Gerçek Gibi Test Etmek
- Azure Cosmos DB’de Silinenleri Görmek: Change Feed’in Sessiz Gücü
- Azure Cosmos DB’de Partition Key Değiştirmek: Artık Daha Az Acı Veriyor
20+ yıl deneyimli Azure Solutions Architect. Microsoft sertifikalı bulut mimari ve DevOps danışmanı. Azure, yapay zekâ ve bulut teknolojileri üzerine Türkçe teknik içerikler üretiyor.
Yorum gönder