veza/docs/MIGRATIONS.md

# Database Migrations

## Overview

Veza uses SQL migrations stored in `veza-backend-api/migrations/`. Migrations are applied in order by filename (lexicographic sort).

## Migration Naming

- Format: `NNN_description.sql` (e.g. `101_product_reviews.sql`)
- Use snake_case for descriptions
- Down migrations (rollback): `NNN_description_down.sql` when needed

## Squash Script

The `scripts/squash_migrations.sh` script generates a baseline SQL file that concatenates all migrations into a single file. This is useful for:

- Fresh database setup
- Creating a clean baseline for new environments
- Versioned releases (e.g. `baseline_v0601.sql`)

### Usage

```bash
# From project root
./scripts/squash_migrations.sh
```

Output: `veza-backend-api/migrations/baseline_v0601.sql`

### Procedure

1. Run the script after adding new migrations
2. Update the version in the script (e.g. `baseline_v0601.sql`) for each release
3. Update the migration range comment (e.g. `001-113`) to reflect the latest migration number
4. The baseline file is auto-generated; do not edit it manually

## Recent Migrations

| # | File | Description |
|---|------|-------------|
| 116 | `116_seller_transfers_retry.sql` | v0.701: Add `retry_count`, `next_retry_at` to `seller_transfers`; index for failed retries |

## Adding New Migrations

1. Create a new file: `veza-backend-api/migrations/NNN_description.sql`
2. Use the next available number (check existing migrations)
3. Write idempotent SQL when possible (e.g. `IF NOT EXISTS`)
4. Test locally before committing
5. Run `squash_migrations.sh` to update the baseline for the release