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
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 会手动解析根目录 .env（monorepo 下 drizzle-kit 不自动加载）。改 env 路径时两处保持一致。

修改指南

• 需要新表时：改 @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:studio