Initialization

After installing the SDK and selecting your import choice. You can initialize a new instance of SurrealDB and connect it to a database endpoint, which can be local or remote.

TypeScript

../utils/surreal.ts
import { Surreal } from "surrealdb.js";

let db: Surreal | undefined;

export async function initDb(): Promise<Surreal | undefined> {
    if (db) return db;
    const db = new Surreal();
    try {
        await db.connect("http://127.0.0.1:8000/rpc");
        await db.use({ namespace: "test", database: "test" });
        return db;
    } catch (err) {
        console.error("Failed to connect to SurrealDB:", err);
        throw err;
    }
}

export async function closeDb(): Promise<void> {
    if (!db) return;
    await db.close();
    db = undefined;
}

export function getDb(): Surreal | undefined {
    return db;
}

JavaScript

../utils/surreal.js
import { Surreal } from "surrealdb.js";

let db;

export async function initDb() {
    if (db) return db;
    const db = new Surreal();
    try {
        await db.connect("http://127.0.0.1:8000/rpc");
        await db.use({ namespace: "test", database: "test" });
        return db;
    } catch (err) {
        console.error("Failed to connect to SurrealDB:", err);
        throw err;
    }
}

export async function closeDb() {
    if (!db) return;
    await db.close();
    db = undefined;
}

export function getDb() {
    return db;
}

From the code snippet above, you can see that the JavaScript SDK has a couple of methods that you can use to initialize a new project with SurrealDB.

Take a look at some of the methods below:

.connect()

Connects to a local or remote database endpoint.

Method Syntax
async db.connect(url, options)

Arguments

Arguments		Description
url		The url of the database endpoint to connect to.
options		An object with options to initiate the connection to SurrealDB.

Example usage

There are several ways to connect to a database endpoint. You can connect to a local or remote endpoint, specify a namespace and database pair to use, authenticate with an existing token, authenticate using a pair of credentials, or use advanced custom logic to prepare the connection to the database.

// Connect to a local endpoint
await db.connect('http://127.0.0.1:8000/rpc');

// Connect to a remote endpoint
await db.connect('https://cloud.surrealdb.com/rpc');

// Specify a namespace and database pair to use
await db.connect('https://cloud.surrealdb.com/rpc', {
	namespace: 'surrealdb',
	database: 'docs',
});

// Authenticate with an existing token
// The .authenticate() function is used under the hood.
await db.connect('https://cloud.surrealdb.com/rpc', {
	auth: '.....',
});

// Authenticate using a pair of credentials
await db.connect('https://cloud.surrealdb.com/rpc', {
	auth: {
		username: 'root',
		password: 'surrealdb',
	},
});

// Use advanced custom logic to prepare the connection to the database
await db.connect('https://cloud.surrealdb.com/rpc', {
	prepare: async (db) => {
		await db.use({ namespace: 'surrealdb', database: 'docs' });

		const token = await retrieveToken();
		if (token) await db.authenticate(token);

		// Any queries executed before the .prepare() function finishes will be forced to wait
		// Please note that this is also the case for queries executed within the prepare function
		// Doing so can cause the connection to stay in a initializing state
	},
});

.wait()

Waits for the connection to the database to succeed.

Method Syntax
async db.wait()

Example usage

await db.wait();

.close()

Closes the persistent connection to the database.

Method Syntax
async db.close()

Example usage

await db.close();

.use()

Switch to a specific namespace and database. If only the ns or db property is specified, the current connection details will be used to fill the other property.

Method Syntax
db.use({` { namespace, database } `})

Arguments

Arguments		Description
namespaceINITIALLY REQUIRED		Switches to a specific namespace.
databaseINITIALLY REQUIRED		Switches to a specific database.

Example usage

await db.use({ namespace: 'surrealdb', database: 'docs' });

.info()

This method returns the record of an authenticated scope user.

Method Syntax
async db.info<T>()

Example usage

const user = await db.info();

What's on your mind?

Create GitHub Issue

Quickest way to alert
our team of a problem.