[!WARNING] We announced the deprecation of Atlas Device Sync + Realm SDKs in September 2024. For more information please see:
For a version of
realm-dart
without sync features, install version 20 or see thecommunity
branch.
Realm is a mobile database that runs directly inside phones, tablets or wearables. This repository holds the source code for the Realm SDK for Flutter™ and Dart™.
Import Realm in a dart file app.dart
import 'package:realm/realm.dart'; // import realm package
part 'app.realm.dart'; // declare a part file.
@RealmModel() // define a data model class named `_Car`.
class _Car {
late String make;
late String model;
int? kilometers = 500;
}
Generate RealmObject class Car
from data model class _Car
.
dart run realm generate
Open a Realm and add some objects.
var config = Configuration.local([Car.schema]);
var realm = Realm(config);
var car = Car("Tesla", "Model Y", kilometers: 5);
realm.write(() {
realm.add(car);
});
Query objects in Realm.
var cars = realm.all<Car>();
Car myCar = cars[0];
print("My car is ${myCar.make} model ${myCar.model}");
cars = realm.all<Car>().query("make == 'Tesla'");
Get stream of result changes for a query.
final cars = realm.all<Car>().query(r'make == $0', ['Tesla']);
cars.changes.listen((changes) {
print('Inserted indexes: ${changes.inserted}');
print('Deleted indexes: ${changes.deleted}');
print('Modified indexes: ${changes.modified}');
});
realm.write(() => realm.add(Car('VW', 'Polo', kilometers: 22000)));
For complete samples check the Realm Flutter and Dart Samples.
For API documentation go to
Use realm package for Flutter and realm_dart package for Dart applications.
For complete documentation of the SDKs, go to the Realm SDK documentation.
If you are using the Realm SDK for the first time, refer to the Quick Start documentation.
To learn more about using Realm with Atlas App Services and Device Sync, refer to the following Realm SDK documentation:
Realm Flutter package is published to realm.
The full contents of catalog.dart
is listed after the usage
Add realm
package to a Flutter application.
flutter pub add realm
For running Flutter widget and unit tests run the following command to install the required native binaries.
dart run realm install
Import Realm in a dart file (ex. catalog.dart
).
import 'package:realm/realm.dart';
Declare a part file catalog.realm.dart
in the begining of the catalog.dart
dart file after all imports.
import 'dart:io';
part 'catalog.realm.dart';
Create a data model class.
It should start with an underscore _Item
and be annotated with @RealmModel()
@RealmModel()
class _Item {
@PrimaryKey()
late int id;
late String name;
int price = 42;
}
Generate RealmObject class Item
from data model class _Item
.
On Flutter use dart run realm
to run realm
package commands
dart run realm generate
A new file catalog.realm.dart
will be created next to the catalog.dart
.
*The generated file should be committed to source control
Use the RealmObject class Item
with Realm.
// Create a Configuration object
var config = Configuration.local([Item.schema]);
// Opean a Realm
var realm = Realm(config);
var myItem = Item(0, 'Pen', price: 4);
// Open a write transaction
realm.write(() {
realm.add(myItem);
var item = realm.add(Item(1, 'Pencil')..price = 20);
});
// Objects `myItem` and `item` are now managed and persisted in the realm
// Read object properties from realm
print(myItem.name);
print(myItem.price);
// Update object properties
realm.write(() {
myItem.price = 20;
myItem.name = "Special Pencil";
});
// Get objects from the realm
// Get all objects of type
var items = realm.all<Item>();
// Get object by index
var item = items[1];
// Get object by primary key
var itemByKey = realm.find<Item>(0);
// Filter and sort object
var objects = realm.query<Item>("name == 'Special Pencil'");
var name = 'Pen';
objects = realm.query<Item>(r'name == $0', [name]);
// Close the realm
realm.close();
catalog.dart
import 'package:realm/realm.dart';
part 'catalog.realm.dart';
@RealmModel()
class _Item {
@PrimaryKey()
late int id;
late String name;
int price = 42;
}
// Create a Configuration object
var config = Configuration.local([Item.schema]);
// Open a Realm
var realm = Realm(config);
var myItem = Item(0, 'Pen', price: 4);
// Open a write transaction
realm.write(() {
realm.add(myItem);
var item = realm.add(Item(1, 'Pencil')..price = 20);
});
// Objects `myItem` and `item` are now managed and persisted in the realm
// Read object properties from realm
print(myItem.name);
print(myItem.price);
// Update object properties
realm.write(() {
myItem.price = 20;
myItem.name = "Special Pencil";
});
// Get objects from the realm
// Get all objects of type
var items = realm.all<Item>();
// Get object by index
var item = items[1];
// Get object by primary key
var itemByKey = realm.find<Item>(0);
// Filter and sort object
var objects = realm.query<Item>("name == 'Special Pencil'");
var name = 'Pen';
objects = realm.query<Item>(r'name == $0', [name]);
// Close the realm
realm.close();
Realm Dart package is published to realm_dart.
Add realm_dart
package to a Dart application.
dart pub add realm_dart
Install the realm_dart
package into the application. This downloads and copies the required native binaries to the app directory.
dart run realm_dart install
Import realm_dart in a dart file (ex. catalog.dart
).
import 'package:realm_dart/realm.dart';
To generate RealmObject classes with realm_dart use this command.
_On Dart use dart run realm_dart
to run realm_dart
package commands_
dart run realm_dart generate
A new file catalog.realm.dart
will be created next to the catalog.dart
.
*The generated file should be committed to source control
The usage of the Realm Dart SDK is the same like the Realm Flutter above.
This section is about how to use the Realm with Device Sync and how to connect to Atlas App Services.
Initialize the App Services App
client and authenticate a user.
String appId = "<Atlas App ID>";
final appConfig = AppConfiguration(appId);
final app = App(appConfig);
final user = await app.logIn(Credentials.anonymous());
Open a synced realm.
final config = Configuration.flexibleSync(user, [Task.schema]);
final realm = Realm(config);
Add a sync subscription and write data.
Only data matching the query in the subscription will be synced to the server and only data matching the subscription will be downloaded to the local device realm file.
realm.subscriptions.update((mutableSubscriptions) {
mutableSubscriptions.add(realm.query<Task>(r'status == $0 AND progressMinutes == $1', ["completed", 100]));
});
await realm.subscriptions.waitForSynchronization();
realm.write(() {
realm.add(Task(ObjectId(), "Send an email", "completed", 4));
realm.add(Task(ObjectId(), "Create a meeting", "completed", 100));
realm.add(Task(ObjectId(), "Call the manager", "init", 2));
});
realm.close();
To learn more about how to sync data with Realm using Device Sync, refer to the Quick Start with Sync documentation.
See CONTRIBUTING.md for instructions about building the source.
This project adheres to the MongoDB Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to community-conduct@mongodb.com.
Realm Flutter and Dart SDKs and Realm Core are published under the Apache License 2.0.