82 lines
2.6 KiB
Markdown
82 lines
2.6 KiB
Markdown
# Database Migrations
|
|
|
|
This directory contains SQL migration scripts for schema changes.
|
|
|
|
## Naming Convention
|
|
|
|
```
|
|
V{YYYYMMDD}_{NNN}__{description}.sql # UP migration
|
|
V{YYYYMMDD}_{NNN}__{description}_DOWN.sql # DOWN migration (rollback)
|
|
```
|
|
|
|
Example:
|
|
- `V20260120_001__migrate_auth_sessions_structure.sql`
|
|
- `V20260120_001__migrate_auth_sessions_structure_DOWN.sql`
|
|
|
|
## Migration Order
|
|
|
|
Migrations should be applied in order by version number:
|
|
|
|
1. `V20260120_001` - auth.sessions structure changes
|
|
2. `V20260120_002` - billing.subscriptions structure changes
|
|
3. `V20260120_003` - audit.audit_logs structure changes
|
|
|
|
## Running Migrations
|
|
|
|
### Apply UP migration
|
|
```bash
|
|
psql -h localhost -U postgres -d template_saas -f migrations/V20260120_001__migrate_auth_sessions_structure.sql
|
|
```
|
|
|
|
### Apply DOWN migration (rollback)
|
|
```bash
|
|
psql -h localhost -U postgres -d template_saas -f migrations/V20260120_001__migrate_auth_sessions_structure_DOWN.sql
|
|
```
|
|
|
|
## Migration Details
|
|
|
|
### V20260120_001 - Auth Sessions
|
|
|
|
**Changes:**
|
|
- Renames `session_token` -> `token_hash` (VARCHAR(64) -> VARCHAR(255))
|
|
- Converts `is_active` (BOOLEAN) -> `status` (ENUM: active, expired, revoked)
|
|
- Adds `device_name`, `browser`, `os`, `location` columns
|
|
- Adds `revoked_at`, `revoked_reason` columns
|
|
- Updates cleanup function to use status
|
|
|
|
### V20260120_002 - Billing Subscriptions
|
|
|
|
**Changes:**
|
|
- Adds Stripe integration columns (`stripe_subscription_id`, `stripe_customer_id`)
|
|
- Adds billing `interval` column (ENUM: month, year)
|
|
- Adds trial/cancellation columns (`trial_start`, `cancel_at`, `cancel_reason`)
|
|
- Adds pricing columns (`price_amount`, `currency`)
|
|
- Renames `cancelled_at` -> `canceled_at` (American spelling)
|
|
- Updates subscription_status enum: `trial` -> `trialing`
|
|
|
|
### V20260120_003 - Audit Logs
|
|
|
|
**Changes:**
|
|
- Renames `entity_type` -> `resource_type`
|
|
- Renames `entity_id` -> `resource_id`
|
|
- Adds actor columns (`user_email`, `actor_type`)
|
|
- Adds `resource_name`, `severity` columns
|
|
- Adds context columns (`request_id`, `session_id`)
|
|
- Adds HTTP columns (`endpoint`, `http_method`, `response_status`, `duration_ms`)
|
|
- Splits `changes` JSONB -> `old_values`, `new_values`, `changed_fields`
|
|
- Updates `audit.log_event()` function
|
|
|
|
## Safety Notes
|
|
|
|
1. **Always backup before migrating**
|
|
2. **Run in transaction** - All migrations use BEGIN/COMMIT
|
|
3. **Test on staging first**
|
|
4. **Idempotent checks** - Migrations check if changes already exist
|
|
5. **DOWN migrations may lose data** - VARCHAR truncation, column drops
|
|
|
|
## Related Files
|
|
|
|
- DDL definitions: `../ddl/schemas/`
|
|
- Enum definitions: `../ddl/02-enums.sql`
|
|
- Functions: `../ddl/03-functions.sql`
|