# @eftech93/prisma-shift 中文文档

规范地址：https://npmcn.com/package/%40eftech93/prisma-shift/

版本：0\.0\.3
npm 元数据更新时间：2026-04-18T05:01:41.153Z
中文译文更新时间：2026-11-14T00:27:06.439Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40eftech93/prisma-shift
原文对照：https://npmcn.com/package/%40eftech93/prisma-shift/?lang=original
项目主页：https://eftech93.github.io/prisma-shift/
源码仓库：https://github.com/eftech93/prisma-shift

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：411 kB，93 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：@prisma/client \>=5\.0\.0
- 首次发布：2026-03-26T03:26:52.896Z
- 最新版本发布：2026-04-18T05:01:41.040Z
- 近 30 天下载量：2728（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 3 个）

## 中文简介

Prisma 的基于脚本的数据迁移 。 通过分布式锁定、批量处理和60QQ测试覆盖,同时进行数据转换.

## 安装

```sh
npm install @eftech93/prisma-shift
```

也可以使用：`pnpm add @eftech93/prisma-shift`、`yarn add @eftech93/prisma-shift`、`bun add @eftech93/prisma-shift`

## README

# Prisma 移动

[![Documentation](https://img.shields.io/badge/docs-eftech93.github.io%2Fprisma--shift-blue)](https://eftech93.github.io/prisma-shift/) [![Test Coverage](https://img.shields.io/badge/coverage-60%25-yellowgreen)](https://eftech93.github.io/prisma-shift/test-report.html) [![Tests](https://img.shields.io/badge/tests-118%20passing-brightgreen)](https://eftech93.github.io/prisma-shift/test-report.html) [![Version](https://img.shields.io/npm/v/@eftech93/prisma-shift)](https://www.npmjs.com/package/@eftech93/prisma-shift)

**[\* 完整文档](https://eftech93.github.io/prisma-shift/)** | **[测试报告](https://eftech93.github.io/prisma-shift/test-report.html)**

Prisma 的基于脚本的数据迁移 。 运行数据转换, 并同时运行您的计划迁移, 并具有完整的类型安全和访问 Prisma 客户端 .

> **++ 在 0.0. 2 中新建 :** 分布式锁接,分批处理,有条件的迁移,迁移的依赖性,还有更多!

## 为什么?

普里斯马的本土迁移处理出计划变化,但数据迁移往往需要:

-   运行 Java 脚本/ Type 脚本代码
-   使用 Prisma 客户端查询和转换数据
-   SQL 无法处理的复杂数据转换
-   保持移徙历史和回滚能力

这个扩展提供了无缝的写出,运行,以及使用TypeScript管理数据迁移的方法.

## 安装

```bash
npm install prisma-shift
# or
yarn add prisma-shift
# or
pnpm add prisma-shift
```

## Prisma 发电机(建议)

整合数据迁移的最清洁方式是使用 **Prisma 生成器**中添加此选项 `schema.prisma`数字 :

```prisma
generator dataMigration {
  provider      = "prisma-shift-generator"
  migrationsDir = "./prisma/data-migrations"  // optional
}
```

现在数据迁移将 **自动运行 `prisma migrate deploy`**数字 :

```bash
npx prisma migrate deploy  # Schema + data migrations in one command!
```

### 生成器选项

| 选项 | 说明 | 默认 |
| --- | --- | --- |
| `migrationsDir` | 迁移文件目录 | `./prisma/data-migrations` |
| `migrationsTable` | 移民历史数据库表 | `_dataMigration` |

### 环境变量

您也可以通过环境变量配置 :

```bash
DATA_MIGRATIONS_DIR=./prisma/data-migrations
DATA_MIGRATIONS_TABLE=_dataMigration
```

## Prisma CLI 整合

或者,用我们的 **Prisma CLI 包装器** 自动运行在图中迁移后的数据迁移:

### 替换 `prisma` 与 `prisma-shift-migrate`

```bash
# Instead of running these 3 commands:
# npx prisma migrate deploy
# npx prisma generate
# npx prisma-shift run

# Just run this ONE command:
npx prisma-shift-migrate migrate deploy
```

### 添加到您的包裹。 json

```json
{
  "scripts": {
    "migrate": "prisma-shift-migrate migrate deploy",
    "migrate:dev": "prisma-shift-migrate migrate dev"
  }
}
```

那就赶紧跑 `npm run migrate` - 它处理一切!

[• 阅读完整的融合指南](https://npmcn.com/package/%40eftech93/prisma-shift/docs/prisma-integration.md)

## 快速启动

### 1\. 初始化

```bash
npx prisma-shift init
```

这创造了一个 `prisma/data-migrations` 目录.

### 2\. 创造移徙

```bash
npx prisma-shift create "add_default_preferences"
```

生成迁移文件 :

```typescript
// prisma/data-migrations/20240324120000_add_default_preferences.ts
import { DataMigration, MigrationContext } from "prisma-shift";

const migration: DataMigration = {
  id: "20240324120000_add_default_preferences",
  name: "add_default_preferences",
  createdAt: 1711281600000,

  async up({ prisma, log }: MigrationContext) {
    await prisma.user.updateMany({
      where: { preferences: null },
      data: { preferences: { theme: "light", notifications: true } }
    });
    
    log("Added default preferences to users");
  },

  async down({ prisma, log }: MigrationContext) {
    await prisma.user.updateMany({
      data: { preferences: null }
    });
    log("Cleared user preferences");
  }
};

export default migration;
```

### 3\. 管理移徙

**备选办法A:结合Prisma CLI(建议)**

使用我们的空降替代 Prisma CLI :

```bash
# This runs schema migrations + data migrations together!
npx prisma-shift-migrate migrate deploy
```

**备选案文B:手册**

```bash
# Run data migrations only
npx prisma-shift run

# Run schema + data migrations together
npx prisma-shift run --with-schema

# Wait for lock if another instance is running
npx prisma-shift run --wait
```

## ++ 完整示例

见 [统一民主](https://npmcn.com/package/%40eftech93/prisma-shift/examples/unified-demo/) 综合实例 **3个计划迁移** 财务报告和审定财务报表 **12个数据迁移**数字 :

```bash
cd examples/unified-demo

# Start PostgreSQL (Docker)
docker-compose up -d

# Install and run
npm install && npm run migrate
```

**演示内容包括:**

-   **多克编曲** - PostgreSQL + 管理者数据库
-   **3 Schema 移民(SQL)** - 创建表格并添加列
-   **12 数据迁移( TypeScript)** - 转换数据
-   **JSON 数据加载** - 文件的种子数据
-   **已计算字段** - 产生流涕、摘录、阅读时间
-   **大型数据集处理** - 有进展的批处理
-   **Enum 迁移** - 变换状态值
-   **多表同步** - 各表的总数
-   **有条件移徙** - 基于地标的处决
-   **移徙依赖性** - 确保适当订购
-   **长期移徙** - 有超时支持

[\+ 完整实例文档](https://npmcn.com/package/%40eftech93/prisma-shift/examples/unified-demo/)

## QQ Schema vs 数据迁移

| 类型 | 目的 | 工具 | 示例 |
| --- | --- | --- | --- |
| **Schema 迁移** | 数据库结构 | `prisma migrate` | 添加列, 创建表格 |
| **数据迁移** | 转换数据 | `prisma-shift` | 回填, 常态 |

### 黄金规则

> **在依赖它们的数据迁移之前, 总是应用策略迁移 .**

```bash
# 1. Schema migration (structure)
npx prisma migrate dev --name add_slug_column

# 2. Generate Prisma Client (CRITICAL!)
npx prisma generate

# 3. Data migration (transformation)
npx prisma-shift create backfill_slugs
npx prisma-shift run
```

## 用作 Prisma 扩展

### 备选案文1:使用 `withDataMigrations`

```typescript
import { PrismaClient } from "@prisma/client";
import { withDataMigrations } from "prisma-shift";

const basePrisma = new PrismaClient();

const prisma = withDataMigrations(basePrisma, {
  migrationsDir: "./prisma/data-migrations",
});

// Now available:
// await prisma.$dataMigrations.run()     // Run pending
// await prisma.$dataMigrations.status()  // Check status
// await prisma.$dataMigrations.rollback() // Rollback last
```

### 备选案文2:使用 `createPrismaClientWithMigrations`

```typescript
import { createPrismaClientWithMigrations } from "prisma-shift";

const prisma = createPrismaClientWithMigrations({
  migrationsDir: "./prisma/data-migrations",
  autoRun: true, // Auto-run on startup (optional)
});
```

## CLI 命令

| 命令 | 说明 |
| --- | --- |
| **`prisma-shift-migrate`** | **滴入式 CLI 替换** ⭐ |
| **`deploy`** | **一起运行 schema + 数据迁移** |
| `init` | 初始化数据迁移 |
| `create <name>` | 创建新数据迁移 |
| `status` | 显示迁移状态 |
| `run` | 只运行数据迁移 |
| `run --with-schema` | 运行 schema + 数据迁移 |
| `run --wait` | 如果另一个实例正在运行, 请等待锁定 |
| `run --dry-run` | 预览将运行的 |
| `validate` | 验证迁移文件 |
| `rollback` | 上次回滚迁移 |
| `reset` | 清除移徙记录 |
| `squash` | 将多个移入 |
| `export` | 出口移民历史 |

### Prisma CLI 剪贴机( 建议)

使用 `prisma-shift-migrate` 和普通的Prisma CLI一样:

```bash
# Deploy schema + data migrations in one command
npx prisma-shift-migrate migrate deploy

# Development mode
npx prisma-shift-migrate migrate dev

# Generate client
npx prisma-shift-migrate generate
```

添加到您的 `package.json`数字 :

```json
{
  "scripts": {
    "migrate": "prisma-shift-migrate migrate deploy",
    "migrate:dev": "prisma-shift-migrate migrate dev"
  }
}
```

### 平地移徙

通过将多种移徙合并为一种来清理长期移徙历史:

```bash
# Squash migrations from March 2024 into a single file
npx prisma-shift squash --from=20240301 --to=20240331 --name="march_changes"

# Dry run to preview what would happen
npx prisma-shift squash --from=20240301 --to=20240331 --name="march_changes" --dry-run

# Keep original files (don't delete them)
npx prisma-shift squash --from=20240301 --to=20240331 --name="march_changes" --keep
```

**它会做什么:**

-   合并所有迁移 `up` 区域中的函数输入一个新的迁移文件
-   删除原始迁移文件( 除非 `--keep` 用于)
-   更新数据库迁移记录,以反映被压抑的迁移
-   只有工作在 **已执行** 迁移(待迁移范围将阻碍行动)

### 统一部署指挥部(建议)

运行 **所有的东西** 在一个命令中:

```bash
npx prisma-shift deploy
```

运行完整序列 :

1.  `prisma migrate deploy` - Schema移民
2.  `prisma generate` - 生成 Prisma 客户端
3.  `prisma-shift run` - 数据迁移

## 部署脚本

### 备选方案1:使用统一部署指挥

```bash
#!/bin/bash
set -e

# One command does it all!
npx prisma-shift deploy

npm start
```

### 备选案文2:手动序列(如果需要更多的控制)

```bash
#!/bin/bash
set -e

npx prisma migrate deploy   # Schema migrations
npx prisma generate         # Generate client
npx prisma-shift run        # Data migrations
npm start
```

### 备选办法3:使用等待旗(用于多层部署)

```bash
#!/bin/bash
set -e

# Use --wait to ensure only one instance runs migrations at a time
npx prisma-shift run --with-schema --wait

npm start
```

## 高级特性

### 有条件移徙

仅在满足条件时进行迁移 :

```typescript
const migration: DataMigration = {
  id: "20240325120000_enable_feature_x",
  name: "enable_feature_x",
  
  // Only run if condition is met
  condition: async ({ prisma }) => {
    const config = await prisma.config.findFirst();
    return config?.featureXEnabled === true;
  },
  
  async up({ prisma, log }) {
    // Migration logic
    log("Feature X is enabled, running migration...");
  },
};
```

### 移徙依赖性

确保按正确顺序迁移:

```typescript
const migration: DataMigration = {
  id: "20240325_add_user_stats",
  name: "add_user_stats",
  // Requires these schema migrations first
  requiresSchema: ["20240324000002_add_categories"],
  // And these data migrations
  requiresData: ["20240324010003_setup_profiles"],
  
  async up({ prisma, log }) {
    // Migration logic
  },
};
```

### 批处理

高效处理大型数据集:

```typescript
async up({ prisma, log, batch }: MigrationContext) {
  await batch({
    query: () => prisma.post.findMany({ where: { processed: false } }),
    batchSize: 1000,
    process: async (posts) => {
      await prisma.post.updateMany({
        where: { id: { in: posts.map(p => p.id) } },
        data: { processed: true }
      });
    },
    onProgress: (processed, total) => {
      log(`Processed ${processed}/${total}`);
    },
  });
}
```

### 长跑移徙

超过交易超时的迁移:

```typescript
const migration: DataMigration = {
  id: "20240325_backfill_large_table",
  name: "backfill_large_table",
  
  // Custom timeout (default: 0 = no timeout)
  timeout: 300000, // 5 minutes
  
  // Disable transaction for very long operations
  disableTransaction: true,
  
  async up({ prisma, log, signal }) {
    // Check for cancellation
    if (signal?.aborted) {
      throw new Error("Migration was cancelled");
    }
    
    // Long-running work...
  },
};
```

### 分布式锁定

防止在多重部署中同时迁移:

```typescript
const runner = new MigrationRunner(prisma, {
  migrationsDir: "./migrations",
  lock: {
    enabled: true,
    timeout: 30000,      // Lock expires after 30s
    retryAttempts: 3,    // Retry 3 times
    retryDelay: 1000,    // Wait 1s between retries
  },
});
```

或者用那个 `--wait` CLI旗无限期等:

```bash
npx prisma-shift run --wait
```

### 钩子

迁移前后运行脚本 :

```typescript
// prisma-shift.config.ts
export default {
  hooks: {
    beforeAll: "./scripts/backup.ts",    // Before any migration
    beforeEach: "./scripts/notify.ts",   // Before each migration
    afterEach: "./scripts/verify.ts",    // After each migration
    afterAll: "./scripts/cleanup.ts",    // After all migrations
  },
};
```

## 常见模式

### 正在装入 JSON 数据

```typescript
import * as fs from "fs";
const data = JSON.parse(fs.readFileSync("./data/seed.json", "utf8"));
for (const item of data) {
  await prisma.user.create({ data: item });
}
```

### 《同上》更新

```typescript
// Only process unmigrated records
const posts = await prisma.post.findMany({
  where: { slug: null },
});
```

### Batching 大型数据集

```typescript
const BATCH_SIZE = 1000;
while (hasMore) {
  const batch = await prisma.post.findMany({
    where: { processed: false },
    take: BATCH_SIZE,
  });
  // Process batch...
}
```

## 配置

创建一个 `prisma-shift.config.ts` 文件 :

```typescript
export default {
  migrationsDir: "./prisma/data-migrations",
  migrationsTable: "_dataMigration",
  schemaPath: "./prisma/schema.prisma",
  logging: {
    level: "info",      // silent, error, warn, info, debug
    progress: true,     // Show progress bars
    format: "text",     // text or json
  },
  lock: {
    enabled: true,
    timeout: 30000,
    retryAttempts: 3,
    retryDelay: 1000,
  },
  execution: {
    timeout: 0,         // 0 = no timeout
    transaction: true,  // Run in transaction by default
  },
  typescript: {
    compiler: "tsx",    // tsx or ts-node
    transpileOnly: true,
  },
};
```

### 环境变量

```bash
DATA_MIGRATIONS_DIR=./prisma/data-migrations
DATA_MIGRATIONS_TABLE=_dataMigration
```

## API 参考

### 数据迁移接口

```typescript
interface DataMigration {
  id: string;                    // Unique identifier
  name: string;                  // Description
  createdAt: number;             // Timestamp
  up: (context: MigrationContext) => Promise<void>;
  down?: (context: MigrationContext) => Promise<void>;
  condition?: (context: Pick<MigrationContext, "prisma" | "log">) => Promise<boolean>;
  requiresSchema?: string[];     // Schema migration dependencies
  requiresData?: string[];       // Data migration dependencies
  timeout?: number;              // Custom timeout in ms (0 = none)
  disableTransaction?: boolean;  // Run outside transaction
}
```

### 迁移内容

```typescript
interface MigrationContext {
  prisma: PrismaClient;
  log: CallableLogger;  // log("msg") or log.info("msg")
  batch: <T>(options: BatchOptions<T>) => Promise<BatchResult<T>>;
  progress: (total: number) => ProgressTracker;
  signal?: AbortSignal; // For cancellation/timeouts
}
```

### 可调用

伐木机可用作函数或方法:

```typescript
// Both work:
log("Simple message");           // Defaults to info level
log.info("Info message");        // Explicit info level
log.warn("Warning message");     // Warning level
log.error("Error message");      // Error level
log.debug("Debug message");      // Debug level
```

## 测试

```bash
# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch
```

## 文档

-   [Prisma 整合](https://npmcn.com/package/%40eftech93/prisma-shift/docs/prisma-integration.md) - 与Prisma CLI相结合
-   [工作流程指南](https://npmcn.com/package/%40eftech93/prisma-shift/docs/workflow.md) - 协调计划和数据迁移
-   [统一演示](https://npmcn.com/package/%40eftech93/prisma-shift/examples/unified-demo/) - 3个计划+12个数据迁移的完整实例

## 发布注释

### v0.0.2 (2026-03-28) (中文(简体) )

**新特性 :**

-   **分配锁定** - 防止与PostgreSQL咨询锁在多个情况下同时迁移
-   **移民超时** - 设定每次迁移的自定义超时,通过中止自动取消
-   **在钩子之前/之后** - 在各种迁移生命周期阶段运行脚本(All、All、Arefore、Arefore、Arefore)
-   **XQ 批处理助手** - 通过自动标记和进度跟踪,高效地处理大型数据集
-   **有条件移徙** - 仅在满足特定条件(例如地物旗)时进行迁移
-   **\* 移徙依赖性** - 宣布依赖其他迁移,以确保正确的执行命令
-   **\* 结构化记录** - 有多个级别、进度指标和JSON格式支持的丰富的记录
-   **\* 进展跟踪** - 长期运行的视觉进度栏
-   **移民验证** - 执行前验证迁移文件(检查ID、复制、类型脚本汇编)
-   **导出功能** - 将迁移历史导出为 JSON、 CSV 或 HTML 格式
-   **等待旗帜( V)`--wait`(中文(简体) )** - 等待锁定购置,而不是立即失败(对多层部署来说是好事)
-   **使用- schema 旗帜( A)`--with-schema`(中文(简体) )** - 在数据迁移之前在一个命令中运行 Prisma 计划迁移
-   **QQ 配置文件支持** - 通过 `prisma-shift.config.ts` 文件

**改进:**

-   **可调用 Logger API** - 说吧 `log()` 可调用为函数( e)`log("msg")`或采用方法(`log.info("msg")`(中文(简体) )
-   **交易控制** - 为长期迁移而禁用交易的选项
-   **更好的错误处理** - 清除有迁移背景的错误信息

**示例使用法:**

```bash
# Run with schema migrations
npx prisma-shift run --with-schema

# Wait for lock (for multi-instance deployments)
npx prisma-shift run --wait

# Preview changes
npx prisma-shift run --dry-run

# Validate migrations
npx prisma-shift validate

# Export history
npx prisma-shift export --format=json
```

### v0.0.1 (2024-03-24) (中文(简体) )

**初释:**

-   基于脚本的数据迁移
-   CLI 命令( init, 创建, 运行, 状态, 回滚, 重置)
-   Prisma 客户端扩展名( R)`withDataMigrations`(中文(简体) )
-   计划迁移后自动运行的发电机集成
-   数据库中的移徙跟踪
-   回滚支持

## 许可证

麻省理工学院

## 常见问题

### @eftech93/prisma-shift 是什么？

Prisma 的基于脚本的数据迁移 。 通过分布式锁定、批量处理和60QQ测试覆盖,同时进行数据转换\.

### 如何安装 @eftech93/prisma-shift？

在项目目录运行 npm install @eftech93/prisma-shift，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@prisma/client（\>=5\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 prisma-shift、prisma-shift-generator、prisma-shift-migrate，可以用 npx prisma-shift 直接运行。

### @eftech93/prisma-shift 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @eftech93/prisma-shift 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @eftech93/prisma-shift 可以商用吗？

@eftech93/prisma-shift 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @eftech93/prisma-shift 的下载量有多少？

根据 npm 官方下载统计，@eftech93/prisma-shift 在 2026/10/13 – 2026/11/11 这 30 天内被下载 2,728 次，日均约 91 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @eftech93/prisma-shift 还在维护吗？

最新版本 0\.0\.3 发布于 2026/04/18（6 个月前）；至今共发布 3 个版本，其中过去 12 个月发布了 3 个；首次发布于 2026/03/26。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。