prisma-data-migrations

v1.6.0

Published

3 months ago

Enhances Prisma ORM with support for post-migration data scripts.

0High
0Medium
0Low

softjey

prisma data-migrations orm typescript database schema-migrations

Prisma Data Migrations

Overview

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.

Installation

Install the library via npm:

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

Usage

Commands

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

Quick Start

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.
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.
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.
Generate Types: Run the generate command to create TypeScript types for your data migrations based on your schemas:
```
npx prisma-dm generate
```

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

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
```
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.

Configuration

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.

Database Support

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.

| Database | Supported | Tested & 100% working | | -------------------- | :-------: | :-------------------: | | PostgreSQL | ✅ | ✅ Fully tested | | Microsoft SQL Server | ✅ | ⛔ Not tested yet | | MySQL | ✅ | ⛔ Not tested yet | | MariaDB | ✅ | ⛔ Not tested yet | | SQLite | ✅ | ⛔ Not tested yet |

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.

Warnings and Considerations

⚠️ Key Warnings ⚠️

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.

Contributing

We welcome contributions! Visit the GitHub Repository to:

Report issues
Provide feedback
Submit pull requests

License

This project is open-source under the ISC License.