async db.connect(url, options)

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

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

async db.close()

Closes the persistent connection to the database.

await db.close();

db.use({ namespace, database })

Switch to a specific namespace and database. If only the namespace or database property is specified, the current connection details will be used to fill the other property.

await db.use({ namespace: 'surrealdb', database: 'docs' });

async db.info()

This method returns the record of an authenticated scope user.

const user = await db.info();

async db.signup({ namespace, database, scope, [...] })

Signs up to a specific authentication scope.

const token = await db.signup({
	namespace: 'surrealdb',
	database: 'docs',
	scope: 'user',

	// Also pass any properties required by the scope definition
	email: 'info@surrealdb.com',
	password: '123456',
});

async db.signin({ ... })

Signs in to a root, namespace, database or scope user.

// Authenticate with a root user
const token = await db.signin({
	username: 'root',
	password: 'surrealdb',
});

// Authenticate with a Namespace user
const token = await db.signin({
	namespace: 'surrealdb',
	username: 'tobie',
	password: 'surrealdb',
});

// Authenticate with a Database user
const token = await db.signin({
	namespace: 'surrealdb',
	database: 'docs',
	username: 'tobie',
	password: 'surrealdb',
});

// Authenticate with a Scope user
const token = await db.signin({
	namespace: 'surrealdb',
	database: 'docs',
	scope: 'user',

	// Also pass any properties required by the scope definition
	email: 'info@surrealdb.com',
	password: '123456',
});

async db.invalidate()

Invalidates the authentication for the current connection.

await db.invalidate();

async db.authenticate(token)

Authenticates the current connection with a JWT token.

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

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

async db.unset(key)

Removes a parameter for this connection.

// Remove the variable from the connection
await db.unset('name');

async db.query(query, vars)

Runs a set of SurrealQL statements against the database.

// Assign the variable on the connection
         const result = await db.query(
      'CREATE person SET name = "John"; SELECT * FROM type::table($tb);',
{ tb: 'person' }
);

// Get the first result from the first query
const created = result[0].result[0];

// Get all of the results from the second query
const people = result[1].result;

async db.select(thing)

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

// Select all records from a table
const people = await db.select('person');

// Select a specific record from a table
const [person] = await db.select('person:h5wxrf2ewk8xjxosxtyc');

This function will run the following query in the database:

SELECT * FROM $thing;

async db.create(thing, data)

Creates a record in the database.

// Create a record with a random ID
const [person] = await db.create('person');

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

// The content you are creating the record with might differ from the return type
const [record] = await db.create('person:tobie', {
	name: 'Tobie',
});

This function will run the following query in the database:

CREATE $thing CONTENT $data;

async db.insert(thing, data)

Insers one or multiple records in the database.

// Insert a single record
const [person] = await db.insert('person', {
	name: 'Tobie',
	settings: {
		active: true,
		marketing: true,
	},
});

// Insert multiple records
const people = await db.insert('person', [
	{
		name: 'Tobie',
		settings: {
			active: true,
			marketing: true,
		},
	},
	{
		name: 'Jaime',
		settings: {
			active: true,
			marketing: true,
		},
	},
]);

// The content you are creating the record with might differ from the return type
const people = await db.insert('person', [
	{ name: 'Tobie' },
	{ name: 'Jaime' },
]);

This function will run the following query in the database:

INSERT INTO $thing $data;

async 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
const people = await db.update('person');

// Update a record with a specific ID
const [person] = await db.update('person:tobie', {
	name: 'Tobie',
	settings: {
		active: true,
		marketing: true,
	},
});

// The content you are updating the record with might differ from the return type
const [record] = await db.update('person:tobie', {
	name: 'Tobie',
});

This function will run the following query in the database:

UPDATE $thing CONTENT $data;

async db.merge(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
const people = await db.merge('person', {
	updated_at: new Date(),
});

// Update a record with a specific ID
const [person] = await db.merge('person:tobie', {
	updated_at: new Date(),
	settings: {
		active: true,
	},
});

// The content you are merging the record with might differ from the return type
const [record] = await db.merge('person:tobie', {
	name: 'Tobie',
});

This function will run the following query in the database:

UPDATE $thing MERGE $data;

async db.patch(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
const people = await db.patch('person', [
	{ op: 'replace', path: '/created_at', value: new Date() },
]);

// Update a record with a specific ID
const [person] = await db.patch('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;

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