基础 16 · 数据库怎么存东西

数据库就是一张巨大的、按行按列规矩排好的表。

「正经的表格」是给人看的：歪着写、加个颜色、画个框。数据库的表格是给机器用的：每列的类型固定、每行的宽度固定、谁在第几行不能乱。规矩换来的是「找得快、不认错、并发不乱」。

数据库的词汇就这几个。先用一句话说清，再看你项目里长什么样：

主键 vs 唯一键：差在哪

表名全部来自 packages/db/src/schema.ts，一个不多一个不少。文件名里已经写了分组注释：

外键是「指针」。下面每一条都是 schema.ts 里真的写了 .references(() => xxx.id) 的：

为什么订单必须拆成主表 + 明细表

因为一条订单天然有多行商品。如果硬塞进一张表，只有两个办法，两个都错：

所有 SQL 就四个动作，动词开头：

下面三条是你项目里真实会跑的查询。左边是纯 SQL，右边是 drizzle 写法（packages/db 用的就是右边这种，但它只是帮你拼字符串，底下还是左边这条 SQL）：

-- ①查：某一家经销商门店的全部订单（前端：门店订单列表页）
SELECT o.id, o.order_no, o.status, o.total_min, o.total_max, o.created_at
FROM order o
JOIN dealer d ON d.id = o.dealer_id
WHERE d.code = 'DL01'
ORDER BY o.created_at DESC;

-- ② 查：某个型号的 BOM（前端：点型号看用料清单）
--注意 order_line.model 是业务型号，直接可读
SELECT l.bom_cat, l.item, l.sku, l.spec, l.material, l.qty, l.unit, l.route, l.supplier, l.line_cost
FROM bom_line l
JOIN order_line ol ON ol.id = l.order_line_id
WHERE ol.model = 'H4-T52'
ORDER BY l.bom_cat;

-- ③ 查：某SKU 在各仓库的存量（前端：库存看板）
SELECT i.sku, w.name AS warehouse, i.qty, i.locked, i.safety_stock, i.updated_at
FROM inventory i
JOIN warehouse w ON w.id = i.warehouse_id
WHERE i.sku = 'HINGE-H4002';

// drizzle 写法（等价于上面第 ① 条），你项目 packages/db 里的真调用形态
const rows = await db
  .select({ id: order.id, no: order.orderNo, status: order.status })
  .from(order)
  .innerJoin(dealer, eq(dealer.id, order.dealerId))
  .where(eq(dealer.code, 'DL01'))
  .orderBy(desc(order.createdAt));

你项目里所有状态都用TS 常量数组声明，这是最省心的做法。源码长这样（schema.ts 开头部分，真实代码）：

export const USER_ROLES  = ['admin', 'factory', 'dealer'] as const;
export const ORDER_STATUS = ['draft', 'submitted', 'reviewed', 'approved',
                             'rejected', 'in_production', 'done', 'cancelled'] as const;
export const PO_STATUS   = ['draft', 'submitted', 'partial', 'received', 'cancelled'] as const;
export const WO_STATUS   = ['open', 'in_progress', 'completed', 'cancelled'] as const;
export const REQ_STATUS  = ['pending', 'issued', 'cancelled'] as const;
export const MOVE_TYPES  = ['in', 'out', 'lock', 'unlock', 'count'] as const;

as const 是关键：它让这个数组的类型变成「只读的字面量联合类型」，所以 status 列的类型推导出来是 'draft' | 'submitted' | ...。你写一个 status: 'shipped'，TypeScript 当场报错——因为拼写错了或者状态压根不存在。

为什么绝不能用魔法数字

// ✗ 魔法数字：三个月后你自己都忘了3 是啥
await db.update(order).set({ status: 3 });

// ✓ 常量：一眼看懂
await db.update(order).set({ status: ORDER_STATUS[3] });   // 或者直接写常量名
// 更常见的写法是给状态配一个对象/映射
await db.update(order).set({ status: 'in_production' });

先说痛点。你改了 schema.ts，以为数据库变了——其实没有。

迁移（migrate）就是「按新图纸改造现场」这个动作。你项目有两条命令，一前一后，顺序不能换：

# 完整流程，你项目根目录敲
npm run db:generate# 1. 改了 schema.ts 之后先跑这个 → 生成迁移文件
npm run db:migrate    # 2. 再跑这个 → 迁移文件真正应用到 .db
npm run db:seed        # 3.（可选）灌初始主数据：SKU 主数据、系列价格、真实型号

德莉玛门店系统的 collections 表曾经把一整个对象存成一个字段（单行 JSON blob）。后果不是「不好看」，是三件事同时崩：①写坏整行就崩（改一个字段要重写整行，JSON 一旦截断就整行读不出来，连正常数据也取不到）；②没法查询（想找「某个型号的那条」只能全表扫，扫出来还得在应用层 JSON.parse 再筛）；③并发直接串行（同一行只能一个人写，别人全等）。这就是「存成一坨」和「拆成可独立查询的最小单元」的真实差距。

刚开发时表小，怎么查都飞快，于是「用这个字段查一下」就顺手写进代码了。数据涨到几万行后同一个页面要几秒。回过头看，那个字段既没 unique() 也没建索引。数据库只能一行一行扫（叫全表扫描），扫完才算得出结果。判断方法：任何出现在 WHERE 右边的列，都要问一句「它有索引吗」。

比如用 uuid 或时间戳字符串当主键。两个坏处：①顺序乱——UUID 是随机的，插到表里到处乱放，「按主键取前 20 条最新」这种需求就没法用「顺序」实现；②索引失效变慢——主键会进所有索引，随机字符串让索引页不断分裂、频繁重排，比自增整数慢好几倍。你项目的27 张表里 25 张用 integer 自增做主键，就是这个原因。

见第 06 节。status: 3 这种写法三个月后没人知道是啥，改的时候还得先猜对下标。用常量数组 + enum，让编译器帮你盯着。

见第 07 节。no such column 的头号原因。改了 schema.ts 之后必须 generate + migrate。

这个坑你没踩，但你项目做对了，值得认一下：inventory（当前存量：qty/locked）和 inventory_movement（流水：谁在什么时候加减了多少、ref_type 指回来源单据）是两张表。如果只留一张、只存当前值，那「上周三这批货为什么少了 20」就永远答不上来——因为历史被覆盖了。

• ✓我知道你全盘只有 SQLite 家族（delimao-system 的 libsql / 门店系统的 better-sqlite3），没有 MySQL 和 PostgreSQL
• ✓我能说出 schema.ts 里27 张表的名字，能按①~⑨ 九个业务层归类
• ✓我讲得出主键 vs 唯一键的区别，并知道主键全表只能一个、不能为空
• ✓我知道为什么你27 张表里 25 张用 integer 自增主键，只有 param.key 和 std_parts.part_key 用 text 主键
• ✓我讲得出 5 条真实外键连线，尤其是 sku_price.sku 和 inventory.sku 指向的是唯一键 sku 字符串不是主键
• ✓我知道索引不存数据（书目录页类比），也知道 unique() 是「顺便」的索引
• ✓我能解释为什么订单必须拆主表 + 明细表（一条订单有多行商品，共有的放一起，各自的另起一行）
• ✓我能背出 SELECT/INSERT/UPDATE/DELETE，并知道 UPDATE/DELETE 漏WHERE 会清全表
• ✓我能说出 6 个状态常量数组的全部值，尤其 ORDER_STATUS 的 8 个态
• ✓我知道 as const 的作用：写错状态拼写当场编译报错
• ✓我能分清 db:generate（生成迁移文件，不碰库）和 db:migrate（真正改库），且知道顺序不能换
• ✓我能讲清 collections 表JSON blob 事故的三个后果：写坏整行就崩、没法查询、并发串行