> Full SurrealDB documentation index: https://surrealdb.com/docs/llms.txt

# SQL drivers for JavaScript

The @surrealdb/pg and @surrealdb/mysql packages send PostgreSQL and MySQL dialect SQL to SurrealDB over HTTP and WebSocket, for edge, serverless and browser runtimes, with drop-in layers for node-postgres, mysql2, Neon, PlanetScale, Drizzle, Kysely and Prisma.

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.

| Package | Dialect | RPC method |
| --- | --- | --- |
| [`@surrealdb/pg`](https://github.com/surrealdb/sql-drivers/tree/main/packages/pg) | PostgreSQL | `pgsql` |
| [`@surrealdb/mysql`](https://github.com/surrealdb/sql-drivers/tree/main/packages/mysql) | MySQL | `mysql` |

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](/docs/reference/javascript.md).

> [!NOTE]
> The drivers need a SurrealDB instance that serves the `pgsql` and `mysql` RPC methods. A server that does not serve them returns a "Method not found" error. The MySQL value encoding may still change.

## A first query

**PostgreSQL**

```bash
npm install @surrealdb/pg
```

```ts
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}`;
```

**MySQL**

```bash
npm install @surrealdb/mysql
```

```ts
import { connect } from "@surrealdb/mysql";

const sql = connect("mysql://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.

| | HTTP | WebSocket |
| --- | --- | --- |
| One-shot queries | Yes | Yes |
| Atomic batch | Yes | Yes |
| Interactive transactions | No | Yes |
| Live queries | No | Yes |
| Session settings that last | No, sent with every call | Yes, sent once per connection |
| Cancel a running call | Abort the request | `query_cancel` on abort or timeout |

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

- [Installation](/docs/libraries/sql-drivers/installation.md) - Install the packages and check the runtime requirements.

- [Connections](/docs/libraries/sql-drivers/connections.md) - Connection strings, authentication, transports and settings.

- [Querying](/docs/libraries/sql-drivers/querying.md) - Tagged templates, query, execute and batch.

- [Transactions](/docs/libraries/sql-drivers/transactions.md) - Atomic batches and interactive transactions.

- [Results and value types](/docs/libraries/sql-drivers/results-and-types.md) - Result shape and how column types decode.

- [Errors](/docs/libraries/sql-drivers/errors.md) - Error classes and how to handle them.

- [SurrealDB extras](/docs/libraries/sql-drivers/surrealdb-extras.md) - SurrealQL, live queries, describe and capabilities.

- [ORM and driver compatibility](/docs/libraries/sql-drivers/orm-compatibility.md) - node-postgres, mysql2, Drizzle, Kysely and Prisma.

- [Neon and PlanetScale](/docs/libraries/sql-drivers/neon-and-planetscale.md) - Drop-in entry points for the two serverless clients.