SurrealDB class

SurrealDB client for Dart & Flutter

This client provides an interface to interact with SurrealDB via WebSockets. It supports authentication, database operations, and middleware for request manipulation.

Example usage with token refresh middleware:

final db = SurrealDB('ws://localhost:8000');
db.connect();
await db.wait();

// Add a token refresh middleware
db.addMiddleware((method, params, next) async {
  try {
    // Try to execute the request normally
    return await next();
  } catch (e) {
    // If we get an authentication error
    if (e.toString().contains('authentication invalid')) {
      // Refresh the token
      final newToken = await refreshToken(); // Your token refresh logic

      // Re-authenticate with the new token
      await db.authenticate(newToken);

      // Retry the original request
      return await next();
    }
    // For other errors, just rethrow
    rethrow;
  }
});

// Now all requests will automatically refresh the token if needed
final results = await db.select('users');

Constructors

SurrealDB.new(String url, {String? token, SurrealDBOptions options = const SurrealDBOptions()})

Properties

hashCode → int
The hash code for this object.
no setterinherited
options → SurrealDBOptions
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
token → String?
final
url → String
final

Methods

addMiddleware(Middleware middleware) → void
Adds a middleware function to be executed before each request
authenticate(String token) → Future<void>
Authenticates the current connection with a JWT token.
close() → void
Closes the persistent connection to the database.
connect() → void
Connects to a local or remote database endpoint.
create(String thing, dynamic data) → Future<Object?>
Creates a record in the database.
delete(String thing) → Future<void>
Deletes all records in a table, or a specific record, from the database thing is the table name or the record id.
info() → Future<Object?>
Retreives the record of an authenticated user.
invalidate() → Future<void>
Invalidates the authentication for the current connection.
let(String key, String val) → Future<String>
Assigns a value as a parameter for this connection. Name of the parameter is key and the value is val.
liveQuery(String query, [Map<String, Object?>? vars]) → Future<LiveQuery>
Subscribes to a live query.
liveTable(String table, [Map<String, Object?>? vars]) → Future<LiveQuery>
Subscribes to a table.
merge(String thing, [Object? data]) → Future<void>
Merges specified data into either all records in a table or a single record.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
patch(String thing, [List<Patch>? data]) → Future<Object?>
Patches either all records in a table or a single record with specified patches.
ping() → Future<void>
Pings SurrealDB instance
query(String query, [Map<String, Object?>? vars]) → Future<Object?>
Runs a set of SurrealQL statements against the database. The statements are specified in the query parameter. The vars parameter is used to pass variables to the query. Returns the result of the query.
relate(String in_, String relation, String out, [Object? data]) → Future<Object?>
Relates two records with a specified relation.
run(String name, [String? version, List<Object?>? args]) → Future<Object?>
Executes built-in functions, custom functions, or machine learning models with optional arguments
select<T>(String thing) → Future<List<T>>
Selects all records in a table, or a specific record, from the database. The table name or the record id is specified in the thing parameter. Returns a list of records.
signin({String? user, String? pass, String? namespace, String? database, String? access, Map<String, Object?>? extra}) → Future<String>
Signs in a user using the query defined in a record access method.
signup({String? user, String? pass, String? namespace, String? database, String? access, Map<String, Object?>? extra}) → Future<String>
Signs up a new user using the query defined in a record access method
toString() → String
A string representation of this object.
inherited
unset(String key) → Future<void>
Removes a variable from the current connection. The name of the variable to remove is specified in the key parameter.
update(String thing, [Object? data]) → Future<Object?>
Updates all records in a table, or a specific record, in the database.
upsert(String thing, [Object? data]) → Future<Object?>
Updates all records in a table, or a specific record, in the database. If the record does not exist, it is created.
use(String? namespace, String? database) → Future<void>
Specifies or unsets the namespace and/or database.
version() → Future<Object?>
Returns version information about the database/server.
wait() → Future<void>
Waits for the connection to the database to succeed.

Operators

operator ==(Object other) → bool
The equality operator.
inherited