link-stack/apps/bridge-migrations/README.md

# Bridge Migrations

Database migration management for the CDR Link bridge system.

## Overview

Bridge Migrations handles database schema versioning and migrations for all bridge-related tables using Kysely migration framework. It manages the database structure for authentication, messaging channels, webhooks, and settings.

## Features

- **Schema Versioning**: Track and apply database schema changes
- **Up/Down Migrations**: Support for rolling forward and backward
- **Type-Safe Migrations**: TypeScript-based migration files
- **Migration History**: Track applied migrations in the database
- **Multiple Migration Strategies**: Run all, run one, or rollback migrations

## Migration Files

Current migrations in order:

1. **0001-add-next-auth.ts** - NextAuth.js authentication tables
2. **0002-add-signal.ts** - Signal messenger integration
3. **0003-add-whatsapp.ts** - WhatsApp integration
4. **0004-add-voice.ts** - Voice/Twilio integration
5. **0005-add-facebook.ts** - Facebook Messenger integration
6. **0006-add-webhooks.ts** - Webhook configuration
7. **0007-add-settings.ts** - Application settings
8. **0008-add-user-role.ts** - User role management

## Development

### Prerequisites

- Node.js >= 20
- npm >= 10
- PostgreSQL database
- Database connection credentials

### Setup

```bash
# Install dependencies
npm install

# Run all pending migrations
npm run migrate:latest

# Check migration status
npm run migrate:list
```

### Environment Variables

Required environment variables:

- `DATABASE_URL` - PostgreSQL connection string
- `DATABASE_HOST` - Database host
- `DATABASE_NAME` - Database name
- `DATABASE_USER` - Database username
- `DATABASE_PASSWORD` - Database password

### Available Scripts

- `npm run migrate:latest` - Run all pending migrations
- `npm run migrate:up` - Run next pending migration
- `npm run migrate:down` - Rollback last migration
- `npm run migrate:up:all` - Run all migrations (alias)
- `npm run migrate:up:one` - Run one migration
- `npm run migrate:down:all` - Rollback all migrations
- `npm run migrate:down:one` - Rollback one migration
- `npm run migrate:list` - List migration status
- `npm run migrate:make <name>` - Create new migration file

## Creating New Migrations

To create a new migration:

```bash
npm run migrate:make add-new-feature
```

This creates a new timestamped migration file in the `migrations/` directory.

Example migration structure:

```typescript
import { Kysely } from 'kysely'

export async function up(db: Kysely<any>): Promise<void> {
  await db.schema
    .createTable('new_table')
    .addColumn('id', 'serial', (col) => col.primaryKey())
    .addColumn('name', 'varchar', (col) => col.notNull())
    .addColumn('created_at', 'timestamp', (col) =>
      col.defaultTo('now()').notNull()
    )
    .execute()
}

export async function down(db: Kysely<any>): Promise<void> {
  await db.schema.dropTable('new_table').execute()
}
```

## Database Schema

### Core Tables

- **users** - User accounts with roles
- **accounts** - OAuth account connections
- **sessions** - User sessions
- **verification_tokens** - Email verification

### Communication Tables

- **bots** - Bot configurations for each service
- **signal_messages** - Signal message history
- **whatsapp_messages** - WhatsApp message history
- **voice_messages** - Voice/call records
- **facebook_messages** - Facebook message history

### Configuration Tables

- **webhooks** - External webhook endpoints
- **settings** - Application settings

## Best Practices

1. **Test Migrations**: Always test migrations in development first
2. **Backup Database**: Create backups before running migrations in production
3. **Review Changes**: Review migration files before applying
4. **Atomic Operations**: Keep migrations focused and atomic
5. **Rollback Plan**: Ensure down() methods properly reverse changes

## Troubleshooting

### Common Issues

1. **Migration Failed**: Check error logs and database permissions
2. **Locked Migrations**: Check for concurrent migration processes
3. **Missing Tables**: Ensure all previous migrations have run
4. **Connection Issues**: Verify DATABASE_URL and network access

### Recovery

If migrations fail:

1. Check migration history table
2. Manually verify database state
3. Run specific migrations as needed
4. Use rollback if necessary

## Integration

Migrations are used by:
- **bridge-frontend** - Requires migrated schema
- **bridge-worker** - Depends on message tables
- **bridge-whatsapp** - Uses bot configuration tables