Erste Schritte

MySQL- und Hyperdrive-Infrastruktur für Cloudflare Workers. Kombinieren Sie aufrufgebundenen Primary-/Replikat-Zugriff, Deadlock-Wiederholungen, optionale Drizzle-Hilfsfunktionen und Node.js-Migrations-/Testwerkzeuge. Die Anwendung behält dabei ihre Schemas und Zugangsdaten.

Der Worker muss Node.js-Kompatibilität aktivieren, da mysql2 Node.js-Netzwerk-APIs verwendet:

# wrangler.toml
compatibility_flags = ["nodejs_compat"]

Installation

npm install @rdlabo/workers-mysql

mysql2 ist als direkte Abhängigkeit enthalten. Ergänzen Sie drizzle-orm, wenn Sie /drizzle oder /testing verwenden:

npm install drizzle-orm

Drizzle als Peer-Abhängigkeit ermöglicht der Anwendung und ihren Schemas eine gemeinsame Typidentität.

Die öffentlichen Verbindungstypen verwenden Node.js-Deklarationen. @types/node@>=20.19.43 ist eine erforderliche Peer-Abhängigkeit, auch bei Bereitstellung auf Workers. TypeScript-Anwendungen sollten sie direkt hinzufügen, damit ihre globalen Deklarationen bei strikten Paketlayouts einschließlich pnpm sichtbar sind:

npm install -D @types/node@20
# Für pnpm-Nutzer:
pnpm add -D @types/node@20

Verwenden Sie die passende unterstützte Hauptversion für Ihre Werkzeuge. Automatische Peer-Installation allein macht diese globalen Deklarationen unter pnpm möglicherweise nicht für den TypeScript-Compiler der Anwendung sichtbar.

Mit einer echten Abfrage beginnen

Ihre erste MySQL-Abfrage ausführen: Starten Sie eine kurzlebige lokale Datenbank, führen Sie ein parametrisiertes SELECT aus und prüfen Sie das Ergebnis. Die Anleitung zeigt anschließend den vollständigen Worker-Handler für eine bestehende Hyperdrive-Bindung.

Einen Einstiegspunkt wählen

Schnellstart

Erstellen Sie die Datenbank innerhalb jedes Worker-Aufrufs. In diesem Ausschnitt enthält env die Hyperdrive-Bindungen der Anwendung und schema ihr eigenes Drizzle-Schema:

import { createHyperdriveDatabase } from '@rdlabo/workers-mysql';
import { DRIZZLE_ORM_OPTIONS } from '@rdlabo/workers-mysql/drizzle';
import { drizzle } from 'drizzle-orm/mysql2';

const db = createHyperdriveDatabase({
  primaryHyperdrive: env.PRIMARY,
  replicaHyperdrive: env.REPLICA,
  createOrm: (connection) => drizzle(connection, { schema, ...DRIZZLE_ORM_OPTIONS }),
});

Mit aktiviertem nodejs_compat ist der Paketwurzelpfad sicher für die Workers-Laufzeit und lädt weder Drizzle noch ausschließlich für Node gedachte Migrationslogik.

Speicherhilfsfunktionen mit festem +09:00 bilden einen MySQL-Wire-Vertrag. Sie folgen nicht den IANA-Anzeigezeitzonen aus @rdlabo/workers-timezone.

Hono-Integration

Hono-Anfragecontainer verwenden den Adapter in @rdlabo/workers-hono-kit/mysql:

import { createContainerRuntime } from '@rdlabo/workers-hono-kit/mysql';

Dieser Adapter ist ab Hono Kit 0.12.0 verfügbar. Installieren Sie beide Pakete:

npm install @rdlabo/workers-mysql @rdlabo/workers-hono-kit

Dokumentation

• Laufzeit — Anfragelebensdauer, Primary-/Replikat-Lesezugriffe und sichere Wiederholungen.
• Drizzle und Datumswerte — Schema-Zuständigkeit, optionale Peer-Abhängigkeit und Speicherung mit festem JST.
• Migrationen und Tests — Node.js-Werkzeuge und destruktive Testhilfsfunktionen.
• API — öffentliche Exporte nach Einstiegspunkt.
• Migration — Kompatibilitätsimports aus dem Kit.

Diese Anleitungen beschreiben diese Quellcoderevision. Verwenden Sie für eine installierte Version das passende Release-Tag.

Migration von workers-hono-kit

Kit 0.12.0 verändert die Importgrenzen. Seine alten /db-Exporte und datenbankbezogenen /testing-Exporte bleiben als gepflegte Kompatibilitätspfade mit @deprecated-Hinweisen verfügbar; eine Entfernung ist nicht geplant. Die Importzuordnung finden Sie unter Migration.