Getting Started

MySQL and Hyperdrive infrastructure for Cloudflare Workers. Compose
invocation-scoped primary/replica access, deadlock retries, optional Drizzle helpers, and Node.js
migration/testing tools while the application keeps its schemas and credentials.

The Worker must enable Node.js compatibility because mysql2 uses Node.js networking APIs:

# wrangler.toml
compatibility_flags = ["nodejs_compat"]

Install

npm install @rdlabo/workers-mysql

mysql2 is included as a direct dependency. Add drizzle-orm when using /drizzle or /testing:

npm install drizzle-orm

Keeping Drizzle as a peer gives the application and its schemas one type identity.

The public connection types use Node.js declarations. @types/node@>=20.19.43 is a required peer
(also when deploying to Workers). TypeScript applications should add it directly so its global
declarations are visible with strict package layouts, including pnpm:

npm install -D @types/node@20
# pnpm users:
pnpm add -D @types/node@20

Use the matching supported major for your tooling. Automatic peer installation alone may not expose
these global declarations to the application's TypeScript compiler under pnpm.

Start with a real query

Run your first MySQL query: start a disposable local database, execute a parameterized SELECT, and confirm the result. The guide then shows the complete Worker handler for an existing Hyperdrive binding.

Choose an entry point

Quick start

Create the database inside each Worker invocation. In this fragment, env contains the application's
Hyperdrive bindings and schema is its own 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 }),
});

With nodejs_compat enabled, the package root is Workers-runtime-safe and does not load Drizzle or
Node-only migration code.

Fixed +09:00 storage helpers are a MySQL wire contract. They do not follow IANA display timezones
from @rdlabo/workers-timezone.

Hono integration

Hono request containers use the adapter in @rdlabo/workers-hono-kit/mysql:

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

This adapter is available from Hono kit 0.12.0. Install both packages:

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

Documentation

• Runtime — request lifetime, primary/replica reads, and retry safety.
• Drizzle and dates — schema ownership, optional peer, and fixed-JST storage.
• Migrations and testing — Node.js tooling and destructive test helpers.
• API — public exports by entry point.
• Migration — kit compatibility imports.

These guides describe this source revision. Use the matching release tag for an installed version.

Migrating from workers-hono-kit

Kit 0.12.0 changes the import boundaries. Its old /db and DB-related /testing exports remain
available as maintained compatibility paths with @deprecated notices; there is no planned removal.
See Migration for the import map.