Skip to content

PLANETSCALE 2022-08-18 Tier 3

Read original ↗

PlanetScale — Introducing the PlanetScale serverless driver for JavaScript

Summary

Taylor Barnett and Matt Robenolt (PlanetScale, 2022-08-18) launch the PlanetScale serverless driver for JavaScript — a Fetch-API-compatible MySQL client that reaches a PlanetScale database over secure HTTP instead of the MySQL binary protocol. This is the first shipping consumer of the PlanetScale HTTP API and the public launch of the infrastructure that backs it: "Backing our new driver is a new HTTP API and global routing infrastructure to support it." The launch solves a structural incompatibility — runtimes like Cloudflare Workers, Vercel Edge Functions, and Netlify Edge Functions "require external connections to be made over HTTP and not other networking protocols," so a MySQL client that speaks the raw TCP binary protocol is simply not usable from those environments. Beyond unblocking serverless, the HTTP interface brings four latency/scale wins called out in the post: TLS 1.3 faster connections, HTTP/2 connection multiplexing, protocol compression (gzip / brotli / snappy), and global routing — the last described explicitly as CDN-like: "A client connects to the closest geographic edge in our network, then backhauls over long-held connection pools over our internal network to reach the actual destination. Within the US, connections from US West to a database in US East reduce latency by 100ms or more in some cases, even more as the distance increases."

Key takeaways

  1. Serverless / edge runtimes physically cannot speak raw MySQL — the platforms only permit HTTP(S) egress. "Connections with other MySQL drivers speak the MySQL binary protocol over a raw TCP socket. Our new driver uses secure HTTP, which allows you to use PlanetScale in these constrained environments." This is a platform constraint, not a design preference — canonical wiki statement of concepts/serverless-tcp-socket-restriction.

  2. The driver is Fetch-API-compatible, not Node-specific. "The driver works in any environment that uses the Fetch API." This is the shipping API boundary that lets the same @planetscale/database npm package run across Cloudflare Workers, Vercel Edge, Netlify Edge, Node.js, and browser contexts — the Fetch API is the portability substrate.

  3. HTTP gives PlanetScale four structural wins beyond serverless unblocking. Quoted verbatim: "a modern TLS stack for faster connections with TLS 1.3, connection multiplexing with HTTP/2, protocol compression with gzip, brotli, or snappy, all of which lead to a better experience for serverless environments." Each item maps to a wiki concept:

  4. TLS 1.3 → concepts/tls-1-3-zero-rtt-handshake
  5. HTTP/2 multiplexing → concepts/connection-multiplexing-over-http

  6. Compression is an HTTP API advantage the MySQL wire protocol cannot match (the MySQL protocol has no first-class client-compression negotiation for uploaded query bytes).

  7. Global routing infrastructure launched alongside the driver. "Our new infrastructure and APIs also enable global routing. Similar to a CDN, global routing reduces latency drastically in situations where a client is connecting from a geographically distant location… A client connects to the closest geographic edge in our network, then backhauls over long-held connection pools over our internal network to reach the actual destination." This is the first public announcement of the PlanetScale Global Network — later disclosed in full architectural detail by the 2024-04-17 global-replica-credentials launch (sources/2026-04-21-planetscale-introducing-global-replica-credentials).

  8. Quantified latency win: "Within the US, connections from US West to a database in US East reduce latency by 100ms or more in some cases, even more as the distance increases." Canonical wiki datum for concepts/edge-to-origin-database-latency — the coast-to-coast database-connection cost that the Global Network's edge-termination + long-held backhaul is built to amortise away.

  9. HTTP API status (Aug 2022): intentionally undocumented. "Note: The HTTP API is currently not documented, but we plan on documenting it when we're ready to officially release it." The serverless driver is the only supported way to call the HTTP API at this point; the protocol contract is an implementation detail of the driver package, not a public surface. (Consistent with the stance in the later Faster MySQL with HTTP/3 benchmark post: "This API is not documented for public consumption just yet.")

  10. SQL injection prevention is a first-class driver feature. "The driver also handles your SQL sanitization to help prevent security issues like SQL injection." Parameterised queries via positional placeholders: conn.execute('SELECT * FROM users WHERE email=?', ['foo@example.com']). The driver is the sanitisation boundary — not the HTTP API, not the Vitess origin — so the same safety property that native MySQL drivers provide is preserved in the HTTP transport version.

  11. Demo application covers all three target edge runtimes. "You can see the Cloudflare Workers, Vercel Edge Functions, and Netlify Edge Functions examples in their own subdirectory." The f1-championship-stats repo is structured as one app × three edge-runtime deployments × one database — the canonical cross-serverless-vendor demo for the driver.

Systems introduced / canonicalised

Concepts introduced / canonicalised

Patterns introduced / canonicalised

Operational numbers

  • Latency improvement (US West → US East): "100ms or more in some cases, even more as the distance increases." Stated as a directional ballpark from the launch copy; no p50 / p95 / p99 disclosure.
  • npm install: npm install @planetscale/database.
  • Configuration: host / username / password from the PlanetScale dashboard's Connect dropdown → select planetscale/database → recommended to store in serverless-platform environment variables.

Caveats

  • HTTP API is undocumented. "The HTTP API is currently not documented, but we plan on documenting it when we're ready to officially release it." The driver is the sole supported consumer at launch; hand-rolled HTTP clients against this API are not supported.
  • No Connection object lifecycle in serverless code. The connect() returns a driver handle, not a persistent socket — a new transaction is each execute(). Long-lived session state (e.g. SET variables, session transactions, prepared-statement cursors) is not the programming model this driver targets; it's structurally serverless / stateless.
  • Fetch-API dependency is load-bearing. Runtimes without fetch() (or with non-standard fetch() implementations) aren't supported; the driver does not ship a polyfill.
  • "100ms or more" is a qualitative number. No benchmark tables; no reference runtime; no geographic grid. The rigorous numeric disclosure for the HTTP API comes two years later in sources/2026-04-21-planetscale-faster-mysql-with-http3.
  • Protocol compression is listed as a capability, not quantified. "gzip, brotli, or snappy" — but no per-codec wire-size reduction numbers, no CPU-cost disclosure on the driver-side serverless-runtime budget.
  • Browser targeting unclear. The Fetch-API compatibility claim implies browser usability; the launch post doesn't explicitly recommend or discourage browser-origin use of the driver, and in-browser direct database access is generally a security anti-pattern (client holds DB credentials). The later HTTP/3 post clarifies that the PlanetScale web console is the first-party browser consumer — not customer browser apps.
  • Global routing infrastructure described at one paragraph's depth. Architecture details — edge termination tier, warm backhaul pool, per-query routing, etcd-watched Route records, latency-based DNS, TabletType enum — are all withheld until the 2024-04-17 global-replica-credentials launch (sources/2026-04-21-planetscale-introducing-global-replica-credentials). This post is "there is a CDN for MySQL now"; the later post is "here's how it works."
  • No HTTP/3 at launch; HTTP/3 via quic-go shows up in the 2023-01-04 benchmark post (sources/2026-04-21-planetscale-faster-mysql-with-http3).

Why it matters on this wiki

  • Canonical first-launch evidence that concepts/serverless-tcp-socket-restriction forces a fundamental redesign of database-access protocols for serverless / edge runtimes. It isn't "native MySQL is faster, we added HTTP for convenience" — native MySQL is structurally unavailable, and HTTP is the only egress the platforms permit.
  • First wiki source that names the PlanetScale Global Network as a product primitive (even before the 2024 architecture disclosure). The Aug 2022 launch establishes the "CDN for databases" framing; the 2024 post fills in the engineering.
  • First wiki source on the HTTP-API-beside-binary-protocol pattern for OLTP MySQL. Contrasts with SQL-over-HTTP shapes for analytics warehouses (BigQuery-class) — same shape, different workload.
  • Historical archeology: paired with Faster MySQL with HTTP/3 (2023-01-04, Robenolt solo), these two posts bracket PlanetScale's public story: "we built HTTP-for-MySQL because we had to" (Aug 2022) → "here's the benchmark showing it's also faster" (Jan 2023).

Source

Last updated · 378 distilled / 1,213 read