Isar Database

Quickstart • Documentation • Sample Apps • Support & Ideas • Pub.dev

Isar [ee-zahr]:

River in Bavaria, Germany.

Database that will make your life easier.

Features

💙 Made for Flutter. Easy to use, no config, no boilerplate
🚀 Highly scalable from hundreds to hundreds of thousands of records
🍭 Feature rich. Composite & multi indexes, query modifiers, JSON support and more
🔎 Full-text search. Make searching fast and fun
📱 Multiplatform. iOS, Android, Desktop and the web (soon™)
🧪 ACID semantics. Rely on consistency
⏱ Asynchronous. Parallel query operations & multi-isolate support
💃 Static typing. Compile-time checked and autocompleted queries

1. Add to pubspec.yaml

dependencies:
  isar: 1.0.0+1
  isar_flutter_libs: 1.0.0+1 # contains the binaries
  isar_connect: 1.0.0+1 # if you want to use the Isar Inspector

dev_dependencies:
  isar_generator: 1.0.0+1
  build_runner: any

2. Define a Collection

@Collection()
class Post {
  late int? id; // auto increment id

  late String title;

  @Index(type: IndexType.value) // Search index
  List<String> get titleWords => Isar.splitWords(title);
}

3. Open an instance

initializeIsarConnect(); // if you want to use the Isar Inspector

final isar = await Isar.open(
  schemas: [PostSchema],
  path: await getDocuments,
);

Isar Inspector

The Isar Inspector allows you to inspect the Isar instances & collections of your app in real time. You can execute queries, switch between instances and sort the data.

CRUD operations

All basic crud operations are available via the IsarCollection.

final newPost = Post()..title = 'Amazing new database';

await isar.writeTxn((isar) {
  newPost.id = await isar.posts.put(newPost); // insert
});

final existingPost = await isar.get(newPost.id!); // get

await isar.writeTxn((isar) {
  await isar.posts.delete(existingPost.id!); // delete
});

Queries

Isar has a powerful query language that allows you to make use of your indexes, filter distinct objects, use complex and() and or() groups and sort the results.

final isar = await Isar.open(
  schemas: [PostSchema],
  path: await getDocuments(),
);

final ftsPosts = isar.posts
  .where()
  .titleWordsAnyStartsWith('amaz') // use case insensitive search index
  .limit(10)
  .findAll()

final matchingPosts = isar.posts
  .where()
  .anyTitle() // use index to sort by title
  .filter()
  .titleMatches('*new*') // titles containing 'new'
  .findAll()

Links

You can easily define relationships between objects. In Isar they are called links and backlinks:

@Collection()
class Teacher {
    late int? id;

    late String subject;

    @Backlink(to: 'teacher')
    var students = IsarLinks<Student>();
}

@Collection()
class Student {
    int? id;

    String name;

    var teacher = IsarLink<Teacher>();
}

Watchers

With Isar, you can watch Collections, Objects, or Queries. A watcher is notified after a transaction commits successfully and the target actually changes. Watchers can be lazy and not reload the data or they can be non-lazy and fetch new results in the background.

Stream<void> collectionStream = isar.posts.watchLazy;

Stream<List<Post>> queryStream = databasePosts.watch();

queryStream.listen((newResult) {
  // do UI updates
})

License

Copyright 2022 Simon Leier

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

xtyxtyx / isar