example/README.md

ObjectBox Examples #

In the following file, e.g. models.dart, we import objectbox.dart to get definitions for @Entity, @Id and other annotations and define a single entity that should be persisted by ObjectBox. You could have multiple entities in the same file or you can have them spread across multiple files in the lib directory tree.

import "package:objectbox/objectbox.dart";

@Entity()
class Note {
    @Id()       // required; stored as a 64-bit unsigned integer in ObjectBox
    int id;
    String text;
    
    @Transient() // field is ignored, entity will not have this property
    int notPersisted;
    
    Note({this.text}); // empty default constructor needed but it can have optional args
    toString() => "Note{id: $id, text: $text}";
}

ObjectBox generator will look for all @Entity annotations in your lib folder and create a single database definition lib/objectbox-model.json and supporting code in lib/objectbox.g.dart. You should commit objectbox-model.json into your source control (e.g. git) and add objectbox.g.dart to the ignore list (e.g. .gitignore), otherwise the build_runner will complain about it being changed each time you pull a change.

Note: the generator will process lib and test folders separately and create a separate database in each one, if it finds annotations there. This is useful if you need a separate test DB, but if you're just writing tests for your own code you won't have any annotations in the test folder so no DB will be created there.

To use ObjectBox and store the just defined entity, you should import objectbox.g.dart and create the Store. Finally, you will create a Box<Note> which gives you a typed interface for storing and retrieving Note objects.

import 'objectbox.g.dart'; // this file will be generated by ObjectBox after running `pub run build_runner build`

void main() {
  var store = Store(getObjectBoxModel()); // Note: getObjectBoxModel() is generated for you in objectbox.g.dart
  var box = Box<Note>(store);
  
  var note = Note(text: "Hello");
  note.id = box.put(note);
  print("new note got id ${note.id}");
  print("refetched note: ${box.get(note.id)}");
  
  store.close();
}

Flutter #

• See a Flutter example app - requires Flutter 1.12

As opposed to a plain Dart app which runs directly on your PC, there are more restrictions where your Flutter app can write data. Therefore, you should give ObjectBox a full path to a per-app documents directory, where to store the data even when a user closes your app.

If you didn't specify this path to ObjectBox, it would try to use a default "objectbox" directory where the app is currently running, but it doesn't have permissions to write there: failed to create store: 10199 Dir does not exist: objectbox (30).

To configure ObjectBox properly, you can use getApplicationDocumentsDirectory() from the path_provider package. See Flutter: read & write files for more info. Have a look how it's done in the Flutter example app:

import 'package:path_provider/path_provider.dart';

class _MyHomePageState extends State<MyHomePage> {
  Store _store;

  @override
  void initState() {
    super.initState();
    
    getApplicationDocumentsDirectory().then((dir) {
      _store = Store(getObjectBoxModel(), directory: dir.path + "/objectbox");
    });
  }
}