SQL drivers for JavaScript

The SQL drivers are two JavaScript packages that send PostgreSQL or MySQL dialect SQL to a SurrealDB instance over HTTP and WebSocket. Use them in runtimes that cannot open a TCP socket, such as Cloudflare Workers, Vercel Edge, Deno Deploy and browsers. They also run on Node.js, Bun and Deno.

Each package has a native API (a tagged template plus query, execute, batch and begin) and a compatibility layer, so existing ORMs and query builders run on top of it.

When to use the SQL drivers

• •

  Edge, serverless and browser code. These runtimes have fetch and WebSocket but no TCP. The drivers use only those APIs.

• •

  Existing SQL code. Drizzle, Kysely, Prisma, node-postgres, mysql2, Neon and PlanetScale code can point at SurrealDB with a small change.

• •

  SurrealQL on the same connection. Every client can also run SurrealQL with the surql template, with the same namespace, database and authentication.

If your code can open TCP connections, a native driver such as pg or mysql2 can connect to the PostgreSQL or MySQL wire listener of the instance directly. If you want SurrealQL and the full data model from JavaScript, use the JavaScript SDK.

A first query

npm install @surrealdb/pg

import { connect } from "@surrealdb/pg";

const sql = connect("postgres://root:secret@abc123.surrealdb.earth/app?namespace=prod");

const name = "Tobie";
const rows = await sql`SELECT name, age FROM person WHERE name = ${name}`;

The client sends nothing until the first query. Values in a template are bound as typed parameters and are never interpolated into the SQL text.

How it works

Each statement is one RPC call: pgsql or mysql, with the SQL text, optional variables and optional options. Positional parameters ($1 for PostgreSQL, each ? for MySQL) bind to the variables _1 to _n, and the instance binds them as typed parameters. The reply holds one entry per statement, with its status, command tag, row count, column metadata and rows.

The clients use two transports and pick one by what the call needs.

With the default transport: "auto", one-shot calls use HTTP, which needs no handshake and has the lowest latency from a cold isolate. Anything that needs a session opens a WebSocket.

Next steps