app-template/packages/db/AGENTS.md

AGENTS.md — @app/db

职责

创建并导出 Drizzle + libSQL 客户端单例，以及 drizzle-kit 配置与种子脚本。查询在 @app/dao，业务在 @app/trpc service。

结构

src/
  client.ts   # export const db = drizzle(client, { schema })
  index.ts    # 对外 re-export
scripts/
  seed.ts     # 幂等初始化默认管理员（yarn db:seed）
drizzle.config.ts    # dialect: turso；schema 指向 ../models/dist/index.js

行为要点

• 读环境变量：TURSO_DATABASE_URL（必填，缺失则启动抛错）、TURSO_AUTH_TOKEN（可选）。
• 本地开发常用 TURSO_DATABASE_URL=file:local.db。
• schema 来自 @app/models——模型定义请去 models 改，本包只聚合导入。
• 不写业务查询；SQL/Drizzle query 在 @app/dao。
• drizzle.config.ts 与 scripts/seed.ts 都会手动解析根目录 .env（monorepo 下 drizzle-kit / tsx 不自动加载）。改 env 路径时保持一致。

seed 脚本

• yarn db:seed：创建默认管理员（用户名 + 密码），已存在同名用户则跳过（幂等）。
• 密码哈希格式与 @app/trpc 的 password.ts 一致（scrypt salt:hash hex）——改哈希算法时两处同步。
• 脚本可直接依赖 @app/models 与 @libsql/client，但不要在 src/ 里塞业务逻辑。

修改指南

• 需要新表时：改 @app/models → yarn db:generate / db:push，不要在本包手写 SQL 迁移（除非 drizzle-kit 生成物不够用）。
• 不要在模块顶层执行查询以外的副作用；保持「import 即得 client」。
• 多环境：本地 file:，线上 libsql://... + token；不要写死 URL。

命令

yarn workspace @app/db typecheck
yarn workspace @app/db build
yarn db:generate
yarn db:push
yarn db:seed
yarn db:studio