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

# Vercel

Use SurrealDB with Vercel - Next.js apps, the AI SDK, eve agents and Vercel Sandbox - with connection, credential and runtime guidance that applies to all four.

These pages show how to use SurrealDB with Vercel's frameworks and compute: Next.js applications, the AI SDK, agents built with eve, and Vercel Sandbox. Each page uses the [`surrealdb`](/docs/reference/javascript.md) JavaScript SDK directly, so no adapter package is needed.

> [!NOTE]
> This section is about running your own SurrealDB database. For managed long-term memory for agents, see [SurrealDB Agent Memory](/docs/agent-memory.md), which has its own [AI SDK](/docs/agent-memory/integrations/ai-sdks/vercel-ai-sdk.md) and [eve](/docs/agent-memory/integrations/frameworks/eve.md) integrations.

## Choose a page

| Page | Use it to |
| --- | --- |
| [Next.js](/docs/build/integrations/vercel/nextjs.md) | Read and write data from Server Components, Server Actions and Route Handlers, and stream live updates to the browser. |
| [AI SDK](/docs/build/integrations/vercel/ai-sdk.md) | Store embeddings, give a model search and graph tools, and keep chat history in SurrealDB. |
| [Eve](/docs/build/integrations/vercel/eve.md) | Give an eve agent tools that query your data, and back an eve memory slot with SurrealDB. |
| [Vercel Sandbox](/docs/build/integrations/vercel/vercel-sandbox.md) | Start a temporary SurrealDB server inside a sandbox, or let sandboxed code query your database with limited access. |

## Where the database runs

Vercel Functions and sandboxes run your code, but they do not keep data between invocations. Run SurrealDB as a separate server, either on [SurrealDB Cloud](/docs/running/cloud.md) or on infrastructure that you manage, and connect to it from Vercel. Place the database in or near the region where your functions run, because every query is a network round trip.

A sandbox can run a SurrealDB server for a short time, which is useful for tests and for scratch data that an agent creates. The [Vercel Sandbox](/docs/build/integrations/vercel/vercel-sandbox.md) page describes when that is appropriate.

## Store credentials as environment variables

The examples in this section read the connection details from these environment variables:

| Variable | Example value |
| --- | --- |
| `SURREALDB_URL` | `https://<your-instance>.aws.surrealdb.cloud` |
| `SURREALDB_NAMESPACE` | `app` |
| `SURREALDB_DATABASE` | `main` |
| `SURREALDB_USER` | `app_server` |
| `SURREALDB_PASS` | The password of that user |

Add them to the Vercel project under **Settings** > **Environment Variables**, or with the Vercel CLI:

```sh
vercel env add SURREALDB_PASS
```

To use the same values on your computer, link the project and pull the variables into `.env.local`:

```sh
vercel link
vercel env pull
```

Give the application its own [database-level user](/docs/learn/security/authentication/users.md#system-users) rather than the root user. A user defined `ON DATABASE` can only reach that one database. The `EDITOR` role lets it read and write data in that database, but not manage users or access methods:

```surql
DEFINE USER app_server ON DATABASE PASSWORD 'strongPassword' ROLES EDITOR;
```

A user defined on the database signs in with the namespace and database as well as the username and password. The connection examples in this section pass both.

## Choose HTTP or WebSocket

The JavaScript SDK connects over HTTP when the URL starts with `http://` or `https://`, and over WebSocket when it starts with `ws://` or `wss://`.

- **HTTP** sends each query as its own request. Nothing has to stay open between invocations, which suits functions that can be paused or stopped at any time. Use it for server-side code on Vercel.
- **WebSocket** keeps one connection open and is required for [live queries](/docs/reference/javascript/concepts/live-queries.md). Use it in the browser, where the page stays open, or in a long-running process.

[Connecting from serverless and edge](/docs/learn/querying/concepts-and-guides/connecting-from-serverless-and-edge.md) explains the trade-offs in more detail, including token authentication and batching.

## Create the namespace and database

SurrealDB returns an error such as `The namespace 'app' does not exist` when a client selects a namespace or database that has not been defined. Start a schema file with the definitions, so the file works on an empty server:

```surql title="schema.surql"
DEFINE NAMESPACE IF NOT EXISTS app;
USE NS app;
DEFINE DATABASE IF NOT EXISTS main;
USE DB main;

-- Tables, fields and indexes follow
```

Send the file to the `/sql` endpoint of the server. The pages in this section use this command to apply their schemas:

```sh
curl -X POST -u "root:secret" -H "Accept: application/json" \
  --data-binary @schema.surql http://localhost:8000/sql
```

## See also

- [JavaScript SDK](/docs/reference/javascript.md)
- [Connecting to SurrealDB](/docs/reference/javascript/concepts/connecting-to-surrealdb.md)
- [SurrealDB Cloud](/docs/running/cloud.md)