[Basics] Local DB! Introducing Isar Database

2024.02.14

In the design of applications, there may come a time when you need to permanently store specific data. In such cases, a local database (local DB), designed within the user’s smartphone, is utilized.

There are various packages available for local DBs, but this time, I will introduce a commonly used package called “Isar Database“.

What is Isar Database?

Isar Database is a fast, cross-platform database designed for Flutter.
It is used to persistently store app data locally.

While there are other local DB options, Isar Database is popular for several reasons:

  • Speed and efficiency
  • User-friendly, even for beginners
  • Being a NoSQL database, it offers high scalability
    (can grow with your app’s future development)

When is it necessary?

Variables and states used in regular apps disappear when the app is closed.

However, when designing an app, there may be scenarios where you want to carry over states or variables generated by user actions to the next startup and process them.

By offloading data to Isar Database, you can manage data that is permanently stored.

How to use Isar Database

Isar Database is a document-type NoSQL.

In relational databases (RDB), the data you save is called a record,
but in document-type NoSQL, it is referred to as a “collection.”

Setting up the environment

Add the necessary packages to your “pubspec.yaml”:

dependencies:

  flutter:
    sdk: flutter
  flutter_localizations: 
    sdk: flutter
  isar: ^3.1.0
  isar_flutter_libs: ^3.1.0

dev_dependencies:
  build_runner: ^2.3.3
  dart_code_metrics: ^5.4.0

  flutter_lints: ^2.0.0
  flutter_test:
    sdk: flutter
  isar_generator: ^3.1.0
  • isar: Core library for Isar Database
  • isar_flutter_libs: Additional libraries for using Isar with Flutter
  • build_runner: A tool for generating Dart code
  • isar_generator: Isar code generation tool, auto-generates necessary code from models

Defining a collection

Define what data you will manage.
For example, define user information used for login in “user.dart”:

import 'package:isar/isar.dart';
import 'user.g.dart';

@collection
class User {
  // Automatically increment ID using Isar's feature
  Id? id = Isar.autoIncrement;
  String? userName;
  String? eMail;
}

@collection:
Place this annotation at the beginning of the definition so Isar recognizes it as a database table.

Unique ID:
Each collection definition must have a unique ID.
Here, Isar.autoIncrement is used, which automatically assigns a unique ID by Isar.

The “user.g.dart” being imported does not exist at this point.
Execute the following command in the terminal to generate “user.g.dart”:

flutter pub run build_runner build --delete-conflicting-outputs


Inserting a collection

Create an object for the data you want to insert and use put to insert the collection:

final user = User()
  ..userName = 'John Doe'
  ..eMail = 'john@example.com';

await isar.users.put(user);
What about users?

What does “users” in isar.users.put refer to?

The auto-generated “user.g.dart” defines a users method for the user collection.
This method is used when performing operations on the user collection.

Updating a collection

Updating a collection uses the same put as insertion.
Creating an object with an ID and using put updates the collection if the ID exists; if not, it inserts it.

final user = User()
  ..id = 123
  ..userName = 'John Doe'
  ..eMail = 'john@example.com';

await isar.users.put(user);


Deleting a collection

To delete a collection, specify the ID and execute delete:

await isar.users.delete(123);


Transaction processing

Registrations, updates, and deletions of collections are usually performed within transaction processing:

final user = User()
  ..id = 123
  ..userName = 'John Doe'
  ..eMail = 'john@example.com';

// The following process updates the DB when all committed
await isar.writeTxn(() async {
  await isar.users.put(user);
  await isar.users.delete(123);
});


Retrieving a collection

There are various ways to retrieve collections:

// Retrieve all User collections
final user = await isar.users;

// Retrieve the User collection with ID "123"
final user = await isar.users.get(123);


Using the Filter clause

The Filter clause allows you to specify conditions and search for elements in a collection:

// Retrieve items with "@example.com" in the eMail
final users = await isar.users
　.filter()
　.emailcontains('@example.com')
　.findAll();
  //※"findAll()" retrieves all matching collections

Using the Where clause

The Where clause can only be used on elements with an index set, providing faster processing than the Filter clause, which can be used on any element.

For example, if “user.dart” defines a collection as follows:

import 'package:isar/isar.dart';
import 'user.g.dart';

@collection
class User {
  Id? id = Isar.autoIncrement;
  String? userName;

  // Index set on the age element
  @Index()
  String? age;

  String? eMail;
}

You can set a Where clause like this:

// Retrieve collections where age is 30
final user = await isar.users
  .where()
  .ageEqualTo(30)
  .findAll();

// Retrieve collections where age is over 30
final user = await isar.users
  .where()
  .ageGreaterThan(30)
  .findAll();

Parameters like “ageEqualTo” and “ageGreaterThan” are defined
in the auto-generated ‘user.g.dart’.

Official Website

For more information beyond what is explained here, Isar Database offers various other features. For those interested, please refer to the official website.

Official Website：https://isar.dev/schema.html

Copied title and URL