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

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

npm run migrate:make add-new-feature

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

Example migration structure:

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