https://github.com/duhanbalci/surrealdb_flutter
SurrealDB client written in pure dart. auto reconnect, typed functions
https://github.com/duhanbalci/surrealdb_flutter
surrealdb surrealdb-driver
Last synced: about 2 months ago
JSON representation
SurrealDB client written in pure dart. auto reconnect, typed functions
- Host: GitHub
- URL: https://github.com/duhanbalci/surrealdb_flutter
- Owner: duhanbalci
- License: mit
- Created: 2022-09-16T05:27:04.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2025-04-03T17:37:36.000Z (2 months ago)
- Last Synced: 2025-04-03T18:34:36.570Z (2 months ago)
- Topics: surrealdb, surrealdb-driver
- Language: Dart
- Homepage:
- Size: 92.8 KB
- Stars: 46
- Watchers: 4
- Forks: 11
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome-surreal - surrealdb-flutter - Client library for [Dart](https://dart.dev) and [Flutter](https://flutter.dev). (Client libraries)
README
# SurrealDB Client For Dart & Flutter
[](https://github.com/duhanbalci/surrealdb_flutter/actions/workflows/dart-test.yml)
This is a Dart client library for interacting with [SurrealDB](https://surrealdb.com/docs/), 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`:
```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.
```dart
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:
```dart
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:
```dart
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:
```dart
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:
```dart
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:
```dart
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
```dart
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.
```dart
final posts = await db.select('posts');
print('Fetched posts: $posts');
```
You can also use queries to filter or manipulate the data:
```dart
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:
```dart
final updatedData = {'title': 'Updated post title'};
await db.update('posts:id', updatedData);
print('Record updated successfully');
```
#### 3.4 Delete Records
To delete a record:
```dart
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.
```dart
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](https://pub.dev/documentation/surrealdb/latest).
## 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`](https://github.com/duhanbalci/surrealdb_flutter/blob/main/LICENSE) file for more details.