Drizzle-Kit推送PostgreSQL Schema时Windows报serial类型不存在错误

问题场景 #

基于Drizzle ORM的后端项目，在Windows和MacOS设备上克隆部署后，MacOS端可正常推送Schema至最新PostgreSQL镜像，但Windows端触发如下错误：

error: "serial" type does not exists
    at \node_modules\drizzle-kit\bin.cjs:24462:21
    at process.processTicksAndRejections (node:internal/process/task_queues:95:5)
    at async PgPostgres.query (\node_modules\drizzle-kit\bin.cjs:25423:21)
    at async Command.<anonymous> (\node_modules\drizzle-kit\bin.cjs:63261:9) {
  length: 89,
  severity: 'ERRORE',
  code: '42704',
  detail: undefined,
  hint: undefined,
  position: undefined,
  internalPosition: undefined,
  internalQuery: undefined,
  where: undefined,
  schema: undefined,
  table: undefined,
  column: undefined,
  dataType: undefined,
  constraint: undefined,
  file: 'parse_type.c',
  line: '274',
  routine: 'typenameType' 
}

已尝试操作：删除并重新克隆仓库、更新Node.js、重新安装PostgreSQL镜像，期望两端操作表现一致。

排查与解决方法 #

1. 对齐PostgreSQL容器启动参数 #

PostgreSQL的serial是原生支持的自增类型语法糖，报错不存在大概率是Windows端容器启动配置异常。对比Mac和Windows的容器启动命令，确保：

• 环境变量（POSTGRES_USER、POSTGRES_DB、POSTGRES_PASSWORD等）完全一致
• 未添加禁用类型支持的自定义参数（如特殊--locale配置）
• 挂载卷、端口映射等配置无差异

2. 统一Drizzle Kit依赖版本 #

即使更新了Node.js，Windows端可能存在依赖安装差异：

• 在两端分别执行npm list drizzle-kit（或对应包管理器命令），确认版本完全一致
• 若版本不一致，在package.json中锁定drizzle-kit版本号，删除Windows端的node_modules和package-lock.json，重新执行npm install
• 可直接复制Mac端的package-lock.json到Windows后再安装依赖，消除版本差异

3. 检查Schema字段定义 #

确保Schema中自增字段使用Drizzle官方提供的方法，而非手动指定"serial"字符串类型：
正确写法：

import { serial } from "drizzle-orm/pg-core";

// 表定义示例
export const users = pgTable("users", {
  id: serial("id").primaryKey(),
  // 其他字段...
});

避免直接写type: "serial"这类手动指定类型的写法，防止Drizzle Kit生成错误SQL。

4. 验证PostgreSQL容器内的类型支持 #

进入Windows端的PostgreSQL容器，执行SQL验证serial类型是否存在：

SELECT typname FROM pg_type WHERE typname = 'serial';

若查询无结果，说明容器镜像本身有问题，重新拉取官方PostgreSQL镜像，避免使用自定义修改后的镜像。

5. 排查文件系统大小写问题 #

Windows文件系统大小写不敏感，MacOS则敏感，若Schema文件中的表名、字段名大小写与数据库内实际存在的对象不一致，可能间接导致解析异常。检查Schema定义中的命名是否统一，确保与数据库内的对象命名匹配。

内容的提问来源于stack exchange，提问作者Lunikkun