D1 a gyakorlatban: lockok, toolok, multitenant, flotta-üzemeltetés

5b.1„SQLite-fájl… nem lesz ezzel gond? Lock?"

Az idegenkedésed forrása valószínűleg a klasszikus SQLite-tapasztalat: egy .db fájl a diszken, amit több processz nyitogat, database is locked hibák, write-ok tolakodása, NFS-en való használat tiltólistája. Ez a problémakör a D1-re nem vihető át, mert az architektúra alapvetően más.

Egy D1 adatbázis a gyakorlatban egy Durable Object: egy egyszálú, állapotőrző mini-szerver, amelyhez az SQLite-motor és a tár fizikailag hozzá van kötve, és amelyből pontosan egy példány létezik a hálózaton. Minden írás ezen az egyetlen példányon megy át, sorban. A klasszikus SQLite-lockolás azért létezik, mert több független processz versenyez ugyanazért a fájlért — a D1-ben nincs több processz. Nincs lock-verseny, nincs „busy timeout" tuning, nincs korrupt fájl egy elszállt writer után. A tartósságot pedig nem egy lokális diszk adja: az írások replikált, tartós tárba kerülnek (ebből a változásfolyamból él a Time Travel is), a read-ekhez pedig a platform automatikus replikákat tart (5. modul).

Az őszinte rész: a lock-probléma helyét egy másik korlát veszi át: az áteresztőképesség. Egy egyszálú writer másodpercenként nagyságrendileg néhány száz–ezer egyszerű írást bír — egyetlen D1 tehát nem egy vertikálisan hizlalható Aurora-writer. Kis-közepes írásterhelésű appnál (és a legtöbb SaaS ilyen) ez bőven elég; write-heavy központi adatbázisnak viszont egy darab D1 rossz választás. A platform válasza a horizontális szétosztás: sok adatbázis (per-tenant!), amelyek írásterhelése természetesen oszlik el — így lesz az aggályból mindjárt architektúra-érv a következő szakaszban.

5b.2„De hol van ez fizikailag? És mekkora latencyvel számoljak?"

Fontos, hogy ezt tisztán lásd, mert itt tér el a D1 a Workers „mindenhol vagyok" modelljétől: a Worker-kódod tényleg mindenhol fut — a D1 primary példánya viszont egy konkrét régióban él. Ez nem D1-gyengeség, hanem a single-writer adatbázisok fizikája: az írásoknak egyetlen konzisztens igazságforrás kell, és az valahol van. Az Aurorád ma pontosan ugyanígy működik.

Amiben viszont több ráhatásod van, mint elsőre tűnik:

• Létrehozáskor te döntesz a helyről. Alapértelmezésben a DB oda kerül, ahonnan létrehozod (Budapestről tipikusan EEUR — a wrangler ki is írja: ✅ Successfully created DB '…' in region EEUR). De adhatsz location hintet: wrangler d1 create my-db --location oc → a DB Óceániában jön létre. Régiók: wnam/enam (Észak-Amerika), weur/eeur (Európa), apac (Ázsia), oc (Óceánia). Emellett --jurisdiction eu garantálja, hogy az adat az EU-ban marad. Utólag ellenőrizni: wrangler d1 info my-db.
• A latency képlete egyszerű és tervezhető. Az írás mindig a primary régióba utazik: Ausztráliából egy EEUR primary-ra ~250–300 ms RTT — ugyanannyi, mint ma Aurorával. Az olvasás viszont a read replikákkal (Sessions API, 5. modul) a userhez közeli régióból jön ki — az ausztrál user readje nem utazik Európába. Read-heavy app tehát globálisan gyors, a write-latencyt pedig a primary helyéből előre kiszámolod.
• Smart Placement. Ha egy kérés sok query-t lő ugyanarra a DB-re, a platform magát a Workert futtatja a DB régiójában — a sok kör így helyben, ~1 ms-os körökkel megy, és csak a kész válasz utazik a userhez.

5b.3„Elérem a szokásos SQL-management toolokkal?"

Röviden: DBeaver/TablePlus/psql közvetlenül nem — a D1 nem beszél Postgres/MySQL wire-protokollt, nincs TCP-endpoint. Amit kapsz helyette, az négy hivatalos út és egy nagyon kényelmes lokális kiskapu:

# ad-hoc lekérdezés élesben, JSON-ban
npx wrangler d1 execute tenant-acme --remote \
  --command "SELECT id, email, created_at FROM users ORDER BY created_at DESC LIMIT 20" \
  --json | jq '.[0].results'

# nagyobb elemzéshez: exportáld, és elemezd helyben bármivel
npx wrangler d1 export tenant-acme --remote --output=./acme.sql

5b.4Multitenant SaaS: az első jó hír — a shared minta változatlanul működik

A mostani rendszered — egy közös DB, mindenhol tenant_id oszlop — egy az egyben átvihető D1-re: ugyanaz a séma, ugyanazok a query-k (SQLite-dialektusban), Drizzle-lel akár ugyanaz a kódbázis. Ilyenkor egyetlen D1-ed van, és a korlátok is egyben érvényesek rá: 10 GB összesen és egyetlen writer az összes tenantnak. Ökölszabály: ha az összes tenant-adatod belátható időn belül néhány GB alatt marad, és az aggregált írásterhelés mérsékelt (nem tartósan több száz write/s), a shared minta D1-en teljesen jó — és a legkisebb migrációs munka.

A per-tenant izolációt ilyenkor ugyanúgy app-szinten fegyelmezed, mint most — azzal a különbséggel, hogy D1-ből olcsón jár a következő szint, ha kell.

5b.5DB-per-tenant: hogyan néz ki tényleg?

Itt jön a D1 igazi különlegessége: mivel egy adatbázis létrehozása egy API-hívás (nincs instance, nincs díj üresjáratban), a „minden tenantnak saját adatbázis" minta először válik olcsóvá. Amit cserébe meg kell oldanod, az két dolog: a dinamikus elérés és a flotta-menedzsment.

A központi elem: a registry

Kell egy központi „control-plane" adatbázis (maga is lehet D1), ami a tenant→adatbázis hozzárendelést és a séma-verziókat tartja nyilván. Minden más erre épül:

-- registry DB (központi D1)
CREATE TABLE tenants (
  id            TEXT PRIMARY KEY,      -- 'acme'
  d1_database_id TEXT NOT NULL,        -- a tenant D1-ének UUID-ja
  schema_version INTEGER NOT NULL,     -- hol tart a migrációban
  status        TEXT NOT NULL,         -- active | migrating | suspended
  created_at    TEXT NOT NULL
);

Tenant-onboardingkor a Workered a REST API-val hozza létre az új DB-t (POST /accounts/:id/d1/database, akár --jurisdiction eu-val), lefuttatja rajta az aktuális sémát, és beírja a registrybe.

Dinamikus elérés: a bindings határa és a megoldások

Az 1. modul bindings-modellje itt beleütközik egy határba: a binding statikus — a wrangler-konfigban felsorolt DB-kre vonatkozik, nem tudsz „futásidőben bindolni" a 400. tenant DB-jére. Három bevált megoldás van, növekvő komplexitással:

async function queryTenant(env, dbId: string, sql: string, params: unknown[]) {
  const res = await fetch(
    `https://api.cloudflare.com/client/v4/accounts/${env.CF_ACCOUNT_ID}/d1/database/${dbId}/query`,
    {
      method: "POST",
      headers: { Authorization: `Bearer ${env.D1_API_TOKEN}`,
                 "Content-Type": "application/json" },
      body: JSON.stringify({ sql, params }),
    });
  const { result } = await res.json();
  return result[0].results;
}

// használat: registry-lookup (cache-elhető KV-ban!) → tenant-query
const tenant = await env.REGISTRY.prepare(
  "SELECT d1_database_id FROM tenants WHERE id = ?").bind(tenantId).first();
const rows = await queryTenant(env, tenant.d1_database_id,
  "SELECT * FROM invoices WHERE status = ?", ["open"]);

5b.6Séma-frissítés több száz tenant-DB-n

Ez a DB-per-tenant minta valódi ára — de jól megoldható, és a 7. modulban érkező Workflows pontosan erre való. A recept:

1. Verziózott, idempotens migrációk. Ugyanazok a sorszámozott .sql fájlok, mint eddig; a registry schema_version mezője mondja meg tenantonként, hol tart. Idempotencia (IF NOT EXISTS, kis lépések), mert újrafuttatás mindig lesz.
2. Canary → flotta. Először 1–2 belső/teszt tenantra futtatod, aztán néhány kis tenantra, végül a teljes flottára — a registry status mezőjével jelölve, ki van folyamatban.
3. Orkesztráció Workflow-val. Egy Workflow végigmegy a registryn, tenantonként lépésben (retry-jal!) alkalmazza a migrációt a HTTP API-n át, és frissíti a verziót. Ha a 137. tenantnál elhal, onnan folytatódik — nem kezdi elölről.

const pending = await registry.prepare(
  "SELECT id, d1_database_id FROM tenants WHERE schema_version < ? AND status = 'active'"
).bind(TARGET_VERSION).all();

for (const t of pending.results) {
  await step.do(`migrate-${t.id}`, async () => {   // retry + resume ingyen
    await queryTenant(env, t.d1_database_id, MIGRATION_SQL, []);
    await registry.prepare(
      "UPDATE tenants SET schema_version = ? WHERE id = ?"
    ).bind(TARGET_VERSION, t.id).run();
  });
}

5b.7Üzemeltetés több száz DB-vel: „bele kell néznem a 217.-be"

A kulcs a következetesség: névkonvenció (tenant-<slug>), a registry mint egyetlen igazságforrás, és néhány begyakorolt fogás:

5b.8Őszinte mérleg

• Az áteresztés-korlátra a válasz az architektúra: per-tenant szétosztás, vagy nagy központi írásterhelésnél maradó Postgres + Hyperdrive.
• A tool-kérdésre: dashboard + wrangler + HTTP API + lokális SQLite-fájl — más munkafolyamat, nem rosszabb.
• A flottához: registry + idempotens migrációk + Workflow-runner + Time Travel — de ezt a control-plane-t neked kell megépítened (kb. néhány nap munka), a platform a primitíveket adja, nem a kész multitenant-keretrendszert.

5b.9Ellenőrizd magad