PlanetScale Database

@planetscale/database is PlanetScale’s official serverless driver for connecting to PlanetScale’s Vitess/MySQL databases over plain HTTP instead of a persistent TCP socket. It targets environments that can’t hold long-lived TCP connections open — Cloudflare Workers, Vercel Edge Functions, and other edge/serverless runtimes — by speaking to PlanetScale’s HTTP-based database gateway using the standard Fetch API.

The library exposes a small surface: a connect() function for one-off queries, a Client/connection() factory for creating fresh connections per request, and a transaction() helper that wraps BEGIN/COMMIT/ROLLBACK around a callback. Query results come back typed, with automatic casting from Vitess’s wire types (INT64, DECIMAL, JSON, DATETIME, binary columns, etc.) into native JavaScript values, and rows can be returned as objects or arrays.

Because it’s built on fetch, the driver works unmodified anywhere a Fetch-compatible global exists, and accepts a custom fetch implementation (e.g. undici or fetch-h2) for older Node.js versions or HTTP/2 support. It also lets callers override SQL parameter escaping and type casting to integrate with existing tooling.

What You Get

• A connect() / Client API for executing parameterized SQL queries against PlanetScale over HTTP
• Automatic type casting of Vitess wire-protocol values (integers, floats, decimals, dates, JSON, binary) into native JS types
• A transaction() helper that automatically issues BEGIN/COMMIT and rolls back on thrown errors
• Support for both positional (?) and named (:name) SQL parameter placeholders with built-in escaping
• Pluggable fetch, format, and cast functions so consumers can swap in their own HTTP client, SQL escaping, or value casting
• Row results returned as either objects or arrays via the as execute option

Common Use Cases

• Querying a PlanetScale database from a Cloudflare Worker or Vercel Edge Function where TCP sockets aren’t available
• Running SQL from serverless functions (AWS Lambda, Vercel serverless) without managing a connection pool
• Wrapping multi-statement writes in a transaction with automatic rollback on error
• Building a lightweight data-access layer for edge-rendered pages that need direct SQL access
• Integrating PlanetScale as the backing store for ORMs or query builders that support a custom driver adapter

Under The Hood

Architecture The driver is a thin translation layer between a JavaScript SQL API and PlanetScale’s HTTP database gateway (psdb.v1alpha1.Database/Execute and /CreateSession). Connection owns a fetch implementation, a session token, and the target URL derived from either a url or discrete host/username/password config fields; Client is a stateless factory that hands out fresh Connection instances per call, and Tx wraps a Connection to scope BEGIN/COMMIT/ROLLBACK around a user callback in transaction(). Query execution flows through a single postJSON helper that Base64-encodes Basic Auth credentials, POSTs the query and any existing session, and distinguishes real Vitess errors from transport-level failures (including Cloudflare’s edge error codes) before parsing rows via decodeRow/parse. There is no connection pooling or retry logic — each Connection is disposable, matching the request-scoped lifecycle of edge and serverless functions.

Tech Stack Written in TypeScript with a single small dependency-free src/ (index, cast, sanitization, text, version), compiled to both ESM (dist/index.js) and CommonJS (dist/cjs) via tsc. It relies entirely on the platform’s global fetch, atob/btoa, and URL APIs rather than Node-specific modules, which is what makes it portable to Workers and Edge runtimes; undici and fetch-h2 are documented as optional custom-fetch shims for older Node or HTTP/2. Linting uses ESLint with @typescript-eslint and Prettier; tests run via Node’s built-in test runner (node --test) through tsx.

Code Quality The __tests__/ directory (cast, sanitization, text, index, and a golden-file suite comparing against golden/*.json fixtures) covers type casting, SQL parameter escaping, and end-to-end query/transaction behavior against a mocked fetch. Error handling is explicit: DatabaseError and UnknownError subclasses distinguish Vitess-reported errors from transport/parsing failures, and Cloudflare’s edge HTTP status codes are special-cased so infrastructure errors aren’t misreported as database errors. Types are used throughout the public API (overloaded execute<T> signatures for object vs. array row shapes), and CI runs lint plus the full test suite on each change.

API Design The public surface is intentionally minimal — connect(), Client, transaction(), and execute() cover the entire read/write path, with sensible defaults (object rows, built-in SQL escaping, automatic type casting) that require zero configuration to get started. Advanced use is opt-in via config overrides (fetch, format, cast) rather than additional API surface, keeping the getting-started path to a single connect() call and one execute() invocation.