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
- JavaScript
../utils/surreal.tsimport { Surreal } from "surrealdb.js";
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.jsimport { 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 Syntaxasync 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 Syntaxasync db.wait()
Example usage
await db.wait();
.close()
Closes the persistent connection to the database.
Method Syntaxasync 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 Syntaxdb.use({` { namespace, database } `})
Arguments
Arguments | Description | ||
---|---|---|---|
namespace | Switches to a specific namespace. | ||
database | 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 Syntaxasync db.info<T>()
Example usage
const user = await db.info();