surrealdb

SurrealDB Client For Dart & Flutter

This is a Dart client library for interacting with SurrealDB, a highly scalable, distributed, and real-time database. This library enables developers to connect to SurrealDB instances, execute queries, authenticate users, and interact with database resources via WebSocket communication.

Features

• ⚡ Connect and Disconnect: Establish or close a persistent WebSocket connection to a SurrealDB instance.
• 🔐 Authentication: Authenticate with a token to manage access to the database.
• 🗄️ Database Interaction: Use namespaces and databases, retrieve user information, and fetch database versions.
• 🔄 Live Queries: Support for live querying via WebSocket streams.
• ⚙️ Customizable Options: Set connection options and behavior using SurrealDBOptions.

Installation

Add the following to your pubspec.yaml:

dependencies:
  surrealdb: ^1.0.0

Then run dart pub get or flutter pub get.

Usage

Connecting to SurrealDB

To connect to a SurrealDB, create a SurrealDB client instance and call the connect() method. You can also provide a token for authentication.

import 'package:surrealdb/surrealdb.dart';

void main() async {
  // Create a SurrealDB client instance
  final db = SurrealDB('ws://localhost:8000/rpc', token: 'your-auth-token');

  // Connect to the database
  db.connect();

  // Wait for the connection to be established
  await db.wait();

  // Use a specific namespace and database
  await db.use('namespace', 'database');

  // Fetch version information
  final version = await db.version();
  print('SurrealDB version: $version');

  // Close the connection when done
  db.close();
}

Authentication

SurrealDB requires authentication to access resources. You can sign up, sign in, and authenticate users using the SurrealDB client.

Signing Up a User

To create a new user:

final token = await db.signup(
  user: 'new_user',
  pass: 'password123',
  namespace: 'namespace',
  database: 'database',
  access: 'users',
);
print('User signed up with token: $token');

Signing In

To sign in an existing user:

final token = await db.signin(
  user: 'existing_user', 
  pass: 'password123',
  namespace: 'namespace',
  database: 'database',
  access: 'users',
);
print('User signed in with token: $token');

Token Authentication

You can also authenticate with a token:

await db.authenticate('your-auth-token');

Middleware

SurrealDB Flutter client supports middleware that allows you to intercept and modify requests before they are sent to the database. This is particularly useful for implementing token refresh functionality or adding logging.

Adding Middleware

You can add middleware using the addMiddleware method:

db.addMiddleware((method, params, next) async {
  // Do something before the request
  print('Before request: $method with params: $params');
  
  // Execute the request
  final result = await next();
  
  // Do something after the request
  print('After request: $method with result: $result');
  
  return result;
});

Multiple middleware functions can be added, and they will be executed in the order they were added.

Token Refresh Example

Here's how you can implement token refresh using 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 (implement your token refresh logic)
      final newToken = await refreshToken(); 
      
      // Re-authenticate with the new token
      await db.authenticate(newToken);
      
      // Retry the original request
      return await next();
    }
    // For other errors, just rethrow
    rethrow;
  }
});

This middleware will catch authentication errors, refresh the token, and retry the original request automatically.

Basic Queries

SurrealDB allows executing a variety of commands, including CRUD operations (Create, Read, Update, Delete) via queries. Here's how you can perform simple database operations.

3.1 Create Records

final data = {'title': 'My first post', 'content': 'Hello, SurrealDB!'};
final result = await db.create('posts', data);
print('Created record: $result');

3.2 Read Records

To retrieve records, you can use the select method.

final posts = await db.select('posts');
print('Fetched posts: $posts');

You can also use queries to filter or manipulate the data:

final specificPosts = await db.query(
  r'SELECT * FROM posts WHERE title = $title',
  {'title': 'My first post'},
);
print('Posts matching criteria: $specificPosts');

3.3 Update Records

Updating records is done by specifying the table and ID of the record:

final updatedData = {'title': 'Updated post title'};
await db.update('posts:id', updatedData);
print('Record updated successfully');

3.4 Delete Records

To delete a record:

await db.delete('posts:id');
print('Record deleted');

Live Queries

SurrealDB supports live queries over WebSocket. Use the LiveQuery class for subscribing to changes in data.

final liveQuery = await db.liveQuery('LIVE SELECT * FROM posts WHERE active = true');
liveQuery.stream.listen((event) {
  print('Received update: ${event.result}');
});

await db.create('posts', {
  'title': 'My first post',
});
await db.create('posts', {
  'title': 'My second post',
  'active': true
});

You can read more about all the available methods and classes in the API documentation.

Contributions

Contributions are welcome! Feel free to submit issues, feature requests, or pull requests to improve this library.

License

This project is licensed under the MIT License. See the LICENSE file for more details.