---
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](../README.md)
  - [Команды разработки](../commands.md)
  - [Инженерные принципы](../../governance/engineering-principles.md)

## 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:

```bash
# 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