---
date: 2026-05-09
type: error
tags: [prisma, postgres, citext, setup-worktree, agent-pool]
---

# 新 worktree 首次 prisma db push 报 type "citext" does not exist（fix 在 PR #248 里）

## 现象

`scripts/dev/setup-worktree.sh` 起新 PG 容器后跑 `prisma db push` 失败：

```
Error: ERROR: type "citext" does not exist
   0: sql_schema_connector::apply_migration::migration_step
           with step=CreateTable { table_id: TableId(133) }
```

setup-worktree 后续步骤（db:seed / init:itadmin）都因为 schema 没建出来连环失败。

## 根因

`platform_ops_center.prisma` 用了 `@db.Citext`（case-insensitive 文本，PostgreSQL 扩展）。
`prisma db push` **不跑 migrations**——只读 schema 推送，不会执行 `migrations/*/migration.sql` 里的 `CREATE EXTENSION` 行。

而 setup-worktree.sh 的 `setup_database()` 只做 `docker run postgres:16-alpine` + `pg_isready`，**没装扩展**。fresh 容器只有默认的 `plpgsql`。

## 解法

PR #248 已修：commit `fa1dd5e4 fix(worktree-setup): 自动安装 citext 扩展，修首次 db push 失败的根因`

```bash
local PG_EXTENSIONS=(citext)
for ext in "${PG_EXTENSIONS[@]}"; do
  docker exec -e PGPASSWORD="${db_password}" "${container_name}" \
    psql -U "${db_user}" -d "${db_name}" -tAc "CREATE EXTENSION IF NOT EXISTS ${ext};"
done
```

放在 PG ready 之后、prisma db push 之前。新增扩展只往数组里加。

## 适用范围

- agent-pool 的 pool-init 内部调 setup-worktree.sh，**也吃这个 bug**——必须包含 fa1dd5e4 的 fix 才能成功 `pool-init`。
- 任何用 `prisma db push` + 容器化 fresh PG 的项目都可能踩，扩展不会自动装。
- `prisma migrate deploy` 路径不踩（migrations 里有 CREATE EXTENSION）。但 setup 流程现在用的是 push。

## 教训

1. **`prisma db push` ≠ `prisma migrate deploy`**：前者从 schema 直推，跳过 migrations。schema 用了任何需要 EXTENSION 的类型，就要保证 EXTENSION 已装。
2. **新模块加 PG 扩展**时，必须**同时**：
   - schema.prisma 里声明 `previewFeatures = ["postgresqlExtensions"]` + `extensions = [citext]`（如启用）
   - 或在 setup-worktree.sh 的 `PG_EXTENSIONS` 数组里加上
   - 否则 fresh 环境永远炸
3. **多分支并行开发的连锁**：这个 bug 在 PR #248 里改了，但 PR #248 自己还没合 develop。任何从 develop 切出来的新 worktree（比如 agent-pool 的 feature 分支）都要自己 cherry-pick fa1dd5e4 才能用，不然 pool-init 第一步就炸。
4. **诊断窍门**：`docker exec <pg-container> psql -c "\dx"` 看已装扩展。新容器只 plpgsql 就是异常，正常 ffoa 项目应有 citext。

## 关联

- 上游 commit：[fa1dd5e4](http://43.130.59.228/FFAIWorkspace/workspace/commit/fa1dd5e4)
- ERR-20260508-003 也涉及（订正 ERR-20260429-014 的误诊）