prisma-comment-migration

한국어

A CLI tool that generates migration files to sync Prisma schema /// comments (triple-slash comments) to database TABLE/COLUMN COMMENTs.

Why?

Prisma reflects /// comments in schema files as JSDoc in Prisma Client, but does not sync them to actual database TABLE/COLUMN COMMENTs. This tool bridges that gap.

/// User information table
model User {
  /// Unique user identifier
  id    Int    @id @default(autoincrement())
  /// User email address
  email String @unique
}

From the schema above, this tool generates the following migration SQL:

-- User comments
ALTER TABLE `User` COMMENT = 'User information table';
CALL prisma_update_column_comment('User', 'id', 'Unique user identifier');
CALL prisma_update_column_comment('User', 'email', 'User email address');

Installation

npm install -D @raipen/prisma-comment-migration @prisma/internals

Note: @prisma/internals version should match your prisma version. If you're using prisma 5.x, install @prisma/internals@5.

Usage

Basic

npx prisma-comment-migration
# or
npx pcm

You'll be prompted for a migration name, then a migration file will be created at prisma/migrations/{timestamp}_{name}/migration.sql.

Options

Options:
  -s, --schema <path>         Path to schema.prisma (default: prisma/schema.prisma)
  -l, --latest-comment <path> Path to comment state file (default: prisma/.latest_migration_comment.json)
  -t, --targets <targets>     Comma-separated targets: table,column (default: table,column)
  -e, --include-enum          Include enum values in field comments (default: true)
      --no-include-enum       Do not include enum values in field comments
  -p, --provider <provider>   Database provider: mysql, postgresql (default: mysql)
  -o, --output-dir <path>     Output directory for migrations (default: prisma/migrations)
  -n, --name <name>           Migration name (will prompt if not provided)
  -a, --append                Append to the latest migration file instead of creating new one
  -h, --help                  Show help message

Note: -n and -a cannot be used together.

Examples

# Specify migration name
npx pcm -n "add_user_comments"

# Generate table comments only
npx pcm -t table

# Append to the latest migration file (with confirmation prompt)
npx pcm --append

# Use PostgreSQL
npx pcm -p postgresql

How It Works

1. Parses prisma/schema.prisma to extract /// comments from models and fields
2. Compares with previously saved comment state (.latest_migration_comment.json)
3. Generates migration SQL containing only changed comments
4. Saves current comment state for next comparison

Enum Support

For enum type fields, enum values can be automatically included in comments:

enum Role {
  ADMIN
  USER
  GUEST
}

model User {
  /// User role
  role Role
}

Generated comment: User role\nenum: Role(ADMIN, USER, GUEST)

Use --no-include-enum to disable this feature.

Prisma Version Support

Supports Prisma 4.x ~ 7.x.

| Prisma Version | Status | |----------------|--------| | 4.x | Supported | | 5.x | Supported | | 6.x | Supported | | 7.x | Supported |

Note: Starting from Prisma 7, the url property in datasource has been removed from schema files and moved to prisma.config.ts. This is a Prisma-specific change, and this library works correctly with the new schema format.

Database Support

MySQL (Stable)

• Table comments: ALTER TABLE ... COMMENT
• Column comments: Uses stored procedure that preserves column definition while modifying only the comment

PostgreSQL (Experimental)

Note: PostgreSQL support is experimental. The author does not use PostgreSQL, so it has not been thoroughly tested.

Testing, feedback, and PRs from PostgreSQL users are welcome!

• COMMENT ON TABLE ...
• COMMENT ON COLUMN ...
• Multi-schema support

Workflow

We recommend using --create-only to create the migration file first, then append comments before applying:

# 1. Create Prisma migration file (without applying)
npx prisma migrate dev --name add_user_table --create-only

# 2. Append comment statements to the migration
npx pcm --append

# 3. Apply the migration
npx prisma migrate dev

Or create comments as a separate migration:

# 1. Apply schema changes first
npx prisma migrate dev --name add_user_table

# 2. Create comment migration
npx pcm -n "add_user_comments"

# 3. Apply comment migration
npx prisma migrate dev

Files

• prisma/.latest_migration_comment.json: Stores the last generated comment state. Commit this file to git. It's needed for tracking comment changes across team members.

License

MIT

Contributing

Issues and PRs are welcome! We especially look forward to contributions in these areas:

• PostgreSQL testing and bug reports
• Support for other databases (SQLite, SQL Server, etc.)
• Test code