Flutter 集成

Prisma ORM for Dart 允许您将其集成到 Flutter 项目中。

平台支持

平台	支持	备注
iOS	✅
Android	✅
macOS	❌	Prisma C-ABI 不支持
Linux	❌	Prisma C-ABI 不支持
Windows	❌	Prisma C-ABI 不支持
Web	❌	目前暂无计划

数据库支持

数据库	支持	备注
Sqlite	✅
MySQL/MariaDB	❌	Prisma C-ABI 不支持
PostgreSQL	❌	Prisma C-ABI 不支持
MongoDB	❌	Prisma C-ABI 不支持
Microsoft SQL Server	❌	Prisma C-ABI 不支持
CockroachDB	❌	Prisma C-ABI 不支持

安装

您应该首先阅读 安装文档，以及 orm 包的 设置 Prisma ORM。

现在，让我们安装 orm_flutter 包，您可以使用命令行

flutter pub add orm_flutter

或者编辑您的 Flutter 项目的 pubspce.yaml 文件

dependencies:
  orm_flutter: latest

集成

在您的 Prisma 模式 (schema.prisma) 中将您的生成器引擎类型设置为 flutter

generator client {
  provider   = "dart run orm"
  output     = "../lib/_generated_prisma_client"
  engineType = "flutter"
}

迁移

与服务器端不同，Flutter 中的数据库通常不会在构建之前由您在 Prisma CLI 中处理。

创建迁移文件

Bun.js

bun prisma migrate dev

NPM

npx prisma migrate dev

pnpm

pnpx prisma migrate dev

备注：默认情况下，它创建在 prisma/migrations/ 文件夹中。

将迁移文件设置为 Flutter 资源

现在，让我们编辑您的 pubspec.yaml

flutter:
  assets:
    - prisma/migrations/ # Migrations root dir
    - prisma/migrations/<dir>/ # Set first migration files dir
    # ... More assets

备注：使用 prisma migrate dev 命令生成的每个迁移文件夹都需要添加。

运行迁移

final engine = prisma.$engine as LibraryEngine;

await engine.applyMigrations(
     path: 'prisma/migrations/', // You define in `flutter.assets` migrations root dir
);

备注

除了使用 flutter.assets 之外，您还可以自定义 AssetBundle 来实现

await engine.applyMigrations(
  path: '<Your migration dir prefix>',
  bundle: <You custon bundle>,
);

此外，engine.applyMigrations 可能会抛出异常。这通常是由您对迁移文件进行的破坏性更改引起的，您应该自己处理此问题。最常见的方法是在抛出异常后删除数据库文件，然后重新运行迁移。

如果您正在添加新的迁移，几乎不会出现问题。

完整的集成示例

在此示例中，我们将安装以下包

• path
• path_provider

我们将在 <Application Support Directory>/database.sqlite 位置安装数据库，然后使用 flutter.assets 运行迁移

lib/prisma.dart

import 'package:flutter/widgets.dart';
import 'package:orm_flutter/orm_flutter.dart';
import 'package:path/path.dart';
import 'package:path_provider/path_provider.dart';

import '_generated_prisma_client/client.dart';

late final PrismaClient prisma;

Future<void> initPrismaClient() async {
  WidgetsFlutterBinding.ensureInitialized();

  final supportDir = await getApplicationSupportDirectory();
  final database = join(supportDir.path, 'database.sqlite.db');

  prisma = PrismaClient(datasourceUrl: 'file:$database');
  final engine = switch (prisma.$engine) {
    LibraryEngine engine => engine,
    _ => null,
  };

  await prisma.$connect();
  await engine?.applyMigrations(path: 'prisma/migrations');
}

lib/main.dart

import 'prisma.dart';

Future<void> main() async {
     await initPrismaClient();

     // ...
}

示例应用

我们为您提供了一个在 Flutter 中集成 Prisma ORM 的演示应用 👉 Flutter with ORM

常见问题解答

错误 (Xcode)：未定义符号：prisma_*

这是由于库编译失败导致的，即使您下载了新的修复版本，此问题也会持续存在。

解决方法：运行以下命令

flutter clean

找不到 */query_engine/*/libquery_engine.a 文件

这是因为 Prisma 静态查询引擎库的自动下载失败。

要修复它，请运行以下命令

dart run orm_flutter:dl_engine

其他未知错误解决方案：

大多数问题都可以通过使用以下命令组合来解决

flutter clean # Clean flutter cache files
flutter pub get # Reinstall deps
dart run orm_flutter:dl_engine # Download prisma engine static library
<bun/npx/pnpx/yarn> prisma generate # Regenerate prisma client

每次更新 orm_flutter 版本时

由于 Prisma C-ABI 引擎在 CDN 上可用，因此 Flutter 插件不支持在 build 之前运行脚本。此外，pub.dev 有一个包大小限制。

因此，在您安装新的 orm_flutter 包后，它不包含 Prisma 引擎，您需要运行以下命令来下载它

dart run orm_flutter:dl_engine

最好运行 flutter clean 以在重新下载引擎后重置原生构建。请注意，清理仅适用于 iOS。

如果您已安装 orm 和 orm_flutter 依赖项并为 Flutter 生成了 Prisma 客户端，则您只需要运行 prisma generate，它将自动查找并下载引擎。这极大地简化了初始化工作。