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.

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

let db: Surreal | undefined;

export async function initDb(): Promise<Surreal | undefined> {
    if (db) return db;
    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;
}

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

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

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

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();