When creating a new connection to a SurrealDB instance, you can choose to 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.
First, you need to initialize a new instance of SurrealDB and connect it to a database endpoint. Using the .connect()
method, you can specify the connection details such as the URL, namespace, and database.
While the .connect()
method is the primary method to connect to a SurrealDB instance, there are other methods that you can use while managing your connection.
Method | Description |
---|---|
db.connect(url, options) | Connects to a local or remote database endpoint |
db.close() | Closes the persistent connection to the database |
db.wait() | Waits for the connection to the database to succeed |
db.use(namespace,database) | Switch to a specific namespace and database |
.connect()
The .connect()
method accepts a url
and an options
object. In the options
object, you can specify the namespace
and database
to use, as well as the auth
details which can be a token or a pair of credentials.
This means that the .use()
method is not required if you specify the namespace
and database
in the options
object. However, if you want to switch to a different namespace or database, you should use the .use()
method. Depending on the use case, you can also specify advanced custom logic for the connection.
You can specify your connection protocol either as http
, https
, ws
, or wss
. Since SurrealDB also supports RPC over WebSocket, by default, it is specified with a /rpc
suffix.
// 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 }, });
.use()
Depending on the complexity of your use case, you can switch to a specific namespace and database using the .use()
method. This is particularly useful if you want to switch to a different setup after connecting. You can also stay in the same namespace but switch to a different database.
Learn more about the .use()
method in the methods section.
await db.use({ namespace: 'surrealdb', database: 'docs' });
.wait()
The .wait()
method is used to wait for the connection to the database to succeed. This is particularly useful if you want to ensure that the connection is established before executing any queries.
ImportantCall this method after
.connect()
to ensure that the connection is established before executing any queries.
await db.wait();
.close()
The .close()
method closes the persistent connection to the database. You should always call this method when you are done with the connection to free up resources.
await db.close();
Here is an example of the .connect()
, .use()
, .wait()
, and .close()
methods in action.
Exampleimport Surreal from "surrealdb"; // Define the database configuration interface interface DbConfig { url: string; namespace: string; database: string; } // Define the default database configuration const DEFAULT_CONFIG: DbConfig = { url: "http://127.0.0.1:8000/rpc", namespace: "test", database: "test", }; // Define the function to get the database instance export async function getDb(config: DbConfig = DEFAULT_CONFIG): Promise<Surreal> { const db = new Surreal(); try { await db.connect(config.url); await db.use({ namespace: config.namespace, database: config.database }); return db; } catch (err) { console.error("Failed to connect to SurrealDB:", err instanceof Error ? err.message : String(err)); await db.close(); throw err; } }