realm

Description:

realm

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™.
Features #

Mobile-first: Realm is the first database built from the ground up to run directly inside phones, tablets, and wearables.
Simple: Realm’s object-oriented data model is simple to learn, doesn’t need an ORM, and the API lets you write less code to get apps up & running in minutes.
Modern: Realm supports latest Dart and Flutter versions and is built with sound null-safety.
Fast: Realm is faster than even raw SQLite on common operations while maintaining an extremely rich feature set.
MongoDB Atlas Device Sync: Makes it simple to keep data in sync across users, devices, and your backend in real-time. Get started for free with a template application and create the cloud backend.

Getting Started #


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;
}
copied to clipboard


Generate RealmObject class Car from data model class _Car.
dart run realm generate
copied to clipboard


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);
});
copied to clipboard


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'");
copied to clipboard


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)));
copied to clipboard


Samples #
For complete samples check the Realm Flutter and Dart Samples.
Documentation #
For API documentation go to


Realm Flutter API Docs


Realm Dart API Docs


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:

App Services Overview
Device Sync Overview

Realm Flutter SDK #
Realm Flutter package is published to realm.
Environment setup for Realm Flutter #

Realm Flutter supports the platforms iOS, Android, Windows, MacOS and Linux.
Flutter 3.10.2 or newer.
For Flutter Desktop environment setup, see Desktop support for Flutter.
Cocoapods v1.11 or newer.
CMake 3.21 or newer.

Usage #
The full contents of catalog.dart is listed after the usage


Add realm package to a Flutter application.
flutter pub add realm
copied to clipboard


For running Flutter widget and unit tests run the following command to install the required native binaries.
dart run realm install
copied to clipboard


Import Realm in a dart file (ex. catalog.dart).
import 'package:realm/realm.dart';
copied to clipboard


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';
copied to clipboard


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;
}
copied to clipboard


Generate RealmObject class Item from data model class _Item.
On Flutter use dart run realm to run realm package commands
dart run realm generate
copied to clipboard
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();
copied to clipboard


Full contents of 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();
copied to clipboard
Realm Dart Standalone SDK #
Realm Dart package is published to realm_dart.
Environment setup for Realm Dart #

Realm Dart supports the platforms Windows, Mac and Linux.
Dart SDK 3.0.2 or newer.

Usage #


Add realm_dart package to a Dart application.
dart pub add realm_dart
copied to clipboard


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
copied to clipboard


Import realm_dart in a dart file (ex. catalog.dart).
import 'package:realm_dart/realm.dart';
copied to clipboard


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
copied to clipboard
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.


Sync data with Realm Flutter and Dart using Device Sync #
This section is about how to use the Realm with Device Sync and how to connect to Atlas App Services.
I. Set up Atlas App Services #

Create an account on cloud.mongodb.com. Follow the instructions: Register a new Atlas Account.
Create a new App following the instructions here: Create an App with Atlas App Services UI.
Read Authentication Providers to see how to configure the appropriate authentication provider type.
Go to the Device Sync menu and Enable Flexible Sync.
Find and Copy the App ID of your new application.

II. Use Device Sync with the Realm #


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());
copied to clipboard


Open a synced realm.
final config = Configuration.flexibleSync(user, [Task.schema]);
final realm = Realm(config);
copied to clipboard


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();
copied to clipboard


To learn more about how to sync data with Realm using Device Sync, refer to the Quick Start with Sync documentation.
Building the source #
See CONTRIBUTING.md for instructions about building the source.
Code of Conduct #
This project adheres to the MongoDB Code of Conduct.
By participating, you are expected to uphold this code. Please report
unacceptable behavior to [email protected].
License #
Realm Flutter and Dart SDKs and Realm Core are published under the Apache License 2.0.
The "Dart" name and logo and the "Flutter" name and logo are trademarks owned by Google.