SurrealDB Docs Logo

Enter a search query

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

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

ArgumentsDescription
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

ArgumentsDescription
namespace initially required

Switches to a specific namespace.

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

© SurrealDB GitHub Discord Community Cloud Features Releases Install