@planetscale/database

A Fetch API-compatible PlanetScale database driver

weekly downloads179K

versionv1.19.0

licenseApache-2.0

categorydatabase

planetscaledatabasemysqlvitessserverlessvercellambda

Overview

The @planetscale/database package is a JavaScript database driver specifically built for serverless and edge computing environments. Unlike traditional MySQL drivers that rely on TCP connections, it uses HTTP and the Fetch API to communicate with PlanetScale's MySQL-compatible databases (powered by Vitess). This architecture solves the fundamental problem of connection pooling and cold starts in serverless functions.

PlanetScale is a horizontally scalable database platform built on Vitess, the same technology that powers YouTube's database infrastructure. The driver enables developers to query MySQL databases from environments where TCP sockets are unavailable or impractical, such as Cloudflare Workers, Vercel Edge Functions, Deno Deploy, and Netlify Edge Functions. It handles authentication via connection strings and returns query results as JavaScript objects.

With over 179,000 weekly downloads, the package has become the standard way to access PlanetScale databases from JavaScript applications. It's particularly popular among developers building globally distributed applications who need low-latency database access from edge locations. The driver works standalone for raw SQL queries or integrates with ORMs like Prisma and Drizzle for type-safe database operations.

The package is maintained by PlanetScale and released under the Apache-2.0 license. It requires Node.js 18+ or any runtime supporting the Fetch API standard, making it highly portable across modern JavaScript environments.

Quick Start

typescript

import { connect } from '@planetscale/database';

// Initialize connection with PlanetScale credentials
const config = {
  host: process.env.DATABASE_HOST,
  username: process.env.DATABASE_USERNAME,
  password: process.env.DATABASE_PASSWORD
};

const conn = connect(config);

// Execute a simple query
const results = await conn.execute('SELECT id, email, created_at FROM users WHERE status = ? LIMIT 10', ['active']);
console.log(results.rows);

// Insert with parameters to prevent SQL injection
const insertResult = await conn.execute(
  'INSERT INTO users (email, name, status) VALUES (?, ?, ?)',
  ['user@example.com', 'John Doe', 'active']
);
console.log('Inserted ID:', insertResult.insertId);

// Use transactions for atomic operations
const txn = await conn.transaction();
try {
  await txn.execute('UPDATE accounts SET balance = balance - ? WHERE user_id = ?', [100, 42]);
  await txn.execute('UPDATE accounts SET balance = balance + ? WHERE user_id = ?', [100, 73]);
  await txn.commit();
} catch (error) {
  await txn.rollback();
  throw error;
}

// Alternatively, use connection URL for simpler config
const simpleConn = connect({ url: process.env.DATABASE_URL });
const { rows } = await simpleConn.execute('SELECT COUNT(*) as total FROM orders');
console.log('Total orders:', rows[0].total);

Use Cases

Edge API Routes: Build API endpoints in Vercel Edge Functions or Cloudflare Workers that query MySQL databases with minimal latency. The HTTP-based connection model avoids TCP socket limitations and leverages PlanetScale's global routing to connect users to the nearest database replica.

Serverless Backend Functions: Use in AWS Lambda, Google Cloud Functions, or Azure Functions to execute database queries without managing connection pools. The stateless nature of HTTP requests aligns perfectly with the ephemeral lifecycle of serverless functions, eliminating connection exhaustion issues.

Jamstack Applications: Power Next.js, Remix, or Astro applications with dynamic data fetching at the edge. Combine with PlanetScale's branching workflow to test schema changes in isolated database branches before deploying to production.

Real-time Data APIs: Create lightweight microservices that expose database queries over HTTP endpoints. The driver's minimal overhead makes it suitable for high-frequency read operations in dashboards, admin panels, or public APIs.

Multi-region Applications: Deploy the same codebase across multiple geographic regions while automatically routing database requests through PlanetScale's distributed infrastructure. Particularly useful for compliance requirements where data residency matters.

Pros & Cons

Pros

+Works natively in edge runtimes without TCP socket polyfills or connection pooling complexity
+Lightweight bundle size with minimal dependencies, using only the standard Fetch API
+Automatic connection management and retry logic built for serverless cold starts
+Integrates seamlessly with PlanetScale features like non-blocking schema changes and database branching
+Global routing ensures queries hit the nearest replica for improved latency
+Type-safe when paired with ORMs like Drizzle or Prisma while maintaining raw SQL access

Cons

−Locked to PlanetScale infrastructure - cannot connect to standard MySQL servers or other managed MySQL services
−HTTP overhead introduces slightly higher latency compared to persistent TCP connections for high-frequency operations
−Requires PlanetScale-specific connection strings; migration from traditional MySQL setups needs configuration changes
−Advanced MySQL features may have limited support due to Vitess compatibility layer
−Transaction support is available but less intuitive than traditional connection-based transaction APIs
−No connection pooling benefits for long-running Node.js servers where persistent connections would be more efficient

Alternatives

drizzle-ormv0.45.1

Drizzle ORM package for SQL databases

databasedrizzleorm

4.6M / week

@neondatabase/serverlessv1.0.2

node-postgres for serverless environments from neon.com

databaseNeonserverless

1.0M / week

prismav7.4.0

Prisma is an open-source database toolkit. It includes a JavaScript/TypeScript ORM for Node.js, migrations and a modern GUI to view and edit the data in your database. You can use Prisma in new projects or add it to an existing one.

databaseCLIORM

7.8M / week

@vercel/postgresv0.10.0

Connect to Vercel Postgres databases on the Edge

database

204K / week

Comparisons

@neondatabase/serverless vs @planetscale/database

database

Install

bash

npm install @planetscale/database

bash

pnpm add @planetscale/database

bash

bun add @planetscale/database

Overview

Quick Start

typescript

import { connect } from '@planetscale/database';

// Initialize connection with PlanetScale credentials
const config = {
  host: process.env.DATABASE_HOST,
  username: process.env.DATABASE_USERNAME,
  password: process.env.DATABASE_PASSWORD
};

const conn = connect(config);

// Execute a simple query
const results = await conn.execute('SELECT id, email, created_at FROM users WHERE status = ? LIMIT 10', ['active']);
console.log(results.rows);

// Insert with parameters to prevent SQL injection
const insertResult = await conn.execute(
  'INSERT INTO users (email, name, status) VALUES (?, ?, ?)',
  ['user@example.com', 'John Doe', 'active']
);
console.log('Inserted ID:', insertResult.insertId);

// Use transactions for atomic operations
const txn = await conn.transaction();
try {
  await txn.execute('UPDATE accounts SET balance = balance - ? WHERE user_id = ?', [100, 42]);
  await txn.execute('UPDATE accounts SET balance = balance + ? WHERE user_id = ?', [100, 73]);
  await txn.commit();
} catch (error) {
  await txn.rollback();
  throw error;
}

// Alternatively, use connection URL for simpler config
const simpleConn = connect({ url: process.env.DATABASE_URL });
const { rows } = await simpleConn.execute('SELECT COUNT(*) as total FROM orders');
console.log('Total orders:', rows[0].total);

Use Cases

Pros & Cons

Pros

+Works natively in edge runtimes without TCP socket polyfills or connection pooling complexity
+Lightweight bundle size with minimal dependencies, using only the standard Fetch API
+Automatic connection management and retry logic built for serverless cold starts
+Integrates seamlessly with PlanetScale features like non-blocking schema changes and database branching
+Global routing ensures queries hit the nearest replica for improved latency
+Type-safe when paired with ORMs like Drizzle or Prisma while maintaining raw SQL access

Cons

−Locked to PlanetScale infrastructure - cannot connect to standard MySQL servers or other managed MySQL services
−HTTP overhead introduces slightly higher latency compared to persistent TCP connections for high-frequency operations
−Requires PlanetScale-specific connection strings; migration from traditional MySQL setups needs configuration changes
−Advanced MySQL features may have limited support due to Vitess compatibility layer
−Transaction support is available but less intuitive than traditional connection-based transaction APIs
−No connection pooling benefits for long-running Node.js servers where persistent connections would be more efficient