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™.
This project is in the Alpha stage. All API's might change without warning and no guarantees are given about stability. Do not use it in production.
Getting Started
-
Import Realm in a dart file
app.dartimport 'package:realm/realm.dart'; // import realm package part 'app.g.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
Carfrom data model class_Car.flutter pub run realm generate -
Open a Realm and add some objects.
var config = Configuration([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'");
Samples
For complete samples check the Realm Flutter and Dart Samples.
Documentation
For API documentation go to
For a complete documentation go to Realm Flutter and Dart SDK Docs.
Limitations
-
This version of Realm Flutter and Dart SDK allows working with a local only (on device) Realm database in Flutter and Dart desktop. Realm Sync functionality is not implemented.
-
It provides the functionality for creating, retrieving, querying, sorting, filtering, updating Realm objects.
-
Flutter Desktop on Linux is not supported yet.
-
Migrations are not supported yet.
If you change your data models often and receive a migration exception be sure to delete the old
default.realmfile in your application directory. It will get recreated with the new schema the next time the Realm is opened.
Realm Flutter SDK
The Realm Flutter package name is realm
Environment setup for Realm Flutter
-
Supported platforms are Flutter (iOS, Android, Windows, MacOS) and Dart standalone (Windows, MacOS and Linux)
-
Flutter ^2.8.0
-
For Flutter Desktop environment setup check the guide here
-
Cocoapods v1.11 or newer is required
Usage
The full contents of catalog.dart is listed after the usage
-
Add
realmpackage to a Flutter application.flutter pub add realm -
Import Realm in a dart file (ex.
catalog.dart).import 'package:realm/realm.dart';
-
Declare a part file
catalog.g.dartin the begining of thecatalog.dartdart file after all imports.import 'dart:io'; part 'catalog.g.dart';
-
Create a data model class.
It should start with an underscore
_Itemand be annotated with@RealmModel()@RealmModel() class _Item { @PrimaryKey() late int id; late String name; int price = 42; }
-
Generate RealmObject class
Itemfrom data model class_Item.On Flutter use
flutter pub run realmto runrealmpackage commandsflutter pub run realm generateA new file
catalog.g.dartwill be created next to thecatalog.dart.*This file should be committed to source control
-
Use the RealmObject class
Itemwith Realm.// Create a Configuration object var config = Configuration([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();
Full contents of catalog.dart
import 'package:realm/realm.dart';
part 'catalog.g.dart';
@RealmModel()
class _Item {
@PrimaryKey()
late int id;
late String name;
int price = 42;
}
// Create a Configuration object
var config = Configuration([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();
Realm Dart SDK
The Realm Dart package is realm_dart
Environment setup for Realm Dart
-
Supported platforms are Windows, Mac and Linux.
-
Dart SDK ^2.15
Usage
-
Add
realm_dartpackage to a Dart application.dart pub add realm_dart -
Install the
realm_dartpackage 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_dartto runrealm_dartpackage commandsdart run realm_dart generateA new file
catalog.g.dartwill be created next to thecatalog.dart.*This file should be committed to source control
-
For more usage of Realm Dart see the Realm Flutter usage above.
Building the source
Building Realm Flutter
- Clone the repo
git clone https://github.com/realm/realm-dart git submodule update --init --recursive
Build Realm Flutter native binaries
-
Android
./scripts/build-android.sh all scripts\build-android.bat all # Or for Android Emulator only ./scripts/build-android.sh x86 scripts\build-android.bat x86
-
iOS
./scripts/build-ios.sh # Or for iOS Simulator only ./scripts/build-ios.sh simulator -
Windows
scripts\build.bat -
MacOS
./scripts/build-macos.sh
Building Realm Dart
- Windows
scripts\build.bat - MacOS
./scripts/build-macos.sh - Linux
./scripts/build-linux.sh
Versioning
Realm Flutter and Dart SDK packages follow Semantic Versioning. During the initial development the packages will be versioned according the scheme 0.major.minor+release stage until the first stable version is reached then packages will be versioned with major.minor.patch scheme.
The first versions will follow 0.1.0+preview, 0.1.1+preview etc. Then next release stages will pick up the next minor version 0.1.2+beta, 0.1.3+beta. This will ensure dependencies are updated on dart pub get with the new alpha, beta versions. If an alpha version is released before beta and it needs to not be considered for pub get then it should be marked as prerelease with -alpha so 0.1.2-alpha etc. Updating the major version with every release stage is also possible - 0.2.0+alpha, 0.3.0+beta, 0.3.1+beta.
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.
This product is not being made available to any person located in Cuba, Iran, North Korea, Sudan, Syria or the Crimea region, or to any other person that is not eligible to receive the product under U.S. law.
![[Bug]: No items in the document field that are linked via relationship.](https://avatars.githubusercontent.com/u/22937093?v=4)
![[Bug]: Unable to install on iOS](https://avatars.githubusercontent.com/u/60294318?v=4)
![[Bug]: Sort not working](https://avatars.githubusercontent.com/u/3436399?v=4)
![[Bug]: Disconnect because of session error](https://avatars.githubusercontent.com/u/12428912?v=4)
![[Bug]: Query method with IN predicate returns empty results](https://avatars.githubusercontent.com/u/93393881?v=4)
Implementation:
3 Feb 15, 2022
351 Dec 24, 2022
12 Dec 11, 2022
0 Dec 27, 2021
14 Feb 13, 2022
80 Nov 10, 2022
12 Oct 11, 2022
786 Dec 28, 2022
347 Jan 2, 2023
0 Oct 22, 2022
4 Nov 25, 2022
20 Aug 12, 2023
14 Dec 29, 2022
61 Dec 16, 2022
54 Dec 31, 2022
3.4k Dec 30, 2022
45 Jun 19, 2021