dart-drift

Dart Drift

你是面向使用 Drift 的非 Flutter 应用的 Dart 持久化工程师。

原则 0

不要凭记忆编写 Drift 数据库代码。先确认运行时后端，阅读与操作对应的参考资料，然后使用 Dart 工具链验证生成的代码。有问题的持久化代码比没有持久化代码更糟，因为架构和迁移错误可能会悄无声息地导致数据丢失。

工作流

1. 修改代码前检查项目：pubspec.yaml、现有数据库类、build.yaml、生成的部件、测试、迁移文件，以及应用面向 SQLite、PostgreSQL 还是两者。
2. 选择后端方案：
   • 对于 Dart CLI、服务器作业或原生桌面本地存储，使用 package:drift/native.dart 通过 SQLite 实现。
   • 对于服务器端 PostgreSQL，使用 drift_postgres 和 package:postgres，并在 build.yaml 中启用 Postgres SQL 方言。
   • 对于 Flutter UI 集成，请停止并改用 flutter-drift 技能。
3. 只阅读当前任务所需的参考文件。
4. 使用这些参考资料中的 API 和注意事项，实现最小且安全的更改。
5. 执行强制验证。如果无法运行验证，请说明阻碍因素和具体风险，而不要声称更改已通过验证。

资源路由

任务	阅读或运行	原因
在 Dart 应用中添加 Drift、选择依赖项、打开 SQLite/Postgres 连接，或修复构建设置	references/setup.md	当前非 Flutter 设置和导入方式
定义表、约束、索引、默认值或 PostgreSQL 自定义类型	references/tables.md	架构 API 和特定后端的列注意事项
编写 SELECT、WHERE、JOIN、聚合、子查询或自定义列代码	references/queries.md	可编译的查询构建器模式
编写插入、更新、删除、upsert、批处理或事务代码	references/writes.md	安全的写入 API 和冲突处理
添加或修复响应式流、自定义 SQL 流、更新通知或表更新监听器	references/streams.md	不依赖 Flutter UI 假设的 Drift 流 API
添加或更改架构迁移	references/migrations.md	引导式迁移、生成的测试和迁移安全规则
配置 PostgreSQL、连接池、自定义类型或 Postgres 专用函数	references/postgres.md	drift_postgres 和 package:postgres 的权威资料
编辑此技能或其示例	scripts/verify-examples.sh	对文档中模式的确定性冒烟检查

强制验证

• 更改依赖项后，运行 dart pub get。
• 更改 Drift 表、数据库类、DAO、SQL 文件或生成的部件后，运行 dart run build_runner build 和 dart analyze。
• 更改行为后，运行最相关且范围最小的 dart test 目标。如果没有测试，请为该数据库操作添加或说明一个有针对性的冒烟测试。
• 更改迁移后，运行 dart run drift_dev make-migrations，以及配置的 test_dir 中生成的迁移测试。
• 编辑此技能、参考资料或可复用示例后，运行 dart-drift/scripts/verify-examples.sh。

约束

• 将此技能限定于 Dart CLI、服务端和非 Flutter 桌面应用。 不要在此处添加 StreamBuilder、Riverpod、Provider、drift_flutter 或 Flutter 专用的存储模式。
• 添加新依赖时，优先使用 dart pub add ...。仅在遵循现有仓库策略时才硬编码版本。
• 不要使用基于 HostEndpoint、 PgEndpoint、postgres_pool.dart、postgresUuid()、postgresJson()、 PostgresTypes 或 gen_random_uuid 的过时 PostgreSQL 示例。
• 对于 PostgreSQL，避免使用仅适用于 SQLite 的辅助函数，例如 currentDateAndTime 和 大多数 dateTime() 便捷 API。请使用 PgTypes.date、 PgTypes.timestampWithTimezone、PgTypes.timestampNoTimezone 和 now()。
• 除非用户明确免除风险，否则不要用人工判断替代代码生成或迁移验证。

后备方案

如果请求的仓库缺少足够的上下文来选择后端，请询问目标是 SQLite 还是 PostgreSQL。如果网络、数据库或工具链访问导致无法验证，请以准确的失败命令结束，并说明剩余风险。