Good

---

title: Schema Changes and Migrations impact: HIGH impactDescription: Prevents data loss and ensures smooth deployments tags: prisma, migrations, schema, database

Паспорт документа

• Статус документа: living standard
• Актуально на: 28 марта 2026 года
• Владелец: backend/platform-команда
• Пересмотр: при изменении инженерной практики, CI/CD, архитектурных правил или локального workflow
• Область применения: внутренние rule/reference-card документы для инженерной команды
• Связанные документы:
  • Индекс Agents
  • Команды разработки
  • Инженерные принципы

Schema Changes and Migrations

Impact: HIGH

Workflow

1. Edit apps/api/prisma/schema.prisma
2. Run pnpm --filter=api prisma migrate dev --name descriptive_name
3. Run pnpm --filter=api prisma generate to update the client
4. Verify the generated migration SQL is correct
5. Test with existing data

Naming Convention

Migration names should be descriptive and use snake_case:

# Good
pnpm --filter=api prisma migrate dev --name add_review_response_field
pnpm --filter=api prisma migrate dev --name create_notification_table
pnpm --filter=api prisma migrate dev --name add_index_on_item_slug

# Bad
pnpm --filter=api prisma migrate dev --name update
pnpm --filter=api prisma migrate dev --name fix

Rules

• Never edit migration files after they've been committed
• Never use prisma db push in production — always use migrations
• Always review generated SQL before committing
• Always add indexes for columns used in WHERE, ORDER BY, or JOIN clauses
• Always make migrations backwards-compatible (additive, not destructive)
• Always provide default values for new required columns or make them nullable first

Destructive Changes

For destructive changes (dropping columns, renaming tables), use a two-step approach:

1. PR 1: Add the new column/table, deploy, migrate data
2. PR 2: Remove the old column/table after all references are updated