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 JavaScript SDK directly, so no adapter package is needed.
This section is about running your own SurrealDB database. For managed long-term memory for agents, see SurrealDB Agent Memory, which has its own AI SDK and eve integrations.
Choose a page
| Page | Use it to |
|---|---|
| Next.js | Read and write data from Server Components, Server Actions and Route Handlers, and stream live updates to the browser. |
| AI SDK | Store embeddings, give a model search and graph tools, and keep chat history in SurrealDB. |
| Eve | Give an eve agent tools that query your data, and back an eve memory slot with SurrealDB. |
| Vercel Sandbox | 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 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 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:
vercel env add SURREALDB_PASSTo use the same values on your computer, link the project and pull the variables into .env.local:
vercel link
vercel env pullGive the application its own database-level user 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:
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. Use it in the browser, where the page stays open, or in a long-running process.
Connecting from serverless and edge 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:
DEFINE NAMESPACE IF NOT EXISTS app;
USE NS app;
DEFINE DATABASE IF NOT EXISTS main;
USE DB main;
-- Tables, fields and indexes followSend the file to the /sql endpoint of the server. The pages in this section use this command to apply their schemas:
curl -X POST -u "root:secret" -H "Accept: application/json" \
--data-binary @schema.surql http://localhost:8000/sql