Schema 定义

• 从 schema 文件中导出所有表——若某张表未被导出，相关查询将静默失败
• 使用 $inferSelect 定义查询返回类型，使用 $inferInsert 定义插入输入类型——二者语义不同（$inferSelect 包含已填充的默认值，$inferInsert 中可选字段保持可选）
• relations() 必须在独立调用中定义，不可内联于表定义中——Drizzle 明确分离 schema 与关系定义

查询语法陷阱

• 条件表达式需使用函数而非对象：where: eq(users.id, 5)，而非 where: { id: 5 }——Prisma 风格语法不适用
• 使用 and() / or() 组合多个条件：where: and(eq(users.active, true), gt(users.age, 18))
• 执行带关联查询（with:）时使用 db.query.users.findMany()；执行类 SQL 查询时使用 db.select().from(users)——混用二者将导致类型错误

迁移（Migrations）

• drizzle-kit push 仅限开发环境使用（具有破坏性）；生产环境应使用 drizzle-kit generate 生成迁移文件，再执行 drizzle-kit migrate
• Schema 变更后必须重新生成迁移文件——手动编辑生成的 SQL 将破坏迁移哈希值，导致迁移失败
• 在 drizzle.config.ts 中设置 strict: true，可在问题进入生产环境前捕获 schema 偏移（schema drift）

驱动特异性说明

• PostgreSQL：使用 pgTable，导入自 drizzle-orm/pg-core
• MySQL：使用 mysqlTable，导入自 drizzle-orm/mysql-core
• SQLite：使用 sqliteTable，导入自 drizzle-orm/sqlite-core
• 跨驱动混用导入（如在 PostgreSQL 项目中引入 mysql-core）虽可通过编译，但在运行时会触发难以排查的错误

性能优化

• 对多查询操作，务必包裹在 db.transaction(async (tx) => {}) 中——Drizzle 不会自动批处理查询
• 对高频重复执行的查询，使用 .prepare() 方法——可跳过每次查询构建的开销
• 为每个 findMany() 和 select() 显式添加 .limit()——无默认限制将导致全表扫描

常见错误

• 查询未加 await 将返回 Promise 而非实际结果——若忽略返回值，TypeScript 无法检测该错误
• 需显式调用 returning() 才能获取插入/更新后的行数据；否则仅返回 { rowCount }
• JSON 列类型：PostgreSQL 使用 jsonb()，MySQL 使用 json()——函数误用将导致序列化异常