planetscale/database-js

A Fetch API-compatible PlanetScale database driver

Summary

planetscale/database-js is a TypeScript driver for PlanetScale's MySQL/Vitess databases, built around the Fetch API so it works in environments that only allow outbound HTTP. It targets serverless and edge runtimes like Cloudflare Workers and Vercel Edge Functions, where traditional TCP-based MySQL clients are not viable. The project is published under the Apache 2.0 license.

What it is useful for

• Talking to a PlanetScale Vitess/MySQL database from edge runtimes that block raw TCP, such as Cloudflare Workers or Vercel Edge Functions.
• Replacing a Node mysql2-style client inside serverless functions, where TCP handshake and pool startup cost matter.
• Applications that need a swappable HTTP transport, including undici for Node and fetch-h2 for HTTP/2, or a custom proxy layer.
• Code that wants a fresh, per-request connection built through a Client factory instead of a long-lived pool.

How engineers can use it

The README documents this setup:

npm install @planetscale/database

import { connect } from '@planetscale/database'
const conn = connect({ url: process.env['DATABASE_URL'] })
const results = await conn.execute('select 1 from dual')

From there, engineers can:

• Build one new Client(config).connection() per request handler or transaction to avoid sharing connection state.
• Wrap multi-statement work in conn.transaction(async tx => { ... }); the README states that any unhandled error will roll the transaction back.
• Provide a fetch in the config to use undici (the README's recommended option for Node) or fetch-h2 to enable HTTP/2, calling disconnectAll() from the fetch-h2 context when finished.
• Override value coercion with a cast function, for example returning BigInt for INT64 and UINT64 columns, either globally on the connection or per call.
• Choose row layout per call with { as: 'object' } (default) or { as: 'array' }.

Documented limitations to be aware of:

• execute does not interpolate parameters and will throw if called with an array or a named-parameter object. The README recommends building SQL with a separate escaper such as sql-escaper rather than relying on the driver.
• This driver targets MySQL/Vitess only; for PlanetScale Postgres, the README points users to the separate Neon serverless driver.