分区指南

> **文档版本**: v1.0.0
> **创建日期**: 2026-02-12
> **最后更新**: 2026-02-12
> **维护人**: 未来鸟FutureBird码巢企业服务引擎开发组
> **状态**: [最新]

---

# PostgreSQL 分区表使用指南

## 概述

本项目采用 PostgreSQL 分区表架构，按 `company_id` 进行 LIST 分区，以支持多租户 SaaS 应用的数据增长需求。

## 分区策略

### 分区键
- **分区列**: `company_id`
- **分区方式**: LIST 分区
- **原因**: 多租户场景下，大部分查询都是针对单个企业，使用 LIST 分区可以实现高效的分区裁剪

### 分区表
以下表采用分区策略：
1. **saas_users**: 用户表（按 company_id 分区）
2. **salary_slips**: 工资单表（按 company_id 分区）
3. **saas_orders**: 订单表（按 company_id 分区）

### 普通表
以下表保持为普通表（数据量小，无需分区）：
1. **saas_companies**: 企业表（数据量小，查询频率低）

## 分区表结构

### 复合主键设计

由于 PostgreSQL 分区表要求主键必须包含分区列，因此所有分区表采用复合主键：

```sql
-- saas_users
PRIMARY KEY (company_id, id)

-- salary_slips
PRIMARY KEY (company_id, id)

-- saas_orders
PRIMARY KEY (company_id, id)
```

### 索引策略

- **主键索引**: 复合主键索引 `(company_id, id)`
- **唯一索引**: 企业内唯一（如 email、username 在 company_id 范围内唯一）
- **普通索引**: tenant_id、status 等常用查询列

## 使用指南

### 1. 为新企业创建专用分区

当新企业注册时，为企业创建专用分区：

```bash
pnpm tsx scripts/manage-partitions.ts create <company_id>
```

**示例**:
```bash
pnpm tsx scripts/manage-partitions.ts create 550e8400-e29b-41d4-a716-446655440000
```

这将创建以下分区：
- `saas_users_550e8400_e29b_41d4_a716_446655440000`
- `salary_slips_550e8400_e29b_41d4_a716_446655440000`
- `saas_orders_550e8400_e29b_41d4_a716_446655440000`

### 2. 查看所有分区

```bash
pnpm tsx scripts/manage-partitions.ts list
```

输出示例：
```
&#128203; 分区列表：

saas_orders:
    &#128230; saas_orders_default (默认分区)
    &#127970; saas_orders_550e8400_e29b_41d4_a716_446655440000

saas_users:
    &#128230; saas_users_default (默认分区)
    &#127970; saas_users_550e8400_e29b_41d4_a716_446655440000

salary_slips:
    &#128230; salary_slips_default (默认分区)
    &#127970; salary_slips_550e8400_e29b_41d4_a716_446655440000
```

### 3. 删除企业分区

当企业注销时，删除对应的分区：

```bash
pnpm tsx scripts/manage-partitions.ts delete <company_id>
```

**注意**: 删除分区会同时删除该分区的所有数据，操作前请确认！

## 应用层使用

### Drizzle ORM 代码兼容性

分区表对应用层完全透明，无需修改现有的 Drizzle ORM 代码：

```typescript
// 插入数据（自动路由到对应分区）
await db.insert(saasUsers).values({
  company_id: 'xxx',
  username: 'user',
  email: 'user@example.com',
  // ...
});

// 查询数据（自动使用分区裁剪）
const users = await db.select()
  .from(saasUsers)
  .where(eq(saasUsers.company_id, 'xxx'));
```

### 查询优化建议

#### 1. 始终使用 company_id 过滤

```typescript
// ✅ 好 - 使用分区裁剪
const users = await db.select()
  .from(saasUsers)
  .where(
    and(
      eq(saasUsers.company_id, companyId),
      eq(saasUsers.status, 'ACTIVE')
    )
  );

// ❌ 差 - 扫描所有分区
const allActiveUsers = await db.select()
  .from(saasUsers)
  .where(eq(saasUsers.status, 'ACTIVE'));
```

#### 2. 使用复合主键查询

```typescript
// ✅ 最高效 - 使用主键索引
const user = await db.select()
  .from(saasUsers)
  .where(
    and(
      eq(saasUsers.company_id, companyId),
      eq(saasUsers.id, userId)
    )
  );
```

## 性能测试

### 测试分区裁剪

运行测试脚本验证分区裁剪效果：

```bash
pnpm tsx scripts/test-partition-functionality.ts
```

测试输出示例：
```
&#128269; 步骤 2: 测试分区裁剪查询（单企业）...
  查询计划（企业 1 的用户）：
    Index Scan using saas_users_default_company_id_username_idx
  ✅ 使用了索引/分区裁剪
```

## 最佳实践

### 1. 分区创建时机

- **新企业注册时**: 立即创建专用分区
- **默认分区**: 对于未创建专用分区的小企业，数据会进入默认分区 `*_default`

### 2. 分区命名规范

分区命名格式：`{表名}_{company_id}`

- 原始 company_id: `550e8400-e29b-41d4-a716-446655440000`
- 分区名称: `saas_users_550e8400_e29b_41d4_a716_446655440000`
- (将 `-` 替换为 `_`)

### 3. 数据迁移

如果已有企业数据，需要迁移到专用分区：

```sql
-- 1. 创建专用分区
CREATE TABLE saas_users_new_partition PARTITION OF saas_users
FOR VALUES IN ('company-id');

-- 2. 从默认分区迁移数据
INSERT INTO saas_users_new_partition
SELECT * FROM saas_users_default
WHERE company_id = 'company-id';

-- 3. 删除默认分区中的数据
DELETE FROM saas_users_default
WHERE company_id = 'company-id';
```

## 回滚方案

如果需要回滚到非分区表，请按以下步骤操作：

### 1. 备份现有数据

```bash
# 导出数据
pg_dump $DATABASE_URL -t saas_users > saas_users_backup.sql
pg_dump $DATABASE_URL -t salary_slips > salary_slips_backup.sql
pg_dump $DATABASE_URL -t saas_orders > saas_orders_backup.sql
```

### 2. 删除分区结构

```sql
-- 删除所有专用分区
DROP TABLE IF EXISTS saas_users_550e8400_e29b_41d4_a716_446655440000 CASCADE;
DROP TABLE IF EXISTS salary_slips_550e8400_e29b_41d4_a716_446655440000 CASCADE;
DROP TABLE IF EXISTS saas_orders_550e8400_e29b_41d4_a716_446655440000 CASCADE;

-- 删除默认分区
DROP TABLE IF EXISTS saas_users_default CASCADE;
DROP TABLE IF EXISTS salary_slips_default CASCADE;
DROP TABLE IF EXISTS saas_orders_default CASCADE;

-- 删除父表
DROP TABLE IF EXISTS saas_users CASCADE;
DROP TABLE IF EXISTS salary_slips CASCADE;
DROP TABLE IF EXISTS saas_orders CASCADE;
```

### 3. 创建普通表

使用原始的 `scripts/init-database.ts` 重新创建表结构。

### 4. 恢复数据

```bash
psql $DATABASE_URL < saas_users_backup.sql
psql $DATABASE_URL < salary_slips_backup.sql
psql $DATABASE_URL < saas_orders_backup.sql
```

## 监控与维护

### 查看分区统计

```sql
SELECT
  schemaname,
  relname AS tablename,
  n_live_tup AS row_count,
  n_dead_tup AS dead_row_count
FROM pg_stat_user_tables
WHERE relname LIKE 'saas_%'
ORDER BY relname;
```

### 检查索引使用情况

```sql
SELECT
  schemaname,
  tablename,
  indexname,
  idx_scan AS index_scans,
  idx_tup_read AS tuples_read
FROM pg_stat_user_indexes
WHERE schemaname = 'public'
ORDER BY tablename, indexname;
```

## 故障排查

### 问题 1: 插入数据时提示分区未找到

**错误**: `no partition of relation "saas_users" found for row`

**原因**: 插入的数据 company_id 没有对应的分区

**解决**: 创建专用分区或数据会进入默认分区

### 问题 2: 查询性能未提升

**原因**: 查询没有使用 company_id 过滤，无法触发分区裁剪

**解决**: 在查询条件中添加 company_id

### 问题 3: 主键冲突

**错误**: `duplicate key value violates unique constraint`

**原因**: 复合主键 `(company_id, id)` 组合冲突

**解决**: 确保每个企业内的 id 唯一，或使用 uuid 自动生成

## 脚本列表

| 脚本 | 功能 |
|------|------|
| `scripts/create-partitioned-tables.ts` | 创建分区表结构 |
| `scripts/manage-partitions.ts` | 管理分区（创建/列表/删除） |
| `scripts/test-partition-functionality.ts` | 测试分区表功能 |
| `scripts/verify-partitions.ts` | 验证分区表状态 |
| `scripts/cleanup-old-tables.ts` | 清理旧表 |

## 参考资源

- [PostgreSQL 分区表文档](https://www.postgresql.org/docs/current/ddl-partitioning.html)
- [LIST 分区最佳实践](https://www.postgresql.org/docs/current/sql-createpartitionedtable.html)