Hyperdrive

Hyperdrive nedir?

Workers dünya genelinde 330’dan fazla şehirde çalışır. Kurumsal veritabanın ise tek bir yerde durur. Bu ikisini birleştirmek üç somut problem doğurur:

1. Bağlantı kurulum turları. Stateless bir isolate her çağrıda TCP el sıkışması (1 tur), TLS anlaşması (3 tur) ve veritabanı kimlik doğrulaması (3 tur) — toplam yedi tur — atmak zorunda kalır. Cloudflare’in kendi ölçümü: Chicago’dan Londra’ya bir tur ~125 ms, beş tur 625 ms. Sorgu daha başlamadan.
2. Bağlantı limiti. Veritabanları sınırlı sayıda eşzamanlı bağlantı kabul eder; dağıtık trafik bunu hızla tüketir.
3. Coğrafya. Sorgu ve yanıt her seferinde kıtalar arası gidip gelir.

Hyperdrive üçünü birden çözer: bağlantı kurulumunu Worker’a yakın tamamlar, havuzu veritabanına yakın tutar, ve sorgu sonuçlarını cache’ler.

Nasıl çalışır?

Tur sayısını düşürme

Resmî açıklama:

“By maintaining a connection pool to your database within Cloudflare’s network, Hyperdrive reduces seven round-trips to your database before you can even send a query: the TCP handshake (1x), TLS negotiation (3x), and database authentication (3x).”

“Since authentication has already been completed at the edge, Hyperdrive only needs a single round trip across regions to your database.”

Kenardaki bu el sıkışma Worker ile aynı sunucuda gerçekleşir — p50’de 2 ms, p90’da 4 ms.

Bağlantı havuzu — transaction modu

Havuz transaction modunda çalışır: istemci bir işlem süresince tek bir bağlantı kullanır, işlem bitince bağlantı havuza döner ve RESET edilir.

Sorgu cache’i

Varsayılan olarak açıktır.

Hyperdrive veritabanı protokolünü ayrıştırır — yalnızca SELECT ile INSERT ayrımı değil, fonksiyon türlerini de görür. Yalnızca IMMUTABLE fonksiyonlar cache’lenebilir.

Cache dışı bırakan PostgreSQL fonksiyonları: NOW(), CURRENT_TIMESTAMP, CURRENT_DATE, CURRENT_TIME, LOCALTIME, LOCALTIMESTAMP, TIMEOFDAY(), RANDOM(), LASTVAL(), TXID_CURRENT().

Cache geçersizleştirme yoktur. Yazma yaptığında cache temizlenmez ve purge API’si de yok. Resmî çözüm ikinci bir yapılandırma:

npx wrangler hyperdrive create veritabanim-taze \
  --connection-string="<BAGLANTI_DIZESI>" --caching-disabled

TLS zorunludur

Şifresiz bağlantı mümkün değil: “Hyperdrive does not support insecure plain text connections.” prefer ve PREFERRED modları da reddedilir.

Özel CA ve mTLS istemci sertifikaları wrangler cert upload ile yüklenebilir.

Şirket içi veritabanına erişim

Workers VPC (önerilen):
  Worker → Hyperdrive → VPC Service → Cloudflare Tunnel → Private veritabanı

Tunnel + Access:
  Worker → Hyperdrive → Cloudflare Access → Cloudflare Tunnel → Private veritabanı

Güvenlik duvarı açısından üç desteklenen topoloji var: internete açık, Cloudflare IP aralıklarına ACL’li, veya Tunnel üzerinden private ağ.

Veritabanı tarafında Hyperdrive’ı görmek için:

SELECT DISTINCT usename, application_name
FROM pg_stat_activity
WHERE application_name = 'Cloudflare Hyperdrive';

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

Uygun olduğu işler

• Mevcut ve taşınamayan PostgreSQL/MySQL’e Workers’tan erişim
• 1 TB ve üzeri tek veritabanları
• Mevcut ORM ve araç zincirini korumak
• Okuma ağırlıklı, bayatlığa toleranslı iş yükleri (cache burada çok işe yarar)

Uygun olmadığı işler

• LISTEN/NOTIFY, advisory lock veya oturum durumu gerekiyorsa. Desteklenmiyor; ikinci bir doğrudan istemci aç.
• MySQL protokol seviyesi prepared statement veya çok ifadeli sorgu. Desteklenmiyor.
• SQL Server veya MongoDB. Desteklenmiyor.
• Uzun işlemler. “Long-running transactions that contain multiple queries can exhaust Hyperdrive’s available connections more quickly.”
• Cache’li okumada yazma sonrası tutarlılık gerekiyorsa. Geçersizleştirme yok; ikinci yapılandırma kullan.
• 60 saniyeden uzun süren tek ifade. Sonlandırılır.
• 50 MB’tan büyük sonuç kümesini cache’lemek. Cache’lenmez ama Worker’a yine döner.
• Durable Object içinde uzun ömürlü bağlantı tutmak. Havuzu tüketir.
• Sıfırdan yeni proje. Mevcut RDBMS yoksa D1 veya Durable Objects daha uygun.

Hyperdrive mi, D1 mi, Durable Objects mi?

Cloudflare’in kendi yönlendirmesi:

Hyperdrive — “if you have an existing Postgres or MySQL database, require large (1TB, 100TB or more) single databases, and/or want to use your existing database tools.”

D1 — “for lightweight, serverless applications that are read-heavy, have global users that benefit from D1’s read replication, and do not require you to manage and maintain a traditional RDBMS.”

Durable Objects — “for stateful serverless workloads, per-user or per-customer SQL state, and building distributed systems.”

Somut örnekler

Ortak yapılandırma:

{
  "compatibility_flags": ["nodejs_compat"],
  "compatibility_date": "2026-09-01",
  "hyperdrive": [{ "binding": "HYPERDRIVE", "id": "<HYPERDRIVE_ID>" }]
}

1. PostgreSQL — node-postgres (önerilen sürücü)

import { Client } from "pg";

export default {
  async fetch(request, env, ctx) {
    // İstemciyi HER İSTEKTE handler İÇİNDE oluştur.
    // Havuzu Hyperdrive yönetir, bu yüzden yeni istemci oluşturmak ucuzdur.
    const client = new Client({ connectionString: env.HYPERDRIVE.connectionString });

    try {
      await client.connect();
      const sonuc = await client.query("SELECT ad, fiyat FROM urunler LIMIT 20");
      return Response.json({ urunler: sonuc.rows });
    } catch (h) {
      console.error("Veritabanı hatası:", h.message);
      return new Response("Sunucu hatası", { status: 500 });
    }
    // client.end() ÇAĞIRMA — bağlantıyı Hyperdrive yönetiyor
  },
};

2. PostgreSQL — Postgres.js, cache dostu ayarlarla

import postgres from "postgres";

export default {
  async fetch(request, env, ctx) {
    const sql = postgres(env.HYPERDRIVE.connectionString, {
      max: 5,              // Workers'ın eşzamanlı dış bağlantı sınırı 6
      fetch_types: false,  // dizi tipi kullanmıyorsan bir turu daha atlar
      prepare: true,       // false olursa Hyperdrive cache'lemez
    });

    const sonuc = await sql`SELECT ad, fiyat FROM urunler LIMIT 20`;
    return Response.json({ urunler: sonuc });
  },
};

3. MySQL — mysql2

import { createConnection } from "mysql2/promise";

export default {
  async fetch(request, env, ctx) {
    const baglanti = await createConnection({
      host: env.HYPERDRIVE.host,
      user: env.HYPERDRIVE.user,
      password: env.HYPERDRIVE.password,
      database: env.HYPERDRIVE.database,
      port: env.HYPERDRIVE.port,
      disableEval: true,   // Workers uyumluluğu için ZORUNLU
    });

    const [satirlar] = await baglanti.query("SELECT ad, fiyat FROM urunler LIMIT 20");
    return Response.json({ urunler: satirlar });
  },
};

4. Cache’li ve taze okumaları ayırma

Bu, Hyperdrive’ı üretimde doğru kullanmanın anahtarıdır.

{
  "hyperdrive": [
    { "binding": "HYPERDRIVE", "id": "<CACHE_ACIK_ID>" },
    { "binding": "HYPERDRIVE_TAZE", "id": "<CACHE_KAPALI_ID>" }
  ]
}

import postgres from "postgres";

export default {
  async fetch(request, env, ctx) {
    const sql = postgres(env.HYPERDRIVE.connectionString);
    const sqlTaze = postgres(env.HYPERDRIVE_TAZE.connectionString);

    // Herkese açık katalog — bayatlık sorun değil
    const urunler = await sql`SELECT * FROM urunler WHERE aktif = true`;

    // Yetki kontrolü — ASLA cache'ten okunmamalı
    const [yetki] = await sqlTaze`
      SELECT rol FROM kullanicilar WHERE id = ${kullaniciId}`;

    return Response.json({ urunler, rol: yetki?.rol });
  },
};

Resmî yönlendirme: cache’li → “public content, dashboards, search results, product catalogs”; cache’siz → “authentication, sessions, permissions, billing state, admin settings, and reads immediately after a write.”

Demo 1: Şirket içi PostgreSQL’e Tunnel üzerinden bağlanma

Bu demo senin on-prem sunucunla yapılacak.

Adım 1 — Veritabanını hazırla

Terminal — postgres servisinin çalıştığı, dinlediği port ve max_connections değeri

Adım 2 — Tunnel ve VPC Service kur

npx wrangler vpc service create postgres-db \
  --type tcp --tcp-port 5432 --app-protocol postgresql \
  --tunnel-id <TUNNEL_ID> --ipv4 <VERITABANI_PRIVATE_IP>

Terminal — servis kimliği ve tünel eşleşmesi

Adım 3 — Hyperdrive yapılandırmasını oluştur

npx wrangler hyperdrive create onprem-pg \
  --service-id <VPC_SERVICE_ID> \
  --database uygulama --user cfuser --password '***' --scheme postgresql

Terminal — dönen Hyperdrive kimliği ve bağlantı bilgileri

Adım 4 — Veritabanı tarafından doğrula

SELECT DISTINCT usename, application_name
FROM pg_stat_activity
WHERE application_name = 'Cloudflare Hyperdrive';

psql çıktısı — application_name sütununda 'Cloudflare Hyperdrive' satırları ve kaç bağlantı açıldığı

Adım 5 — Doğrudan bağlantıyla karşılaştır

Aynı sorguyu Hyperdrive’sız ve Hyperdrive’lı çalıştır.

İki ölçüm yan yana — aynı sorgunun iki yoldan süresi; farkın büyüklüğü görünsün

Demo 2: Cache davranışı ve tuzakları

Adım 1 — Cache isabetini gözle

Panel — Hyperdrive metrik ekranında cacheStatus dağılımı (hit / miss / disabled / uncacheable)

Adım 2 — NOW() ile cache’i bozma

Aynı sorguyu NOW() ekleyip çalıştır ve uncacheable olduğunu gör.

Metrik ekranı veya log — sorgunun uncacheable olarak işaretlendiği

Adım 3 — Yorum satırı tuzağını doğrula

-- NOW() yorumu ekleyip aynı etkinin oluştuğunu göster.

İki sorgu — biri yorumsuz cache'leniyor, diğeri sadece yorum yüzünden cache'lenmiyor

Adım 4 — Yazma sonrası bayat okuma

Bir satırı güncelle, hemen ardından cache’li binding’den oku.

İki okuma — güncelleme sonrası cache'li binding eski değeri, cache'siz binding yeni değeri döndürüyor

Adım 5 — İkinci yapılandırmayla çöz

Aynı test iki binding ile — HYPERDRIVE_TAZE'nin doğru değeri döndürdüğü

Ölçüm

Fiyatlandırma

Resmî tanım: “Database queries refers to any database statement made via Hyperdrive, whether a query (SELECT), a modification (INSERT, UPDATE, or DELETE) or a schema change (CREATE, ALTER, DROP).”

Üç önemli nokta:

• Connection pooling ve cache ek ücret doğurmaz. “There are no hidden limits other than those published.”
• Cache’li sorgular da sayılır. Ücretsiz plandaki 100.000 kotasına cache’ten dönenler de dahildir.
• Egress ve compute ücreti yoktur. Yalnızca Worker’ının istek ve CPU süresi faturalanır.

PlanetScale ayrı faturalanır: Cloudflare panelinden PlanetScale veritabanı oluşturursan kullanım Cloudflare faturanda ayrı bir kalem olarak görünür.

Limitler

Hyperdrive Worker’larından gelen istemci bağlantı sayısını sınırlamaz; sınırladığı şey veritabanına açılan origin bağlantılarıdır.

Sürücü minimum sürümleri

Lisanslama ve hukuki çerçeve

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

Veri akışı açısından kritik nokta: Hyperdrive yalnızca bir aracı değil, aynı zamanda bir cache’tir. Sorgu sonuçların Cloudflare’in altyapısında saklanır — varsayılan 60 saniye, en fazla 1 saat.

Kişisel veri döndüren sorgular cache’leniyorsa bu bir veri işleme faaliyetidir. Pratik öneriler:

• Kişisel veri döndüren sorguları --caching-disabled yapılandırmasına yönlendir
• max_age değerini ihtiyacın kadar kısalt
• Kimlik doğrulama ve oturum sorgularını zaten cache dışında tutman gerekiyor — bu hem doğruluk hem gizlilik açısından aynı kapıya çıkıyor

Veritabanın Türkiye’de olsa bile Hyperdrive havuzu ve cache’i Cloudflare ağındadır.

Sık yapılan hatalar

İstemciyi global kapsamda oluşturmak. En sık hata. Belirtiler: Disallowed operation called within global scope, Cannot perform I/O on behalf of a different request. İstemciyi handler içinde oluştur.

new Pool() veya createPool() kullanmak. Havuzu Hyperdrive yönetir. Belirti: Cannot use a pool after calling end on the pool.

client.end() veya sql.end() çağırmak. Gereksiz ve zararlı. Belirtiler: Connection terminated, Cannot enqueue Query after invoking quit.

İstemciyi istekler arasında yeniden kullanmak. Client has already been connected.

Sorguya NOW() yazıp cache beklemek. Zamanı Worker kodunda üretip parametre olarak geçir.

Yorum satırında fonksiyon adı bırakmak. -- NOW() sorguyu cache dışı bırakır.

Postgres.js’te prepare: false. Kysely ve sql.unsafe() bunu yapar; hiçbir şey cache’lenmez.

mysql2’de disableEval: true unutmak. Code generation from strings disallowed.

nodejs_compat bayrağını unutmak. No such module "node:...".

Yazma sonrası okumada tazelik beklemek. Geçersizleştirme yok; ikinci yapılandırma kullan.

Çok sayıda sorguyu tek işleme sarmak. Multiplexing’i öldürür: Failed to acquire a connection from the pool.

--origin-connection-limit değerini veritabanının max_connections değerine eşitlemek. Yumuşak sınır aşılabilir; pay bırak.

wrangler dev içinde cache beklemek. Yerelde cache çalışmaz; --remote kullan.