SurrealDB Client For Dart & Flutter

Pub Version Tests GitHub Issues or Pull Requests

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

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.

Libraries

surrealdb