【基础】本地数据库！Isar 数据库

在应用程序设计中，有时需要永久保存特定数据。
这时，我们会使用存储在用户智能手机内的本地数据库。

虽然存在许多不同的本地数据库包，但本文将介绍一个广泛使用的包——Isar Database。

Isar Database是什么？
1. 何时需要使用？
2. 如何使用 Isar Database
官方网站介绍

Isar Database是什么？

是一个适用于 Flutter 的高速跨平台数据库，用于永久保存应用数据。

虽然还有其他本地数据库可用，但Isar数据库因以下原因而受欢迎：

高速性和效率
对初学者友好
作为 NoSQL 数据库，具有高扩展性（可以随着应用的成长进行扩展）

何时需要使用？

通常，应用程序使用的变量和状态（State）会在应用程序关闭时消失。

但在设计应用程序时，我们希望能够在下次启动时继承由用户操作产生的状态和变量，并进行处理。
通过将数据存储到 Isar 数据库，可以管理永久保存的数据。

如何使用 Isar Database

Isar 数据库是一种文档型的 NoSQL。
在关系型数据库（RDB）中，我们将保存的数据称为“记录”，而在文档型的 NoSQL 中，
我们将其称为“Collection”。

使用方法如下：

环境准备

在 “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: Isar 数据库的核心库
isar_flutter_libs: 用于在 Flutter 中使用 Isar 的附加库
build_runner: 用于 Dart 代码生成的工具
isar_generator: Isar 的代码自动生成工具，从模型自动生成所需的代码

定义Collection

定义要管理的数据类型。
例如，我们在 “user.dart” 中定义用于登录等的用户信息。

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

@collection
class User {
  // 使用 Isar 的功能自动增加 ID
  Id? id = Isar.autoIncrement;
  String? userName;
  String? eMail;
}

规则１：@collection
在定义的开头加上 “@collection”。
这是一个注解，用于让 Isar 将其识别为数据库表的一部分。
它是一个标志，表示“这里定义了一个集合”。

规则 2：唯一的 ID
定义集合时，必须设置一个可以唯一识别的 ID。在这里，我们使用了 “Isar.autoIncrement”。
使用 Isar.autoIncrement 时，Isar 会自动分配唯一的 ID。

此时，”user.g.dart” 尚未存在。执行以下命令生成 “user.g.dart”：

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

注册Collection

创建要插入的数据对象，并通过 put 方法插入Collection。

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

await isar.users.put(user);

关于 users

“isar.users.put” 中的 “users” 是什么意思？

由自动生成的 “user.g.dart” 定义了一个为 user 集合服务的 users 方法。
当我们需要对 user 集合执行某些操作时，会使用这个方法。

如果定义的集合是 Item，则对应的是 Items。
如果不确定方法名称，可以参考 “xxx.g.dart”。

更新Collection

使用相同的 put 方法更新集合。
创建一个带有 ID 的对象，并通过 put 进行更新。
如果该 ID 已经存在，则更新集合；如果不存在，则插入。

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

await isar.users.put(user);

删除Collection

通过指定 ID 并执行 delete 来删除Collection。

await isar.users.delete(123);

事务处理

通常，Collection注册、更新和删除是在事务处理中执行的。

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

// 如果所有操作都提交，则更新数据库
await isar.writeTxn(() async {
  await isar.users.put(user);
  await isar.users.delete(123);
});

获取Collection

有多种方法可以获取集合。

// 获取所有 User 集合
final user = await isar.users;

// 获取 ID 为 "123" 的 User 集合
final user = await isar.users.get(123);

使用 Filter 语句

Filter 语句允许您对集合元素指定条件进行搜索。

// 获取 eMail 中包含 "@example.com" 的记录
final users = await isar.users
　.filter()
　.emailcontains('@example.com')
　.findAll();
  //※"findAll()" 会获取所有匹配的集合

使用 Where 语句

Where 语句仅适用于设置了索引的元素。
与 Filter 语句相比，Where 语句更快，但 Filter 语句可以用于任何元素。

例如，如果 user.dart 定义了以下集合：

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

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

  // 为年龄设置索引
  @Index()
  String? age;

  String? eMail;
}

可以使用以下 Where 语句：

// 获取年龄为 30 岁的集合
final user = await isar.users
  .where()
  .ageEqualTo(30)
  .findAll();

// 获取年龄超过 30 岁的集合
final user = await isar.users
  .where()
  .ageGreaterThan(30)
  .findAll();

“ageEqualTo” 和 “ageGreaterThan” 的参数定义在自动生成的 ‘user.g.dart’ 中。

官方网站介绍

除了本文介绍的内容，Isar 数据库还有许多其他用法。
如果感兴趣，请参考官方网站。

官方网站：https://isar.dev/zh/schema.html