Docs Menu
Docs Home
/
MongoDB Atlas
/
Atlas Device SDKs
/
Flutter SDK
/
Realm Database
/
CRUD

CRUD - Create - Flutter SDK

On this page

  • Write Transactions
  • Write Operations
  • Background Writes
  • Create Objects
  • Create One Object
  • Create Multiple Objects

Atlas Device SDK uses a highly efficient storage engine to persist objects. You can create objects, update objects in the database, and eventually delete objects from the database. Because these operations modify the state of the database, we call them writes.

Write Transactions

The SDK handles writes in terms of transactions. A transaction is a list of read and write operations that the SDK treats as a single indivisible operation. In other words, a transaction is all or nothing: either all of the operations in the transaction succeed or none of the operations in the transaction take effect.

All writes must happen in a transaction.

The database allows only one open transaction at a time. The SDK blocks other writes on other threads until the open transaction is complete. Consequently, there is no race condition when reading values from the database within a transaction.

When you are done with your transaction, the SDK either commits it or cancels it:

  • When the SDK commits a transaction, it writes all changes to disk. For synced databases, the SDK queues the change for synchronization with Atlas Device Sync.

  • When the SDK cancels a write transaction or an operation in the transaction causes an error, all changes are discarded (or "rolled back").

Write Operations

Once you've opened a database, you can create objects within it using a Realm.write() transaction block.

realm.write((){
  // ...write data to realm
});

You can also return values from the write transaction callback function.

final yoda = realm.write<Person>(() {
  return realm.add(Person(ObjectId(), 'Yoda'));
});

Warning

Write RealmObjects to One Realm File

You can only write RealmObjects to a single realm file. If you already wrote a RealmObject to one realm file, the SDK throws a RealmException if you try to write it to another database.

Background Writes

You can add, modify, or delete objects asynchronously using Realm.writeAsync().

When you use Realm.writeAsync() to perform write operations, waiting to obtain the write lock and committing a transaction occur in the background. Only the write itself occurs on the main process.

This can reduce time spent blocking the execution of the main process. This is particularly useful when using Device Sync, where you don't know when and for how long the Sync client will be writing.

// Add Leia to the realm using `writeAsync`
Person leia = Person(ObjectId(), "Leia");
realm.writeAsync(() {
  realm.add<Person>(leia);
});

Create Objects

The examples on this page use two object types, Person and Team.

@RealmModel()
class _Person {
  @PrimaryKey()
  late ObjectId id;
  late String name;
  late List<String> hobbies;
}
@RealmModel()
class _Team {
  @PrimaryKey()
  late ObjectId id;
  late String name;
  late List<_Person> crew;
  late RealmValue eventLog;
}

Create One Object

To add an object to the database, pass an instance of a Realm object class to the database in a write transaction block with Realm.add().

realm.write(() {
  realm.add(Person(ObjectId(), 'Lando'));
});

Create Multiple Objects

To add multiple objects to a database, pass a list of multiple objects to Realm.addAll() inside a write transaction block.

realm.write(() {
  realm.addAll([
    Person(ObjectId(), 'Figrin D\'an'),
    Person(ObjectId(), 'Greedo'),
    Person(ObjectId(), 'Toro')
  ]);
});
← CRUD
Read →

On this page