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';

	// Create a new Surreal instance
	const db = new Surreal();

	const { Surreal } = require('surrealdb');

	// Create a new Surreal instance
	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();

// Connect as record user using the WebSocket protocol
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();

	// Connect using the WebSocket protocol
	await db.connect('ws://localhost:8000', {
		namespace: "company_name",
		database: "project_name"
	});

	// Sign in as a record user
	await db.signin({
		access: "user",
		variables: {
			email: "user@example.com",
			password: "....."
		}
	});

	const db = new Surreal();

	// Connect using the WebSocket protocol
	await db.connect('ws://localhost:8000', {
		namespace: "company_name",
		database: "project_name"
	});

	// Sign up as a record user
	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();

	// Connect using the WebSocket protocol
	await db.connect('ws://localhost:8000', {
		namespace: "company_name",
		database: "project_name"
	});

	// Authenticate with an access token
	await db.authenticate(".....");

	const db = new Surreal();

	// Connect using the WebSocket protocol
	await db.connect('ws://localhost:8000', {
		namespace: "company_name",
		database: "project_name"
	});

	// Authenticate with an access and refresh token pair
	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

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';

// Create a record with a random id
const user = await db.create(users).content({
	name: 'John',
	email: 'john@example.com',
	age: 32
});

console.log(user);
// { id: user:w6xb3izpgvz4n0gow6q7, name: 'John', email: 'john@example.com', age: 32 }

// Create a record with a specific ID
const appleId = new RecordId(products, 'apple');
const product = await db.create(appleId).content({
	name: 'Apple',
	price: 1.50,
	category: 'fruit'
});

console.log(product);
// { id: product:apple, name: 'Apple', price: 1.50, category: 'fruit' }

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';

// Select all users
const users = await db.select(users);

// Select a specific record by ID
const apple = await db.select(new RecordId(products, 'apple'));

// Select specific fields with filtering
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);
// [{ name: 'Apple', price: 1.50 }]

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.