D1

D1 nedir?

Bir Worker 330’dan fazla şehirde çalışır; klasik bir ilişkisel veritabanı tek bir bölgede, önünde sunucusuz iş yüklerinin hızla tükettiği bir bağlantı havuzuyla durur.

D1 bu ikilemi ortadan kaldırır. Resmî tanım:

“D1 is Cloudflare’s managed, serverless database with SQLite’s SQL semantics, built-in disaster recovery, and Worker and HTTP API access.”

Bağlantı yönetmezsin, kapasite planlamazsın ve sıfıra ölçeklenir: “You are not billed for hours or capacity units. If you are not running queries against your database, you are not billed for compute.”

Nasıl çalışır?

SQLite temeli

D1 “leverages SQLite’s query engine” ve “compatible with most SQLite’s SQL convention”. Desteklenen uzantılar: FTS5 (tam metin arama), JSON uzantısı, matematik fonksiyonları ve bazı PRAGMA ifadeleri.

Her veritabanı bir Durable Object üzerine kuruludur ve tek iş parçacıklıdır:

“Each individual D1 database is inherently single-threaded, and processes queries one at a time.”

Pratik sonuç, Cloudflare’in kendi hesabıyla:

Hazırlanmış ifadeler ve batch

const stmt = env.DB.prepare("SELECT ad, eposta FROM kullanicilar WHERE kiraci_id = ?1 LIMIT 50");
const { results } = await stmt.bind(kiraciId).all();

Yalnızca sıralı (?NNNN) ve anonim (?) parametreler desteklenir; isimli parametreler henüz yok.

batch() ağ turlarını azaltır ve bir transaction’dır:

“Batched statements are SQL transactions. If a statement in the sequence fails, then an error is returned for that specific statement, and it aborts or rolls back the entire sequence.”

Sessions API ve read replication

Üç oturum biçimi:

Tutarlılık modeli: sequential consistency. Dört garanti sunar: monotonic reads, monotonic writes, writes follow reads, ve read-my-own-writes.

Replica bölgeleri: ENAM, WNAM, WEUR, EEUR, APAC, OC.

Replica gecikmesi için yayımlanmış bir sayısal üst sınır yoktur; doküman yalnızca “a read replica may be arbitrarily out of date” diyor. Güvence bookmark mekanizmasıdır, zaman garantisi değil.

Time Travel

“Time Travel is D1’s approach to backups and point-in-time-recovery, and allows you to restore a database to any minute within the last 30 days.”

Üç özelliği: her zaman açık, ek ücreti yok, bookmark’ları otomatik oluşturur.

Ücretsiz planda 7 gün. Geri yükleme yıkıcıdır ve devam eden sorguları iptal eder — ama işlem önceki bookmark’ı döndürdüğü için yanlış noktaya dönersen geri alabilirsin.

Migration’lar

migrations/ klasöründeki .sql dosyaları; uygulananlar d1_migrations tablosunda tutulur. Hata durumunda: “this migration will be rolled back, and the previous successful migration will remain applied.”

Drizzle gibi ORM yerleşimleri için migrations_dir ve migrations_pattern ayarlanabilir. Yabancı anahtar ihlali doğuracak değişikliklerden önce PRAGMA defer_foreign_keys = true.

Ne zaman kullanılır, ne zaman kullanılmaz

Uygun olduğu işler

• Kullanıcı profilleri, ürün listeleri, siparişler — klasik ilişkisel veri
• Ad-hoc SQL sorgusu gerektiren işler
• Okuma/yazma oranı yüksek uygulamalar (çoğu web uygulaması)
• Kiracı başına veya kullanıcı başına ayrı veritabanı

Uygun olmadığı işler

• Çalışan veri kümesi 10 GB’ı aşıyorsa. Sınır artırılamaz; bölmek gerekir.
• Yazma ağırlıklı veya yüksek eşzamanlı iş yükü. Veritabanı tek iş parçacıklıdır.
• Kesin serileştirilebilirlik veya global sıralama gerekiyorsa. Durable Objects.
• Mevcut PostgreSQL/MySQL varsa veya 1 TB üstü tek veritabanı gerekiyorsa. Hyperdrive.
• Toplu mutasyon. “A single query that attempts to modify hundreds of thousands of rows or hundreds of MBs of data at once will exceed execution limits.” 1.000’er satırlık parçalara böl.
• Tablo başına 100’den fazla kolon gerekiyorsa.
• Etkileşimli transaction gerekiyorsa.

Hangi ürün — Cloudflare’in kendi yönlendirmesi

Somut örnekler

1. Kiracı bazlı sorgu

export default {
  async fetch(request, env) {
    const kiraci = new URL(request.url).searchParams.get("kiraci");

    const { results, meta } = await env.DB
      .prepare(`SELECT id, eposta, olusturuldu FROM kullanicilar
                WHERE kiraci_id = ?1 ORDER BY olusturuldu DESC LIMIT 50`)
      .bind(kiraci)
      .all();

    // Fatura ölçümü: taranan satır / döndürülen satır oranı
    console.log(JSON.stringify({
      olay: "sorgu",
      okunanSatir: meta.rows_read,
      donenSatir: results.length,
      oran: meta.rows_read / Math.max(results.length, 1),
    }));

    return Response.json(results);
  },
};

2. Sipariş yazma — batch ile transaction

const siparisEkle = env.DB.prepare(
  "INSERT INTO siparisler (siparis_id, musteri_id, durum, tarih) VALUES (?1, ?2, ?3, ?4)");
const kalemEkle = env.DB.prepare(
  "INSERT INTO siparis_kalemleri (siparis_id, sku, adet) VALUES (?1, ?2, ?3)");
const stokDus = env.DB.prepare(
  "UPDATE stok SET adet = adet - ?2 WHERE sku = ?1 AND adet >= ?2");

// Biri başarısız olursa tamamı geri alınır
const sonuclar = await env.DB.batch([
  siparisEkle.bind(siparisId, musteriId, 0, Date.now()),
  kalemEkle.bind(siparisId, "SKU-1", 2),
  stokDus.bind("SKU-1", 2),
]);

// Her sonucun meta.rows_written değeri tam olarak faturalandığın şeydir
const toplamYazma = sonuclar.reduce((t, s) => t + s.meta.rows_written, 0);

3. Sessions API — kendi yazdığını okuma

export default {
  async fetch(request, env) {
    // Bookmark'ı istemciden al, yoksa varsayılanla başla
    const bookmark = request.headers.get("x-d1-bookmark") ?? "first-unconstrained";
    const oturum = env.DB.withSession(bookmark);

    // Yazma birincile gider, bookmark ilerler
    await oturum.prepare("INSERT INTO goruntulemeler (sayfa, ts) VALUES (?1, ?2)")
      .bind("/anasayfa", Date.now()).run();

    // Yukarıdaki yazmayı görmesi garanti — read-my-own-writes
    const sonuc = await oturum
      .prepare("SELECT COUNT(*) AS n FROM goruntulemeler WHERE sayfa = ?1")
      .bind("/anasayfa").first();

    const yanit = Response.json({ sayi: sonuc?.n });
    // Bookmark'ı istemciye geri ver ki sonraki istek devam etsin
    yanit.headers.set("x-d1-bookmark", oturum.getBookmark() ?? "");
    return yanit;
  },
};

4. Index’in faturaya etkisini ölçme

-- Önce planı gör
EXPLAIN QUERY PLAN SELECT * FROM kullanicilar WHERE eposta = 'ali@ornek.com';
-- SCAN kullanicilar              → her satır faturalanır
-- SEARCH kullanicilar USING INDEX → yalnızca eşleşenler

CREATE INDEX idx_kullanicilar_eposta ON kullanicilar(eposta);

Çok kolonlu index kuralı: “queries will only use the index if they specify either all of the columns, or a subset of the columns provided all columns to the ‘left’ are also within the query.”

Demo 1: Veritabanı kurma ve migration

Adım 1 — Veritabanı oluştur

npx wrangler d1 create urun-veritabani --location weur

Terminal — oluşturulan veritabanının kimliği ve wrangler.jsonc'a eklenecek binding bloğu

Adım 2 — Şemayı yerelde uygula

npx wrangler d1 execute urun-veritabani --local --file=./schema.sql
npx wrangler d1 execute urun-veritabani --local --command="SELECT name FROM sqlite_master"

İki komut çıktısı — şema yükleme ve tabloların listelenmesi

Adım 3 — Migration ile ilerle

npx wrangler d1 migrations create urun-veritabani kullanici_tablosu_ekle
npx wrangler d1 migrations list urun-veritabani --remote
npx wrangler d1 migrations apply urun-veritabani --remote

Terminal — migration dosyasının oluşturulması, listelenmesi ve uygulanması

SELECT * FROM d1_migrations çıktısı — uygulanan migration kayıtları

Adım 4 — Panelden incele

Storage & databases → D1 → veritabanı: boyut, tablo listesi ve sorgu konsolu

Demo 2: Index’in fatura üzerindeki etkisi

Bu demo D1’in en pahalı hatasını somut olarak ölçer.

Adım 1 — Index’siz sorgu çalıştır

npx wrangler d1 execute urun-veritabani --remote \
  --command="SELECT * FROM kullanicilar WHERE eposta = 'test@ornek.com'"

Komut çıktısındaki meta bloğu — rows_read değerinin tablo satır sayısına eşit olduğu

Adım 2 — Sorgu planını incele

EXPLAIN QUERY PLAN sonucu — 'SCAN kullanicilar' satırı

Adım 3 — Index ekle ve tekrar ölç

Aynı sorgunun meta bloğu — rows_read değerinin bire düştüğü

Aynı EXPLAIN çıktısı — bu kez 'SEARCH kullanicilar USING INDEX' satırı

Adım 4 — Pahalı sorguları bul

npx wrangler d1 insights urun-veritabani

En çok satır okuyan sorguların listesi ve okunan/döndürülen oranları

Adım 5 — Time Travel ile geri dön

npx wrangler d1 time-travel info urun-veritabani
npx wrangler d1 time-travel restore urun-veritabani --timestamp=<UNIX>

Terminal — geri yükleme onayı ve dönen önceki bookmark değeri

Geri yüklemeden sonra tabloların eski hâline döndüğünü gösteren sorgu çıktısı

Ölçüm

Fiyatlandırma

Rakamlar 1 Eylül 2026’da resmî dokümandan doğrulanmıştır.

Egress ücreti yoktur.

Fatura tuzakları — Cloudflare’in kendi listesi

Ölçüm için her yanıttaki meta bloğuna bak:

"meta": { "duration": 0.204, "rows_read": 5000, "rows_written": 0, "total_attempts": 1 }

Odaklanılacak sorgular: rows_read / döndürülen satır oranı yüksek olanlar.

Limitler

Eşzamanlı bağlantı: Worker çağrısı başına en fazla 6.

Konum ipuçları: wnam, enam, weur, eeur, apac, oc. Güney Amerika, Afrika ve Orta Doğu desteklenmiyor — “D1 databases do not run in these locations.”

Lisanslama ve hukuki çerçeve

D1 tescilli bir hizmettir; Cloudflare Hizmet Şartları kapsamındadır.

Veri yerleşimi — D1’in KV’ye göre üstünlüğü. Yargı bölgesi (eu, fedramp) yalnızca birincil veritabanını değil read replica’ları da kısıtlar:

“If a jurisdiction is configured, read replicas are only created within the jurisdiction set on database creation.”

Bu, KV ile arasındaki önemli bir farktır — KV’de jurisdiction yalnızca kalıcı depolamayı bağlar, cache o sınırın dışına çıkabilir.

Yargı bölgesi oluşturma anında verilir ve sonradan değiştirilemez. Konum ipucuyla birlikte verilirse yargı bölgesi kazanır. Türkiye için tanımlı bir bölge yoktur.

Time Travel ve silme hakkı. 30 günlük geri dönüş penceresi, silinen verinin 30 gün daha geri getirilebilir olduğu anlamına gelir. KVKK kapsamında silme talebi işliyorsan bunu veri envanterine ve süreçlerine yansıtman gerekir.

Sık yapılan hatalar

Faturanın döndürülen satıra göre kesildiğini sanmak. Taranan satıra göre kesilir.

SELECT * çekip filtrelemeyi kodda yapmak. Tam tarama çarpanı.

Bileşik koşula tek kolonluk index koymak. Tam taramayı önler ama yine de o kolonla eşleşen her satır okunur.

ORDER BY RANDOM() LIMIT 1. Büyük tabloda index’le düzeltilemez.

İstek yolunda CREATE INDEX. İndekslenen her satır için bir yazma — en pahalı işlem.

--local bayrağını unutmak (veya tersine, üretime yazmak isterken unutmak).

Replication’ı açıp withSession() çağırmamak. Hiçbir fayda sağlamaz.

Yazmaların otomatik tekrar deneneceğini sanmak. Yalnızca SELECT, EXPLAIN ve WITH tekrar denenir.

Toplu UPDATE/DELETE’i tek ifadede çalıştırmak. 1.000’er satıra böl.

Time Travel geri yüklemesini güvenli sanmak. Yerinde üzerine yazar ve devam eden sorguları iptal eder.

100 bağlı parametre sınırını aşmak. Uzun IN (?, ?, ...) listelerinde sık karşılaşılır.