从0到1构建PostgreSQL迁移项目：node-pg-migrate+TypeScript实战案例

【免费下载链接】node-pg-migrate Node.js database migration management for Postgresql 项目地址: https://gitcode.com/gh_mirrors/no/node-pg-migrate

PostgreSQL数据库迁移是现代应用开发中的关键环节，而node-pg-migrate作为Node.js生态中最受欢迎的PostgreSQL迁移工具，结合TypeScript的类型安全特性，能帮助开发者轻松管理数据库架构变更。本文将带你从零开始搭建一个完整的PostgreSQL迁移项目，通过实战案例掌握迁移的核心流程与最佳实践。

📋 环境准备与快速安装

系统要求

• Node.js 20.11或更高版本
• PostgreSQL 13或更高版本（低版本可能兼容但未官方支持）
• pg库作为依赖（node-postgres客户端）

一键安装步骤

首先安装PostgreSQL客户端依赖：

# 使用npm
npm add pg

# 使用pnpm
pnpm add pg

# 使用yarn
yarn add pg

# 使用bun
bun add pg

然后安装node-pg-migrate作为开发依赖：

# 使用npm
npm add -D node-pg-migrate

# 使用pnpm
pnpm add -D node-pg-migrate

# 使用yarn
yarn add -D node-pg-migrate

# 使用bun
bun add -D node-pg-migrate

⚙️ 项目配置与初始化

配置package.json脚本

在package.json中添加迁移命令，方便快速执行：

{
  "scripts": {
    // TypeScript项目配置
    "migrate": "node-pg-migrate -j ts"
  }
}

初始化项目仓库

如需从源码构建，可克隆官方仓库：

git clone https://gitcode.com/gh_mirrors/no/node-pg-migrate
cd node-pg-migrate
pnpm install

🚀 创建第一个迁移文件

生成迁移模板

执行以下命令创建名为my-first-migration的迁移文件：

npm run migrate create my-first-migration
# 生成文件路径：migrations/xxx_my-first-migration.ts

编写TypeScript迁移代码

打开生成的迁移文件，添加创建用户表和文章表的逻辑：

import { MigrationBuilder } from 'node-pg-migrate';

export const up = (pgm: MigrationBuilder) => {
  // 创建用户表
  pgm.createTable('users', {
    id: 'id', // 自动生成的自增主键
    name: { type: 'varchar(1000)', notNull: true },
    createdAt: {
      type: 'timestamp',
      notNull: true,
      default: pgm.func('current_timestamp'),
    },
  });

  // 创建文章表
  pgm.createTable('posts', {
    id: 'id',
    userId: {
      type: 'integer',
      notNull: true,
      references: '"users"', // 外键关联用户表
      onDelete: 'CASCADE', // 删除用户时级联删除文章
    },
    body: { type: 'text', notNull: true },
    createdAt: {
      type: 'timestamp',
      notNull: true,
      default: pgm.func('current_timestamp'),
    },
  });

  // 为文章表的userId字段创建索引
  pgm.createIndex('posts', 'userId');
};

export async function down(pgm: MigrationBuilder): Promise<void> {
  // 回滚操作：先删除依赖表，再删除主表
  pgm.dropTable('posts');
  pgm.dropTable('users');
}

▶️ 执行迁移与版本控制

应用迁移

设置数据库连接字符串并执行迁移：

# Linux/Mac
DATABASE_URL=postgres://test:test@localhost:5432/test npm run migrate up

# Windows (PowerShell)
$env:DATABASE_URL="postgres://test:test@localhost:5432/test"; npm run migrate up

常用迁移命令

• 查看帮助：npm run migrate -- --help
• 执行特定迁移：npm run migrate up 20231001000000_my-first-migration
• 回滚最近一次迁移：npm run migrate down
• 回滚到初始状态：npm run migrate down 0

🔄 数据库架构演进实战

添加新字段

创建添加文章摘要字段的迁移：

npm run migrate create add_posts_lead

编写迁移代码：

import { MigrationBuilder } from 'node-pg-migrate';

export const up = (pgm: MigrationBuilder) => {
  pgm.addColumns('posts', {
    lead: { type: 'text', notNull: true, default: '' },
  });
};

export async function down(pgm: MigrationBuilder): Promise<void> {
  pgm.dropColumns('posts', ['lead']);
}

执行迁移使变更生效：npm run migrate up

📚 进阶功能与最佳实践

事务安全迁移

node-pg-migrate默认将每个迁移包装在事务中，确保原子性。如需禁用事务（例如创建索引），可使用--no-transaction标志。

迁移文件组织

推荐按功能模块组织迁移文件，如：

• users/ - 用户相关迁移
• posts/ - 文章相关迁移
• shared/ - 共享表和通用结构

类型定义与智能提示

核心类型定义位于src/migration.ts，包含MigrationBuilder等关键接口，提供完整的TypeScript智能提示。

📖 官方资源与文档

• 完整API文档：docs/src/api.md
• 迁移操作指南：docs/src/migrations/index.md
• CLI命令参考：docs/src/cli.md

通过本文的实战案例，你已掌握使用node-pg-migrate和TypeScript构建PostgreSQL迁移项目的核心技能。无论是小型应用还是大型系统，这套工具组合都能帮助你安全、高效地管理数据库架构变更，实现平滑的版本迭代。

【免费下载链接】node-pg-migrate Node.js database migration management for Postgresql 项目地址: https://gitcode.com/gh_mirrors/no/node-pg-migrate