Quickstart
The JavaScript SDK for SurrealDB makes it effortless to connect to your instance and start querying data. This guide will walk you through the process of connecting to a SurrealDB instance and performing basic operations.
1. Install the SDK
Follow the installation guide to install the SDK as dependency in your project. Once installed, you can import and instantiate the SDK to start using it.
import Surreal from 'surrealdb';
const db = new Surreal();
const { Surreal } = require('surrealdb');
const db = new Surreal();
The Surreal class can be instantiated multiple times to connect to multiple SurrealDB instances at once.
2. Connect to SurrealDB
You can use the .connect() method to connect to a local or remote SurrealDB instance. This method accepts a connection string and a set of options, including namespace, database, and authentication details.
Supported connection protocols include:
- WebSocket (
ws://) for long lived connections (e.g. backend or frontend applications) - HTTP (
http://) for short lived stateless connections (e.g. server-side rendering applications) - Embedded protocols using the WebAssembly engine or Node.js engine
In order to facilitate a wide range of use cases, the SDK supports a variety of authentication options
Connecting as system user
This approach is suitable for connecting to a SurrealDB instance as a system user, for example when connecting from a server-side application.
const db = new Surreal();
await db.connect('ws://localhost:8000', {
namespace: "company_name",
database: "project_name",
authentication: {
username: 'root',
password: 'root'
}
});
Alternatively you can use the .signin() method to authenticate, however passing the authentication details to the .connect() method is the preferred way and allows for automatic reconnecting.
Connecting as record user
This approach is suitable when connecting as record user from a frontend application. Since authentication usually takes place through a login page, you can use the dedicated .signin() or .signup() methods to authenticate.
const db = new Surreal();
await db.connect('ws://localhost:8000', {
namespace: "company_name",
database: "project_name"
});
await db.signin({
access: "user",
variables: {
email: "user@example.com",
password: "....."
}
});
const db = new Surreal();
await db.connect('ws://localhost:8000', {
namespace: "company_name",
database: "project_name"
});
await db.signup({
access: "user",
variables: {
email: "user@example.com",
password: "....."
}
});
Connecting with an existing token
This approach is suitable when connecting with an existing access or refresh token.
const db = new Surreal();
await db.connect('ws://localhost:8000', {
namespace: "company_name",
database: "project_name"
});
await db.authenticate(".....");
const db = new Surreal();
await db.connect('ws://localhost:8000', {
namespace: "company_name",
database: "project_name"
});
await db.authenticate({
access: ".....",
refresh: "....."
});
3. Defining your tables
The JavaScript SDK is built to be fully type-safe and TypeScript compatible. For this reason we recommend defining table references in a central location
tables.ts
import { Table } from 'surrealdb';
const users = new Table('users');
const products = new Table('products');
3. Inserting data into SurrealDB
Once connected, you can use the .create() method to execute a CREATE query. This method accepts either a Table or a RecordId as the first argument. Use the .content() chain to specify the record data.
import { Table, RecordId } from 'surrealdb';
import { users, products } from './tables';
const user = await db.create(users).content({
name: 'John',
email: 'john@example.com',
age: 32
});
console.log(user);
const appleId = new RecordId(products, 'apple');
const product = await db.create(appleId).content({
name: 'Apple',
price: 1.50,
category: 'fruit'
});
console.log(product);
4. Retrieving data from SurrealDB
Selecting records
The .select() method retrieves all records from a table, or a single record by its RecordId. You can chain methods like .fields(), .where(), and .limit() to refine your query.
import { Table, RecordId, eq } from 'surrealdb';
import { users, products } from './tables';
const users = await db.select(users);
const apple = await db.select(new RecordId(products, 'apple'));
const results = await db.select(products)
.fields('name', 'price')
.where(eq("category", "fruit"))
.limit(10);
In addition to the .eq() function in the above example, we offer a comprehensive set of expression utilities for building type-safe SurrealQL conditions.
Running SurrealQL queries
For more advanced use cases, you can use the .query() method to run SurrealQL statements directly. Use parameters to safely pass dynamic values.
const [cheapProducts] = await db.query<[{ name: string; price: number }[]]>(
'SELECT name, price FROM product WHERE price < $max_price ORDER BY price',
{ max_price: 5.00 }
);
console.log(cheapProducts);
What’s next?
You’ve learned how to install the SDK, connect to SurrealDB, create records, and retrieve data. There’s a lot more you can do with the SDK, including updating and deleting records, handling authentication, live queries, and running embedded databases.
