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

# SQL drivers SurrealDB extras

Use SurrealQL, live queries, describe, capabilities, database selection and vector parameters on the same connection as @surrealdb/pg and @surrealdb/mysql SQL queries.

The native client has a few methods beyond SQL. They use the same connection, namespace, database and authentication as your SQL queries.

## SurrealQL

The `surql` template runs SurrealQL. Each value binds as a variable, and a `RecordId` binds as `type::record(...)`. The result has one entry for each SurrealQL statement.

```ts
const [people] = await sql.surql`SELECT * FROM person WHERE age > ${18}`;
```

## Live queries

`live` subscribes to a table over a WebSocket. It yields `{ action, id, result }` for each change, and kills the query when the loop ends. It throws if the WebSocket drops. `LISTEN` and `NOTIFY` are not emulated.

```ts
for await (const message of sql.live("person")) {
    console.log(message.action, message.id, message.result);
}
```

A client pinned to HTTP throws `UnsupportedOnTransportError`.

## Describe

`describe` returns the column metadata and parameter types of a statement without running it.

**PostgreSQL**

```ts
const { columns, params } = await sql.describe("SELECT name FROM person WHERE name = $1");
```

**MySQL**

```ts
const { columns, params } = await sql.describe("SELECT name FROM person WHERE name = ?");
```

## Capabilities

`capabilities()` returns `{ supported, reason?, version?, transport }`. It reports `supported: false` with a reason when the instance denies the method or the dialect route.

```ts
console.log(await sql.capabilities());
```

## Another database

`withDatabase` returns a client for another database on the same instance.

```ts
const archive = sql.withDatabase("archive");
```

## Vector parameters

In `@surrealdb/pg`, `sql.vector(values)` binds a vector parameter, for use with a vector distance operator.

```ts
await sql`SELECT id FROM item ORDER BY embedding <-> ${sql.vector([0.1, 0.2, 0.3])} LIMIT 5`;
```

Vector columns decode to `Float32Array` in both packages.

> [!NOTE]
> The shapes of the `query_cancel` and `describe` replies may still change.