Surreal.Instance

The Instance static singleton ensures that a single database instance is available across very large or complicated applications. With the singleton, only one connection to the database is instantiated, and the database connection does not have to be shared across components or controllers.

const Surreal = require('surrealdb.js');

async function main() {
	try {
		// Connect to the database
		await Surreal.Instance.connect('https://cloud.surrealdb.com/rpc');
		// Select a namespace + database
		await Surreal.Instance.use("test", "test");
		// Create or update a specific record
		await Surreal.Instance.update("person:tobie", {
			name: 'Tobie',
		});
	} catch (e) {
		console.error('ERROR', e);
	}
}

main();

db.connect(url)

Connects to a local or remote database endpoint.

// 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');

db.wait()

Waits for the connection to the database to succeed.

await db.wait();

db.close()

Closes the persistent connection to the database.

db.close();

db.use(ns, db)

Switch to a specific namespace and database.

await db.use('test', 'test');

db.signup(vars)

Signs up to a specific authentication scope.

let token = await db.signup({
	NS: 'test',
	DB: 'test',
	SC: 'user',
	email: 'info@surrealdb.com',
	pass: '123456',
});

db.signin(vars)

Signs in to a specific authentication scope.

let token = await db.signin({
	NS: 'test',
	DB: 'test',
	SC: 'user',
	email: 'info@surrealdb.com',
	pass: '123456',
});

db.invalidate()

Invalidates the authentication for the current connection.

await db.invalidate();

db.authenticate(token)

Authenticates the current connection with a JWT token.

await db.authenticate('eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJTdXJyZWFsREIiLCJpYXQiOjE1MTYyMzkwMjIsIm5iZiI6MTUxNjIzOTAyMiwiZXhwIjoxODM2NDM5MDIyLCJOUyI6InRlc3QiLCJEQiI6InRlc3QiLCJTQyI6InVzZXIiLCJJRCI6InVzZXI6dG9iaWUifQ.N22Gp9ze0rdR06McGj1G-h2vu6a6n9IVqUbMFJlOxxA');

db.let(key, val)

Assigns a value as a parameter for this connection.

// Assign the variable on the connection
await db.let('name', {
	first: 'Tobie',
	last: 'Morgan Hitchcock',
});
// Use the variable in a subsequent query
await db.query('CREATE person SET name = $name');
// Use the variable in a subsequent query
await db.query('SELECT * FROM person WHERE name.first = $name.first');

db.query(sql, vars)

Runs a set of SurrealQL statements against the database.

// Assign the variable on the connection
let result = await db.query('CREATE person; SELECT * FROM type::table($tb);', {
	tb: 'person',
});
// Get the first result from the first query
let created = result[0].result[0];
// Get all of the results from the second query
let people = result[1].result;

db.select(thing)

Selects all records in a table, or a specific record, from the database.

// Select all records from a table
let people = await db.select('person');
// Select a specific record from a table
let person = await db.select('person:h5wxrf2ewk8xjxosxtyc');

This function will run the following query in the database:

SELECT * FROM $thing;

db.create(thing, data)

Creates a record in the database.

// Create a record with a random ID
let person = await db.create('person');
// Create a record with a specific ID
let record = await db.create('person:tobie', {
	name: 'Tobie',
	settings: {
		active: true,
		marketing: true,
	},
});

This function will run the following query in the database:

CREATE $thing CONTENT $data;

db.update(thing, data)

Updates all records in a table, or a specific record, in the database.

This function replaces the current document / record data with the specified data.

// Update all records in a table
let people = await db.update('person');
// Update a record with a specific ID
let person = await db.update('person:tobie', {
	name: 'Tobie',
	settings: {
		active: true,
		marketing: true,
	},
});

This function will run the following query in the database:

UPDATE $thing CONTENT $data;

db.change(thing, data)

Modifies all records in a table, or a specific record, in the database.

This function merges the current document / record data with the specified data.

// Update all records in a table
let people = await db.change('person', {
	updated_at: new Date(),
});
// Update a record with a specific ID
let person = await db.change('person:tobie', {
	updated_at: new Date(),
	settings: {
		active: true,
	},
});

This function will run the following query in the database:

UPDATE $thing MERGE $data;

db.modify(thing, data)

Applies JSON Patch changes to all records, or a specific record, in the database.

This function patches the current document / record data with the specified JSON Patch data.

// Update all records in a table
let people = await db.modify('person', [
	{ op: "replace", path: "/created_at", value: new Date() },
]);
// Update a record with a specific ID
let person = await db.modify('person:tobie', [
	{ op: "replace", path: "/settings/active", value: false },
	{ op: "add", "path": "/tags", "value": ["developer", "engineer"] },
	{ op: "remove", "path": "/temp" },
]);

This function will run the following query in the database:

UPDATE $thing PATCH $data;

db.delete(thing)

Deletes all records in a table, or a specific record, from the database.

// Delete all records from a table
await db.delete('person');
// Delete a specific record from a table
await db.delete('person:h5wxrf2ewk8xjxosxtyc');

This function will run the following query in the database:

DELETE * FROM $thing;