Releases: realm/realm-dart
2.1.0
2.1.0 (2024-04-17)
Enhancements
- Improve file compaction performance on platforms with page sizes greater than 4k (for example arm64 Apple platforms) for files less than 256 pages in size (Core 14.4.0).
- Add better hint to error message, if opening native library fails. (Issue #1595)
- Added support for specifying schema version on
Configuration.flexibleSync
. This allows you to take advantage of an upcoming server-side feature that will allow schema migrations for synchronized Realms. (Issue #1599) - The default base url in
AppConfiguration
has been updated to point toservices.cloud.mongodb.com
. See https://www.mongodb.com/docs/atlas/app-services/domain-migration/ for more information. (Issue #1549) - Don't ignore private fields on realm models. (Issue #1367)
- Improve performance of
RealmValue.operator==
when containing binary data. (PR #1628)
Fixed
- Using valid const, but non-literal expressions, such as negation of numbers, as an initializer would fail. (Issue #1606)
- Backlinks mistakenly included in EJson serialization. (Issue #1616)
- Fix an assertion failure "m_lock_info && m_lock_info->m_file.get_path() == m_filename" that appears to be related to opening a Realm while the file is in the process of being closed on another thread. (Core 14.5.0)
- Fixed diverging history due to a bug in the replication code when setting default null values (embedded objects included). (Core 14.5.0)
- Null pointer exception may be triggered when logging out and async commits callbacks not executed. (Core 14.5.0)
- Comparing RealmValue containing a collection to itself would return false. Semantics changed to ensure reference equality always imply equality. (Issue [#1632])
- Clearing a nested collection could end with a crash. (Core 14.5.1)
- Removing nested collections in RealmValue for synced realms throws. (Core 14.5.1)
- Fixed crash when integrating removal of already removed dictionary key. (Core 14.5.2)
Compatibility
- Realm Studio: 15.0.0 or later.
Internal
- Using Core 14.5.2.
2.0.0-beta.2
2.0.0-beta.2 (2024-03-20)
Breaking Changes
-
RealmValue.type
is now an enum of typeRealmValueType
rather thanType
. If you need the runtime type of the value wrapped inRealmValue
, useRealmValue.value.runtimeType
. (Issue #1505) -
Renamed
RealmValue.uint8List
constructor toRealmValue.binary
. (PR #1469) -
Removed the following deprecated classes and members:
AppConfiguration.localAppName
- was unused and had no effectAppConfiguration.localAppVersion
- was unused and had no effectClientResetError.isFatal
- it was alwaystrue
ClientResetError.sessionErrorCode
SyncError.codeValue
- can be accessed throughSyncError.code.code
SyncError.category
- categories were deprecated in1.6.0
SyncError.detailedMessage
- was always emptySyncError
constructor andSyncError.create
factory - sync errors are created internally by the SDK and are not supposed to be constructed by usersSyncClientError
,SyncConnectionError
,SyncSessionError
,SyncResolveError
,SyncWebSocketError
,GeneralSyncError
- consolidated intoSyncError
as part of the error simplification in1.6.0
RealmProperty.indexed
- replaced byRealmProperty.indexType
SyncErrorCategory
,SyncClientErrorCode
,SyncConnectionErrorCode
,SyncSessionErrorCode
,SyncResolveErrorCode
,SyncWebsocketErrorCode
,GeneralSyncErrorCode
- consolidated intoSyncErrorCode
as part of the error simplification in1.6.0
User.provider
- the provider is associated with each identity, so the value was incorrect for users who had more than one identity
-
The generated parts are now named
.realm.dart
instead of.g.dart
. This is because the builder is now aPartBuilder
, instead of aSharedPartBuilder
. To migrate to this version you need to update all the part declarations to match, ie.part 'x.g.dart
becomespart x.realm.dart
and rerun the generator.This makes it easier to combine builders. Here is an example of combining with
dart_mappable
:import 'package:dart_mappable/dart_mappable.dart'; import 'package:realm_dart/realm.dart'; part 'part_builder.realm.dart'; part 'part_builder.mapper.dart'; @MappableClass() @RealmModel() class $Stuff with $StuffMappable { @MappableField() late int id; @override String toString() => 'Stuff{id: $id}'; } final realm = Realm(Configuration.local([Stuff.schema])); void main(List<String> arguments) { final s = realm.write(() => realm.add(Stuff(1), update: true)); print(s.toJson()); // <-- realm object as json Realm.shutdown(); }
-
Removed
SchemaObject.properties
- instead,SchemaObject
is now an iterable collection ofProperty
. (Issue #1449) -
SyncProgress.transferredBytes
andSyncProgress.transferableBytes
have been consolidated intoSyncProgress.progressEstimate
. The values reported previously were incorrect and did not accurately represent bytes either. The new field better conveys the uncertainty around the progress being reported. With this release, we're reporting accurate estimates for upload progress, but estimating downloads is still unreliable. A future server and SDK release will add better estimations for download progress. (Issue #1562) -
Realm.logger
is no longer settable, and no longer implementsLogger
from packagelogging
. In particular you can no longer callRealm.logger.level =
. Instead you should callRealm.logger.setLogLevel(RealmLogLevel level, {RealmLogCategory? category})
that takes an optional category. If no category is exlicitly given, thenRealmLogCategory.realm
is assumed.Also, note that setting a level is no longer local to the current isolate, but shared accross all isolates. At the core level there is just one process wide logger.
Categories form a hierarchy and setting the log level of a parent category will override the level of its children. The hierarchy is exposed in a type safe manner with:
sealed class RealmLogCategory { /// All possible log categories. static final values = [ realm, realm.app, realm.sdk, realm.storage, realm.storage.notification, realm.storage.object, realm.storage.query, realm.storage.transaction, realm.sync, realm.sync.client, realm.sync.client.changeset, realm.sync.client.network, realm.sync.client.reset, realm.sync.client.session, realm.sync.server, ...
The
onRecord
stream now pumpsRealmLogRecord
s that include the category the message was logged to.If you want to hook up realm logging with conventional dart logging you can do:
Realm.logger.onRecord.forEach((r) => Logger(r.category.toString()).log(r.level.level, r.message));
If no isolate subscribes to
Realm.logger.onRecord
then the logs will by default be sent to stdout.
Enhancements
-
Realm objects can now be serialized as EJSON
import 'package:ejson/ejson.dart'; // ... class _Event { late DateTime timestamp; late String message; } // ... final ejson = toEJson(aRealmObject); final anUnmanagedRealmObject = fromEJson<Event>(ejson);
-
Added
isCollectionDeleted
toRealmListChanges
,RealmSetChanges
, andRealmMapChanges
which will betrue
if the parent object, containing the collection has been deleted. (Core 14.0.0) -
Added
isCleared
toRealmMapChanges
which will betrue
if the map has been cleared. (Core 14.0.0) -
Querying a specific entry in a collection (in particular 'first and 'last') is supported. (Core 14.0.0)
class _Owner { late List<_Dog> dogs; } realm.query<Owner>('dogs[1].age = 5'); // Query all owners whose second dog element is 5 years old realm.query<Owner>('dogs[FIRST].age = 5'); // Query all owners whose first dog is 5 years old realm.query<Owner>('dogs[LAST].age = 5'); // Query all owners whose last dog is 5 years old realm.query<Owner>('dogs[SIZE] = 10'); // Query all owners who have 10 dogs
-
Added support for storing lists and maps inside a
RealmValue
property. (Issue #1504)class _Container { late RealmValue anything; } realm.write(() { realm.add(Container(anything: RealmValue.from([1, 'foo', 3.14]))); }); final container = realm.all<Container>().first; final list = container.anything.asList(); // will throw if cast is invalid for (final item in containerValue) { switch (item.type) { case RealmValueType.int: print('Integer: ${item.value as int}'); break; case RealmValueType.string: print('String: ${item.value as String}'); break; case RealmValueType.double: print('Double: ${item.value as double}'); break; } } final subscription = list.changes.listen((event) { // The list changed });
-
Added
RealmValueType
enum that contains all the possible types that can be wrapped by aRealmValue
. (PR #1469) -
Added support for accessing
Set
andMap
types using the dynamic object API -obj.dynamic.getSet/getMap
. (PR #1533) -
Added
RealmObjectBase.objectSchema
that returns the schema for this object. In most cases, this would be the schema defined in the model, but in case the Realm is opened as dynamic (by providing an empty collection for schemaObjects in the config) or usingFlexibleSyncConfiguration
, it may change as the schema on disk changes. (Issue #1449) -
Added
Realm.schemaChanges
that returns a stream of schema changes that can be listened to. Only dynamic and synchronized Realms will emit schema changes. (Issue #1449) -
Improve performance of object notifiers with complex schemas and very simple changes to process by as much as 20% ([Core 14.2.0).
-
Improve performance with very large number of notifiers as much as 75% (Core 14.2.0).
-
Add support to synchronize collections embedded in Mixed properties and other collections (except sets) (Core v14.2.0-12-g95c6efce8).
-
Improve performance of change notifications on nested collections somewhat (Core v14.2.0-12-g95c6efce8).
-
Improve performance of aggregate operations on Dictionaries of objects, particularly when the dictionaries are empty (Core v14.2.0-12-g95c6efce8)
Fixed
- If you have more than 8388606 links pointing to one specific object, the program will crash. (Core 14.0.0)
- A Realm generated on a non-apple ARM 64 device and copied to another platform (and vice-versa) were non-portable due to a sorting order difference. This impacts strings or binaries that have their first difference at a non-ascii character. These items may not be found in a set, or in an indexed column if the strings had a long common prefix (> 200 characters). (Core 14.0.0)
- Ctor arguments appear in random order on generated classes, if the realm model contains many properties. (PR #1531)
- Fixed an issue where removing realm objects from a List with more than 1000 items could crash. (Core 14.2.0)
- Fix a spurious crash related to opening a Realm on background thread while the process was in the middle of exiting (Core v14.2.0-12-g95c6efce8)
Compatibility
- Realm Studio: 14.0.0 or later.
- Fileformat: Generates files with format v24. Reads and automatically upgrade from fileformat v10. If you want to upgrade from an earlier file format version you will have to use RealmCore v13.x.y or earlier.
Internal
- Using Core v14.2.0-12-g95c6ef...
2.0.0
2.0.0 (2024-03-20)
Breaking Changes
-
RealmValue.type
is now an enum of typeRealmValueType
rather thanType
. If you need the runtime type of the value wrapped inRealmValue
, useRealmValue.value.runtimeType
. (Issue #1505) -
Renamed
RealmValue.uint8List
constructor toRealmValue.binary
. (PR #1469) -
Removed the following deprecated classes and members:
AppConfiguration.localAppName
- was unused and had no effectAppConfiguration.localAppVersion
- was unused and had no effectClientResetError.isFatal
- it was alwaystrue
ClientResetError.sessionErrorCode
SyncError.codeValue
- can be accessed throughSyncError.code.code
SyncError.category
- categories were deprecated in1.6.0
SyncError.detailedMessage
- was always emptySyncError
constructor andSyncError.create
factory - sync errors are created internally by the SDK and are not supposed to be constructed by usersSyncClientError
,SyncConnectionError
,SyncSessionError
,SyncResolveError
,SyncWebSocketError
,GeneralSyncError
- consolidated intoSyncError
as part of the error simplification in1.6.0
RealmProperty.indexed
- replaced byRealmProperty.indexType
SyncErrorCategory
,SyncClientErrorCode
,SyncConnectionErrorCode
,SyncSessionErrorCode
,SyncResolveErrorCode
,SyncWebsocketErrorCode
,GeneralSyncErrorCode
- consolidated intoSyncErrorCode
as part of the error simplification in1.6.0
User.provider
- the provider is associated with each identity, so the value was incorrect for users who had more than one identity
-
The generated parts are now named
.realm.dart
instead of.g.dart
. This is because the builder is now aPartBuilder
, instead of aSharedPartBuilder
. To migrate to this version you need to update all the part declarations to match, ie.part 'x.g.dart
becomespart x.realm.dart
and rerun the generator.This makes it easier to combine builders. Here is an example of combining with
dart_mappable
:import 'package:dart_mappable/dart_mappable.dart'; import 'package:realm_dart/realm.dart'; part 'part_builder.realm.dart'; part 'part_builder.mapper.dart'; @MappableClass() @RealmModel() class $Stuff with $StuffMappable { @MappableField() late int id; @override String toString() => 'Stuff{id: $id}'; } final realm = Realm(Configuration.local([Stuff.schema])); void main(List<String> arguments) { final s = realm.write(() => realm.add(Stuff(1), update: true)); print(s.toJson()); // <-- realm object as json Realm.shutdown(); }
-
Removed
SchemaObject.properties
- instead,SchemaObject
is now an iterable collection ofProperty
. (Issue #1449) -
SyncProgress.transferredBytes
andSyncProgress.transferableBytes
have been consolidated intoSyncProgress.progressEstimate
. The values reported previously were incorrect and did not accurately represent bytes either. The new field better conveys the uncertainty around the progress being reported. With this release, we're reporting accurate estimates for upload progress, but estimating downloads is still unreliable. A future server and SDK release will add better estimations for download progress. (Issue #1562) -
Realm.logger
is no longer settable, and no longer implementsLogger
from packagelogging
. In particular you can no longer callRealm.logger.level =
. Instead you should callRealm.logger.setLogLevel(RealmLogLevel level, {RealmLogCategory? category})
that takes an optional category. If no category is exlicitly given, thenRealmLogCategory.realm
is assumed.Also, note that setting a level is no longer local to the current isolate, but shared accross all isolates. At the core level there is just one process wide logger.
Categories form a hierarchy and setting the log level of a parent category will override the level of its children. The hierarchy is exposed in a type safe manner with:
sealed class RealmLogCategory { /// All possible log categories. static final values = [ realm, realm.app, realm.sdk, realm.storage, realm.storage.notification, realm.storage.object, realm.storage.query, realm.storage.transaction, realm.sync, realm.sync.client, realm.sync.client.changeset, realm.sync.client.network, realm.sync.client.reset, realm.sync.client.session, realm.sync.server, ...
The
onRecord
stream now pumpsRealmLogRecord
s that include the category the message was logged to.If you want to hook up realm logging with conventional dart logging you can do:
Realm.logger.onRecord.forEach((r) => Logger(r.category.toString()).log(r.level.level, r.message));
If no isolate subscribes to
Realm.logger.onRecord
then the logs will by default be sent to stdout. (Issue #1578)
Enhancements
- Realm objects can now be serialized as EJSON. (Issue #1254)
import 'package:ejson/ejson.dart'; // ... class _Event { late DateTime timestamp; late String message; } // ... final ejson = toEJson(aRealmObject); final anUnmanagedRealmObject = fromEJson<Event>(ejson);
- Added
isCollectionDeleted
toRealmListChanges
,RealmSetChanges
, andRealmMapChanges
which will betrue
if the parent object, containing the collection has been deleted. (Core 14.0.0) - Added
isCleared
toRealmMapChanges
which will betrue
if the map has been cleared. (Core 14.0.0) - Querying a specific entry in a collection (in particular 'first and 'last') is supported. (Core 14.0.0)
class _Owner { late List<_Dog> dogs; } realm.query<Owner>('dogs[1].age = 5'); // Query all owners whose second dog element is 5 years old realm.query<Owner>('dogs[FIRST].age = 5'); // Query all owners whose first dog is 5 years old realm.query<Owner>('dogs[LAST].age = 5'); // Query all owners whose last dog is 5 years old realm.query<Owner>('dogs[SIZE] = 10'); // Query all owners who have 10 dogs
- Added support for storing lists and maps inside a
RealmValue
property. (Issue #1504)class _Container { late RealmValue anything; } realm.write(() { realm.add(Container(anything: RealmValue.from([1, 'foo', 3.14]))); }); final container = realm.all<Container>().first; final list = container.anything.asList(); // will throw if cast is invalid for (final item in containerValue) { switch (item.type) { case RealmValueType.int: print('Integer: ${item.value as int}'); break; case RealmValueType.string: print('String: ${item.value as String}'); break; case RealmValueType.double: print('Double: ${item.value as double}'); break; } } final subscription = list.changes.listen((event) { // The list changed });
- Added
RealmValueType
enum that contains all the possible types that can be wrapped by aRealmValue
. (PR #1469) - Added support for accessing
Set
andMap
types using the dynamic object API -obj.dynamic.getSet/getMap
. (PR #1533) - Added
RealmObjectBase.objectSchema
that returns the schema for this object. In most cases, this would be the schema defined in the model, but in case the Realm is opened as dynamic (by providing an empty collection for schemaObjects in the config) or usingFlexibleSyncConfiguration
, it may change as the schema on disk changes. (Issue #1449) - Added
Realm.schemaChanges
that returns a stream of schema changes that can be listened to. Only dynamic and synchronized Realms will emit schema changes. (Issue #1449) - Improve performance of object notifiers with complex schemas and very simple changes to process by as much as 20% (Core 14.2.0).
- Improve performance with very large number of notifiers as much as 75% (Core 14.2.0).
Fixed
- If you have more than 8388606 links pointing to one specific object, the program will crash. (Core 14.0.0)
- A Realm generated on a non-apple ARM 64 device and copied to another platform (and vice-versa) were non-portable due to a sorting order difference. This impacts strings or binaries that have their first difference at a non-ascii character. These items may not be found in a set, or in an indexed column if the strings had a long common prefix (> 200 characters). (Core 14.0.0)
- Ctor arguments appear in random order on generated classes, if the realm model contains many properties. (PR #1531)
- Fixed an issue where removing realm objects from a List with more than 1000 items could crash. (Core 14.2.0)
- Fix a spurious crash related to opening a Realm on background thread while the process was in the middle of exiting. (Core v14.3.0)
- Fixed conflict resolution bug which may result in an crash when the AddInteger instruction on Mixed properties is merged against updates to a non-integer type. (Core v14.3.0)
Compatibility
- Realm Studio: 14.0.0 or later.
- Fileformat: Generates files with format v24. Reads and automatically upgrade from fileformat v10. If you want to upgrade from an earlier file format version you will have to use RealmCore v13.x.y or earlier.
Internal
- Using Core v14.3.0
2.0.0-beta.1
2.0.0-beta.1 (2024-03-18)
Breaking Changes
-
RealmValue.type
is now an enum of typeRealmValueType
rather thanType
. If you need the runtime type of the value wrapped inRealmValue
, useRealmValue.value.runtimeType
. (Issue #1505) -
Renamed
RealmValue.uint8List
constructor toRealmValue.binary
. (PR #1469) -
Removed the following deprecated classes and members:
AppConfiguration.localAppName
- was unused and had no effectAppConfiguration.localAppVersion
- was unused and had no effectClientResetError.isFatal
- it was alwaystrue
ClientResetError.sessionErrorCode
SyncError.codeValue
- can be accessed throughSyncError.code.code
SyncError.category
- categories were deprecated in1.6.0
SyncError.detailedMessage
- was always emptySyncError
constructor andSyncError.create
factory - sync errors are created internally by the SDK and are not supposed to be constructed by usersSyncClientError
,SyncConnectionError
,SyncSessionError
,SyncResolveError
,SyncWebSocketError
,GeneralSyncError
- consolidated intoSyncError
as part of the error simplification in1.6.0
RealmProperty.indexed
- replaced byRealmProperty.indexType
SyncErrorCategory
,SyncClientErrorCode
,SyncConnectionErrorCode
,SyncSessionErrorCode
,SyncResolveErrorCode
,SyncWebsocketErrorCode
,GeneralSyncErrorCode
- consolidated intoSyncErrorCode
as part of the error simplification in1.6.0
User.provider
- the provider is associated with each identity, so the value was incorrect for users who had more than one identity
-
The generated parts are now named
.realm.dart
instead of.g.dart
. This is because the builder is now aPartBuilder
, instead of aSharedPartBuilder
. To migrate to this version you need to update all the part declarations to match, ie.part 'x.g.dart
becomespart x.realm.dart
and rerun the generator.This makes it easier to combine builders. Here is an example of combining with
dart_mappable
:import 'package:dart_mappable/dart_mappable.dart'; import 'package:realm_dart/realm.dart'; part 'part_builder.realm.dart'; part 'part_builder.mapper.dart'; @MappableClass() @RealmModel() class $Stuff with $StuffMappable { @MappableField() late int id; @override String toString() => 'Stuff{id: $id}'; } final realm = Realm(Configuration.local([Stuff.schema])); void main(List<String> arguments) { final s = realm.write(() => realm.add(Stuff(1), update: true)); print(s.toJson()); // <-- realm object as json Realm.shutdown(); }
-
Removed
SchemaObject.properties
- instead,SchemaObject
is now an iterable collection ofProperty
. (Issue #1449) -
SyncProgress.transferredBytes
andSyncProgress.transferableBytes
have been consolidated intoSyncProgress.progressEstimate
. The values reported previously were incorrect and did not accurately represent bytes either. The new field better conveys the uncertainty around the progress being reported. With this release, we're reporting accurate estimates for upload progress, but estimating downloads is still unreliable. A future server and SDK release will add better estimations for download progress. (Issue #1562)
Enhancements
-
Realm objects can now be serialized as EJSON
import 'package:ejson/ejson.dart'; // ... class _Event { late DateTime timestamp; late String message; } // ... final ejson = toEJson(aRealmObject); final anUnmanagedRealmObject = fromEJson<Event>(ejson);
-
Added
isCollectionDeleted
toRealmListChanges
,RealmSetChanges
, andRealmMapChanges
which will betrue
if the parent object, containing the collection has been deleted. (Core 14.0.0) -
Added
isCleared
toRealmMapChanges
which will betrue
if the map has been cleared. (Core 14.0.0) -
Querying a specific entry in a collection (in particular 'first and 'last') is supported. (Core 14.0.0)
class _Owner { late List<_Dog> dogs; } realm.query<Owner>('dogs[1].age = 5'); // Query all owners whose second dog element is 5 years old realm.query<Owner>('dogs[FIRST].age = 5'); // Query all owners whose first dog is 5 years old realm.query<Owner>('dogs[LAST].age = 5'); // Query all owners whose last dog is 5 years old realm.query<Owner>('dogs[SIZE] = 10'); // Query all owners who have 10 dogs
-
Added support for storing lists and maps inside a
RealmValue
property. (Issue #1504)class _Container { late RealmValue anything; } realm.write(() { realm.add(Container(anything: RealmValue.from([1, 'foo', 3.14]))); }); final container = realm.all<Container>().first; final list = container.anything.asList(); // will throw if cast is invalid for (final item in containerValue) { switch (item.type) { case RealmValueType.int: print('Integer: ${item.value as int}'); break; case RealmValueType.string: print('String: ${item.value as String}'); break; case RealmValueType.double: print('Double: ${item.value as double}'); break; } } final subscription = list.changes.listen((event) { // The list changed });
-
Added
RealmValueType
enum that contains all the possible types that can be wrapped by aRealmValue
. (PR #1469) -
Added support for accessing
Set
andMap
types using the dynamic object API -obj.dynamic.getSet/getMap
. (PR #1533) -
Added
RealmObjectBase.objectSchema
that returns the schema for this object. In most cases, this would be the schema defined in the model, but in case the Realm is opened as dynamic (by providing an empty collection for schemaObjects in the config) or usingFlexibleSyncConfiguration
, it may change as the schema on disk changes. (Issue #1449) -
Added
Realm.schemaChanges
that returns a stream of schema changes that can be listened to. Only dynamic and synchronized Realms will emit schema changes. (Issue #1449) -
Improve performance of object notifiers with complex schemas and very simple changes to process by as much as 20% ([Core 14.2.0).
-
Improve performance with very large number of notifiers as much as 75% (Core 14.2.0).
-
Add support to synchronize collections embedded in Mixed properties and other collections (except sets) (Core v14.2.0-12-g95c6efce8).
-
Improve performance of change notifications on nested collections somewhat (Core v14.2.0-12-g95c6efce8).
-
Improve performance of aggregate operations on Dictionaries of objects, particularly when the dictionaries are empty (Core v14.2.0-12-g95c6efce8)
Fixed
- If you have more than 8388606 links pointing to one specific object, the program will crash. (Core 14.0.0)
- A Realm generated on a non-apple ARM 64 device and copied to another platform (and vice-versa) were non-portable due to a sorting order difference. This impacts strings or binaries that have their first difference at a non-ascii character. These items may not be found in a set, or in an indexed column if the strings had a long common prefix (> 200 characters). (Core 14.0.0)
- Ctor arguments appear in random order on generated classes, if the realm model contains many properties. (PR #1531)
- Fixed an issue where removing realm objects from a List with more than 1000 items could crash. (Core 14.2.0)
- Fix a spurious crash related to opening a Realm on background thread while the process was in the middle of exiting (Core v14.2.0-12-g95c6efce8)
Compatibility
- Realm Studio: 14.0.0 or later.
- Fileformat: Generates files with format v24. Reads and automatically upgrade from fileformat v10. If you want to upgrade from an earlier file format version you will have to use RealmCore v13.x.y or earlier.
Internal
- Using Core v14.2.0-12-g95c6efce8
2.0.0-alpha.5
2.0.0-alpha.5 (2024-03-15)
Breaking Changes
-
RealmValue.type
is now an enum of typeRealmValueType
rather thanType
. If you need the runtime type of the value wrapped inRealmValue
, useRealmValue.value.runtimeType
. (Issue #1505) -
Renamed
RealmValue.uint8List
constructor toRealmValue.binary
. (PR #1469) -
Removed the following deprecated classes and members:
AppConfiguration.localAppName
- was unused and had no effectAppConfiguration.localAppVersion
- was unused and had no effectClientResetError.isFatal
- it was alwaystrue
ClientResetError.sessionErrorCode
SyncError.codeValue
- can be accessed throughSyncError.code.code
SyncError.category
- categories were deprecated in1.6.0
SyncError.detailedMessage
- was always emptySyncError
constructor andSyncError.create
factory - sync errors are created internally by the SDK and are not supposed to be constructed by usersSyncClientError
,SyncConnectionError
,SyncSessionError
,SyncResolveError
,SyncWebSocketError
,GeneralSyncError
- consolidated intoSyncError
as part of the error simplification in1.6.0
RealmProperty.indexed
- replaced byRealmProperty.indexType
SyncErrorCategory
,SyncClientErrorCode
,SyncConnectionErrorCode
,SyncSessionErrorCode
,SyncResolveErrorCode
,SyncWebsocketErrorCode
,GeneralSyncErrorCode
- consolidated intoSyncErrorCode
as part of the error simplification in1.6.0
User.provider
- the provider is associated with each identity, so the value was incorrect for users who had more than one identity
-
The generated parts are now named
.realm.dart
instead of.g.dart
. This is because the builder is now aPartBuilder
, instead of aSharedPartBuilder
. To migrate to this version you need to update all the part declarations to match, ie.part 'x.g.dart
becomespart x.realm.dart
and rerun the generator.This makes it easier to combine builders. Here is an example of combining with
dart_mappable
:import 'package:dart_mappable/dart_mappable.dart'; import 'package:realm_dart/realm.dart'; part 'part_builder.realm.dart'; part 'part_builder.mapper.dart'; @MappableClass() @RealmModel() class $Stuff with $StuffMappable { @MappableField() late int id; @override String toString() => 'Stuff{id: $id}'; } final realm = Realm(Configuration.local([Stuff.schema])); void main(List<String> arguments) { final s = realm.write(() => realm.add(Stuff(1), update: true)); print(s.toJson()); // <-- realm object as json Realm.shutdown(); }
-
Removed
SchemaObject.properties
- instead,SchemaObject
is now an iterable collection ofProperty
. (Issue #1449) -
SyncProgress.transferredBytes
andSyncProgress.transferableBytes
have been consolidated intoSyncProgress.progressEstimate
. The values reported previously were incorrect and did not accurately represent bytes either. The new field better conveys the uncertainty around the progress being reported. With this release, we're reporting accurate estimates for upload progress, but estimating downloads is still unreliable. A future server and SDK release will add better estimations for download progress. (Issue #1562)
Enhancements
-
Realm objects can now be serialized as EJSON
import 'package:ejson/ejson.dart'; // ... class _Event { late DateTime timestamp; late String message; } // ... final ejson = toEJson(aRealmObject); final anUnmanagedRealmObject = fromEJson<Event>(ejson);
-
Added
isCollectionDeleted
toRealmListChanges
,RealmSetChanges
, andRealmMapChanges
which will betrue
if the parent object, containing the collection has been deleted. (Core 14.0.0) -
Added
isCleared
toRealmMapChanges
which will betrue
if the map has been cleared. (Core 14.0.0) -
Querying a specific entry in a collection (in particular 'first and 'last') is supported. (Core 14.0.0)
class _Owner { late List<_Dog> dogs; } realm.query<Owner>('dogs[1].age = 5'); // Query all owners whose second dog element is 5 years old realm.query<Owner>('dogs[FIRST].age = 5'); // Query all owners whose first dog is 5 years old realm.query<Owner>('dogs[LAST].age = 5'); // Query all owners whose last dog is 5 years old realm.query<Owner>('dogs[SIZE] = 10'); // Query all owners who have 10 dogs
-
Added support for storing lists and maps inside a
RealmValue
property. (Issue #1504)class _Container { late RealmValue anything; } realm.write(() { realm.add(Container(anything: RealmValue.from([1, 'foo', 3.14]))); }); final container = realm.all<Container>().first; final list = container.anything.asList(); // will throw if cast is invalid for (final item in containerValue) { switch (item.type) { case RealmValueType.int: print('Integer: ${item.value as int}'); break; case RealmValueType.string: print('String: ${item.value as String}'); break; case RealmValueType.double: print('Double: ${item.value as double}'); break; } } final subscription = list.changes.listen((event) { // The list changed });
-
Added
RealmValueType
enum that contains all the possible types that can be wrapped by aRealmValue
. (PR #1469) -
Added support for accessing
Set
andMap
types using the dynamic object API -obj.dynamic.getSet/getMap
. (PR #1533) -
Added
RealmObjectBase.objectSchema
that returns the schema for this object. In most cases, this would be the schema defined in the model, but in case the Realm is opened as dynamic (by providing an empty collection for schemaObjects in the config) or usingFlexibleSyncConfiguration
, it may change as the schema on disk changes. (Issue #1449) -
Added
Realm.schemaChanges
that returns a stream of schema changes that can be listened to. Only dynamic and synchronized Realms will emit schema changes. (Issue #1449) -
Improve performance of object notifiers with complex schemas and very simple changes to process by as much as 20% ([Core 14.2.0).
-
Improve performance with very large number of notifiers as much as 75% (Core 14.2.0).
-
Add support to synchronize collections embedded in Mixed properties and other collections (except sets) (Core v14.2.0-12-g95c6efce8).
-
Improve performance of change notifications on nested collections somewhat (Core v14.2.0-12-g95c6efce8).
-
Improve performance of aggregate operations on Dictionaries of objects, particularly when the dictionaries are empty (Core v14.2.0-12-g95c6efce8)
Fixed
- If you have more than 8388606 links pointing to one specific object, the program will crash. (Core 14.0.0)
- A Realm generated on a non-apple ARM 64 device and copied to another platform (and vice-versa) were non-portable due to a sorting order difference. This impacts strings or binaries that have their first difference at a non-ascii character. These items may not be found in a set, or in an indexed column if the strings had a long common prefix (> 200 characters). (Core 14.0.0)
- Ctor arguments appear in random order on generated classes, if the realm model contains many properties. (PR #1531)
- Fixed an issue where removing realm objects from a List with more than 1000 items could crash. (Core 14.2.0)
- Fix a spurious crash related to opening a Realm on background thread while the process was in the middle of exiting (Core v14.2.0-12-g95c6efce8)
Compatibility
- Realm Studio: 14.0.0 or later.
- Fileformat: Generates files with format v24. Reads and automatically upgrade from fileformat v10. If you want to upgrade from an earlier file format version you will have to use RealmCore v13.x.y or earlier.
Internal
- Using Core v14.2.0-12-g95c6efce8
1.9.0
1.9.0 (2024-02-02)
Enhancements
- Added
User.changes
stream that allows subscribers to receive notifications when the User changes - for example when the user's custom data changes or when their authentication state changes. (PR #1500) - Allow the query builder to construct >, >=, <, <= queries for string constants. This is a case sensitive lexicographical comparison. Improved performance of RQL queries on a non-linked string property using: >, >=, <, <=, operators and fixed behaviour that a null string should be evaulated as less than everything, previously nulls were not matched. (Core 13.26.0-13-gd12c3)
Fixed
- Creating an
AppConfiguration
with an empty appId will now throw an exception rather than crashing the app. (Issue #1487) - Uploading the changesets recovered during an automatic client reset recovery may lead to 'Bad server version' errors and a new client reset. (Core 13.26.0-13-gd12c3)
Compatibility
- Realm Studio: 13.0.0 or later.
Internal
- Using Core 13.26.0-13-gd12c3
1.8.0
1.8.0 (2024-01-29)
Enhancements
- Added
RealmObject.getBacklinks<SourceType>('sourceProperty')
which is a method allowing you to look up all objects of typeSourceType
which link to the current object via theirsourceProperty
property. (Issue #1480) - Added
App.updateBaseUrl
method for updating the App's base URL for switching between cloud and edge servers. The current Sync Session(s) must be paused before calling this method and the user must log in again afterwards before the Sync Session can be resumed. (PR #1454)
Fixed
- Fix a possible hang (or in rare cases crash) during notification handling. (Issue #1492)
- Fix Flutter app build on Linux. A contribution from thiagokisaki. (PR #1488)
- App was not using the current baseUrl value from AppConfiguration when it is created and always used the cached value stored upon the first contact with the server. (Core XX.XX.X)
Compatibility
- Realm Studio: 13.0.0 or later.
Internal
- Using Core 13.26.0
1.7.0
1.7.0 (2024-01-23)
Enhancements
-
Reworked how creating an
App
instance works across isolates:- The
App(AppConfiguration)
constructor should only be used on the main isolate. Ideally, it should be called once as soon as your app launches. If you attempt to use it on a background isolate (as indicated byIsolate.debugName
being different frommain
), a warning will be logged. - Added a new method -
App.getById
that allows you to obtain an already constructed app on a background isolate.
(Issue #1433)
- The
-
Added support for fields of type
Map<String, T>
whereT
is any supported Realm type. You can define a model with a map like:@RealmModel() class _LotsOfMaps { late Map<String, _Person?> persons; late Map<String, bool> bools; late Map<String, DateTime> dateTimes; late Map<String, Decimal128> decimals; late Map<String, double> doubles; late Map<String, int> ints; late Map<String, ObjectId> objectIds; late Map<String, RealmValue> realmValues; late Map<String, String> strings; late Map<String, Uint8List> datas; late Map<String, Uuid> uuids; }
The map keys may not contain
.
or start with$
. (Issue #685) -
Added a new exception -
MigrationRequiredException
that will be thrown when a local Realm is opened with a schema that differs from the schema on disk and no migration callback is supplied. Additionally, ahelpLink
property has been added toRealmException
and its subclasses to provide a link to the documentation for the error. (Issue #1448) -
Downgrade minimum dependencies to Dart 3.0.0 and Flutter 3.10.0. (PR #1457)
Fixed
- Fixed warnings being emitted by the realm generator requesting that
xyz.g.dart
be included withpart 'xyz.g.dart';
forxyz.dart
files that importrealm
but don't have realm models defined. Those should not need generated parts and including the part file would have resulted in an empty file with// ignore_for_file: type=lint
being generated. (PR #1443) - Updated the minimum required CMake version for Flutter on Linux to 3.19. (Issue #1381)
- Errors in user-provided client reset callbacks, such as
RecoverOrDiscardUnsyncedChangesHandler.onBeforeReset/onAfterDiscard
would not be correctly propagated and the client reset exception would contain a message likeA fatal error occurred during client reset: 'User-provided callback failed'
but no details about the actual error. NowSyncError
has aninnerError
field which contains the original error thrown in the callback. (PR #1447) - Fixed a bug where the generator would not emit errors for invalid default values for collection properties. Default values for collection properties are not supported unless the default value is an empty collection. (PR #1406)
- Bad performance of initial Sync download involving many backlinks (Issue #7217, Core 13.25.1)
- Exceptions thrown during bootstrap application will now be surfaced to the user via the sync error handler rather than terminating the program with an unhandled exception. (PR #7197, Core 13.25.0).
- Exceptions thrown during bootstrap application could crash the sync client with an
!m_sess
assertion if the bootstrap was being applied during sync::Session activation. (Issue #7196, Core 13.25.0). - If a SyncSession was explicitly resumed via
App.reconnect()
while it was waiting to auto-resume after a non-fatal error and then another non-fatal error was received, the sync client could crash with a!m_try_again_activation_timer
assertion. (Issue #6961, Core 13.25.0) - Fixed several causes of "decryption failed" exceptions that could happen when opening multiple encrypted Realm files in the same process while using Apple/linux and storing the Realms on an exFAT file system. (Issue #7156, Core 13.24.1)
- Fixed deadlock which occurred when accessing the current user from the
App
from within a callback from theUser
listener (Issue #7183, Core 13.24.1) - Having a class name of length 57 would make client reset crash as a limit of 56 was wrongly enforced (57 is the correct limit) (Issue #7176, Core 13.24.1)
- Automatic client reset recovery on flexible sync Realms would apply recovered changes in multiple write transactions, releasing the write lock in between. This had several observable negative effects:
- Other threads reading from the Realm while a client reset was in progress could observe invalid mid-reset state.
- Other threads could potentially write in the middle of a client reset, resulting in history diverging from the server.
- The change notifications produced by client resets were not minimal and would report that some things changed which actually didn't.
- All pending subscriptions were marked as Superseded and then recreating, resulting in anything waiting for subscriptions to complete firing early.
(PR #7161, Core 13.24.1).
- If the very first open of a flexible sync Realm triggered a client reset, the configuration had an initial subscriptions callback, both before and after reset callbacks, and the initial subscription callback began a read transaction without ending it (which is normally going to be the case), opening the frozen Realm for the after reset callback would trigger a BadVersion exception (PR #7161, Core 13.24.1).
- Changesets have wrong timestamps if the local clock lags behind 2015-01-01T00:00:00Z. The sync client now throws an exception if that happens. (PR #7180, Core 13.24.1)
- Handle
EOPNOTSUPP
when usingposix_fallocate()
and fallback to manually consume space. This should enable android users to open a Realm on restrictive filesystems. (PR #7251, Core v13.26.0) - Application may crash with
incoming_changesets.size() != 0
when a download message is mistaken for a bootstrap message. This can happen if the synchronization session is paused and resumed at a specific time. (PR #7238, Core v13.26.0, since v11.8.0)
Compatibility
- Realm Studio: 13.0.0 or later.
- Flutter: ^3.10.0
- Dart: ^3.0.0
Internal
- Using Core v13.26.0.
1.6.1
1.6.1 (2023-11-30)
Fixed
- Fixed an issue where connections to Atlas App Services would fail on Android with a certificate expiration error. (Issue #1430)
- Fixed an issue with the generator where having multiple generated classes in the same file would result in multiple
// ignore_for_file: type=lint
lines being added, which itself was generating a lint warning. (Issue #1412) - Errors encountered while reapplying local changes for client reset recovery on partition-based sync Realms would result in the client reset attempt not being recorded, possibly resulting in an endless loop of attempting and failing to automatically recover the client reset. Flexible sync and errors from the server after completing the local recovery were handled correctly. (Core 13.24.0)
- During a client reset with recovery when recovering a move or set operation on a
List
that operated on indices that were not also added in the recovery, links to an object which had been deleted by another client while offline would be recreated by the recovering client. But the objects of these links would only have the primary key populated and all other fields would be default values. Now, instead of creating these zombie objects, the lists being recovered skip such deleted links. (Core 13.24.0) - During a client reset recovery a Set of objects could be missing items, or an exception could be thrown that prevents recovery ex: "Requested index 1 calling get() on set 'source.collection' when max is 0". (Core 13.24.0)
- Automatic client reset recovery would duplicate insertions in a list when recovering a write which made an unrecoverable change to a list (i.e. modifying or deleting a pre-existing entry), followed by a subscription change, followed by a write which added an entry to the list. (Core 13.24.0)
Compatibility
- Realm Studio: 13.0.0 or later.
- Flutter: ^3.13.0
- Dart: ^3.1.0
Internal
- Using Core 13.24.0.
1.6.0
1.6.0 (2023-11-15)
NOTE: There's a known regression with certificate validation on Android devices with 1.6.0. See #1430 for more details and suggested workarounds.
Enhancements
- Support for performing geo spatial queries using the new classes:
GeoPoint
,GeoCircle
,GeoBox
andGeoPolygon
. SeeGeoPoint
documentation on how to persist locations (#1389) - Suppressing rules for a *.g.dart files (#1413)
- Full text search supports searching for prefix only. Eg. "description TEXT 'alex*'" (Core upgrade)
- Unknown protocol errors received from the baas server will no longer cause the application to crash if a valid error action is also received. (Core upgrade)
- Added support for server log messages that are enabled by sync protocol version 10. AppServices request id will be provided in a server log message in a future server release. (Core upgrade)
- Simplified sync errors. The following sync errors and error codes are deprecated (#1387):
SyncClientError
,SyncConnectionError
,SyncSessionError
,SyncWebSocketError
,GeneralSyncError
- replaced bySyncError
.SyncClientErrorCode
,SyncConnectionErrorCode
,SyncSessionErrorCode
,SyncWebSocketErrorCode
,GeneralSyncErrorCode, SyncErrorCategory
- replaced bySyncErrorCode
.
- Throw an exception if
File::unlock
has failed, in order to inform the SDK that we are likely hitting some limitation on the OS filesystem, instead of crashing the application and use the same file locking logic for all the platforms. (Core upgrade) - Lift a restriction that prevents asymmetric objects from linking to non-embedded objects. (#1403)
- Add ISRG X1 Root certificate (used by lets-encrypt and hence MongoDB) to
SecurityContext
of the defaultHttpClient
. This ensure we work out-of-the-box on older devices (in particular Android 7 and earlier), as well as some Windows machines. (#1187, #1370) - Added new flexible sync API
RealmResults.subscribe()
andRealmResults.unsubscribe()
as an easy way to create subscriptions and download data in background. Added named parameter toMutableSubscriptionSet.clear({bool unnamedOnly = false})
for removing all the unnamed subscriptions. (#1354) - Added
cancellationToken
parameter toSession.waitForDownload()
,Session.waitForUpload()
andSubscriptionSet.waitForSynchronization()
. (#1354)
Fixed
- Fixed iteration after
skip
bug (#1409) - Crash when querying the size of a Object property through a link chain (Core upgrade, since v13.17.2)
- Deprecated
App.localAppName
andApp.localAppVersion
. They were not used by the server and were not needed to set them. (#1387) - Fixed crash in slab allocator (
Assertion failed: ref + size <= next->first
). (Core upgrade, since 13.0.0) - Sending empty UPLOAD messages may lead to 'Bad server version' errors and client reset. (Core upgrade, since v11.8.0)
- If a user was logged out while an access token refresh was in progress, the refresh completing would mark the user as logged in again and the user would be in an inconsistent state. (Core 13.21.0)
- Receiving a
write_not_allowed
error from the server would have led to a crash. (Core 13.22.0) - Fix interprocess locking for concurrent realm file access resulting in a interprocess deadlock on FAT32/exFAT filesystems. (Core 13.23.0)
- Fixed RealmObject not overriding
hashCode
, which would lead to sets of RealmObjects potentially containing duplicates. (#1418) realm.subscriptions.waitForSynchronization
will now correctly receive an error if a fatal session error occurs that would prevent it from ever completing. Previously the future would never resolve. (Core 13.23.3)- Fixed FLX subscriptions not being sent to the server if the session was interrupted during bootstrapping. (Core 13.23.3)
- Fixed application crash with 'KeyNotFound' exception when subscriptions are marked complete after a client reset. (Core 13.23.3)
- A crash at a very specific time during a DiscardLocal client reset on a FLX Realm could leave subscriptions in an invalid state. (Core 13.23.4)
Compatibility
- Realm Studio: 13.0.0 or later.
Internal
-
Made binding a
sync::Session
exception safe so if aMultipleSyncAgents
exception is thrown, the sync client can be torn down safely. (Core upgrade, since 13.4.1) -
Add information about the reason a synchronization session is used for to flexible sync client BIND message. (Core upgrade)
-
Sync protocol version bumped to 10. (Core upgrade)
-
Handle
badChangeset
error when printing changeset contents in debug. (Core upgrade) -
Using Core 13.23.2.