• Overview
• Installation
• Usage
  • Commands
  • Quick Start
• Configuration
• Database Support
• Warnings and Considerations
• Contributing
• License

Prisma Data Migrations is a library designed to address the lack of built-in support for data migrations in Prisma ORM. It allows you to execute post-migration scripts alongside schema migrations.

Install the library via npm:

npm install prisma-data-migrations --save-dev

npx prisma-dm help

Output:

Usage: prisma-dm [options] [command]

CLI for Prisma data migrations

Options:
  -V, --version             output the version number
  -h, --help                display help for command

Commands:
  init                      Generate configuration file
  merge:schema [options]    Merge prisma schema folder to single schema file
  generate                  Generate types for data migrations by prisma schemas
  migrate [options]         Migrate to target migration with post scripts execution
  run:postscript [options]  Run a specific data migration post script manually (particularly useful when a post script fails during migration, allowing you to reapply it after fixing the issue)
  help [command]            display help for command

1. Initialize Configuration: Run the following command to create a configuration file:

   npx prisma-dm init

   This generates a default configuration file (prisma-dm.config.json) in the root of your project.

2. Merge Prisma Schema (Optional): If you use prismaSchemaFolder feature, you can merge all prisma files into a single schema file for easier management within the migration folder.

   Example:

   npx prisma-dm merge:schema --schema prisma/schema --output prisma/schema.prisma

   This merges all schemas in the prisma/schema folder into a single schema.prisma file.

3. Add schema.prisma to Migration Folders (Optional): Place the schema.prisma file in the corresponding migration folder alongside migration.sql. This file must match the schema state after applying the Prisma migration.

   ⚠️ Note: You can skip copying the schema.prisma file and generating types if you do not need the Prisma Client. Instead, you can simply add the post-migration script directly to the migration folder. ⚠️ Note: You can change the default schema.prisma filename by using the migrationSchemaFileName key in the config.

4. Generate Types: Run the generate command to create TypeScript types for your data migrations based on your schemas:

   npx prisma-dm generate

5. Create Post-Migration Script: Create a post-migration script in the migration folder. The script must be named post and can have any file extension (e.g., .ts, .js, .sh). Example:

   import {
     Prisma,
     PrismaClient,
   } from "prisma-data-migrations/migrations/20250108201031_add_user_name";
   
   async function nameUsers(prisma: Prisma.TransactionClient) {
     await prisma.user.updateMany({
       data: {
         name: "Name for users :)",
       },
     });
   }
   
   const prisma = new PrismaClient();
   prisma.$transaction(nameUsers, { timeout: 60_000 });

   ⚠️ Important ⚠️

   • Always wrap your logic in a transaction to ensure atomic operations.
   • If the post script fails, you must manually reapply it after resolving the issue.
   • To simplify manual reapplication you can use the run:postscript command.

   After completing this step, your directory structure should look like this:

   project-root/
   ├── prisma/
   │   ├── migrations/
   │       ├── 20250108201031_add_user_name/
   │           ├── migration.sql
   │           ├── schema.prisma
   │           └── post.ts
   ├── prisma-dm.config.json
   

6. Run Migration: Execute the migration and post-migration script using:

   npx prisma-dm migrate

   (by default, it migrates to latest)

   ⚠️ Note: You can use the --to flag to migrate to a specific migration version (not including the migration passed). Example:

   npx prisma-dm migrate --to 20250108201031_add_user_name

   ⚠️ Note: You can use the --upto flag to migrate to a specific migration version (including the one passed). Example:

   npx prisma-dm migrate --upto 20250108201031_add_user_name

7. Reapplying Failed Post Scripts (If migration fails):

   • If a migration fails due to an error in the post script, you need to manually fix the issue and reapply the post script.
   • To reapply a specific post script, use the run:postscript command with the -m flag, specifying the migration folder name:

   npx prisma-dm run:postscript -m 20250108201031_add_user_name

   This ensures that only the failed post script is executed after addressing the issue without reverting the already applied schema migration.

The configuration file (prisma-dm.config.json) allows customization of the library. Key fields include:

• execScriptCommand: Specifies the command to execute the post-migration script. Include the placeholder ${post} for the script name. Example:

  • For .ts scripts: "tsx ${post}.ts"
  • For shell scripts: "sh ${post}.sh"

• outputDir: Directory for generated migration files.

  • Default: ../../../node_modules/prisma-data-migrations/migrations.
  • Note: This path is specified relative to the migrations/{some_migration}/schema.prisma file, as it is the value of the output parameter in the Prisma schema settings block.

• migrationsDir: Directory containing Prisma migrations. Default: prisma/migrations.

• tempDir: Temporary directory for moving migration folders during execution. Default: prisma/.temp.

• migrationSchemaFileName: The filename for prisma schema files within migration directories. Default: schema.prisma.

• mainPrismaSchema: The main Prisma schema file or folder for npx prisma migrate deploy command. Default: prisma/schema.prisma.

• log: Logging level (none, info, verbose). Default: info.

The library includes built-in support for the following databases. Only PostgreSQL has been fully tested and verified in production-like environments at this time; others are supported by the codebase but have not yet been validated end-to-end.

Community help welcome: if you verify that any of the untested databases work end-to-end with your setup, please open a Pull Request updating this section of the README with the result (include versions and any notes). This helps everyone benefit from broader coverage.

• Post scripts and transactions:

  • Post scripts are not included in the same transaction as schema migrations.
  • If a post script fails, you will need to manually reapply it after resolving the issue.
  • To simplify manual reapplication you can use the run:postscript command.

• Development status:

  • This library is developed and maintained by a single developer and has not been fully tested. Issues may occur.
  • Please report problems or submit feature requests—I am always open to feedback and contributions.

• Database support:

  • Built-in support exists for PostgreSQL, Microsoft SQL Server, MySQL, MariaDB, and SQLite.
  • See the Database Support section for details on testing status.
  • If you successfully validate another database, please open a PR to update the support matrix above and share your findings.
  • Some databases may still require additional logic based on real-world feedback; contributions are welcome.

• Future improvements:

  • Plans to track post scripts in a dedicated database table to improve reliability. Community contributions are highly encouraged.

We welcome contributions! Visit the GitHub Repository to:

• Report issues
• Provide feedback
• Submit pull requests

This project is open-source under the ISC License.