Database Migrations Guide¶

RawDigs uses multiple databases with separate migration paths for better organization and safety.

Database Architecture¶

┌─────────────────────────────────────────────────────────┐
│                     RawDigs Stack                        │
├─────────────────────────────────────────────────────────┤
│                                                          │
│  📦 PostgreSQL (Port 5432)                              │
│     └─ Main application data                            │
│        ├─ Users, Tracks, Playlists                      │
│        ├─ Comments, Likes, Follows                      │
│        └─ All business logic tables                     │
│                                                          │
│  📊 MySQL Monitoring (Port 3307)                        │
│     └─ Monitoring & debugging data                      │
│        ├─ Laravel Telescope entries                     │
│        └─ Laravel Pulse metrics                         │
│                                                          │
└─────────────────────────────────────────────────────────┘

Migration Folders¶

database/
├── migrations/              # PostgreSQL - Main App
│   ├── 2024_01_01_create_users_table.php
│   ├── 2024_01_02_create_tracks_table.php
│   └── ...
│
└── migrations-monitoring/   # MySQL - Telescope & Pulse
    ├── 2025_10_17_create_telescope_entries_table.php
    └── 2025_10_17_create_pulse_tables.php

Available Commands¶

Run All Migrations (Recommended)¶

sail artisan migrate:all

This runs migrations for both databases in the correct order.

Run Main App Migrations Only¶

# Option 1: Standard Laravel command
sail artisan migrate

# Option 2: Explicit command
sail artisan migrate:app

Run Monitoring Migrations Only¶

sail artisan migrate:monitoring

Fresh Migrations (Drop All Tables)¶

# All databases
sail artisan migrate:all --fresh

# Main app only
sail artisan migrate:app --fresh

# Monitoring only
sail artisan migrate:monitoring --fresh

With Seeding¶

# All databases with seeding
sail artisan migrate:all --fresh --seed

# Main app with seeding
sail artisan migrate:app --fresh --seed

Creating New Migrations¶

For Main App (PostgreSQL)¶

sail artisan make:migration create_tracks_table

This creates the migration in database/migrations/ and will run on PostgreSQL.

For Monitoring (MySQL)¶

sail artisan make:migration create_custom_monitoring_table

Then manually move the file to database/migrations-monitoring/:

mv database/migrations/*_create_custom_monitoring_table.php database/migrations-monitoring/

Migration Status¶

Check Main App Migrations¶

sail artisan migrate:status

Check Monitoring Migrations¶

sail artisan migrate:status --database=mysql_monitoring --path=database/migrations-monitoring

Rollback¶

Main App¶

sail artisan migrate:rollback

Monitoring¶

sail artisan migrate:rollback --database=mysql_monitoring --path=database/migrations-monitoring

Common Workflows¶

Initial Setup (First Time)¶

# Start containers
sail up -d

# Run all migrations
sail artisan migrate:all

# Seed data (optional)
sail artisan db:seed

After Pulling New Code¶

# Check for new migrations
sail artisan migrate:all

Reset Everything¶

# Drop all tables and re-migrate
sail artisan migrate:all --fresh

# With seeding
sail artisan migrate:all --fresh --seed

Production Deployment¶

# Always use --force in production
sail artisan migrate:all --force

Troubleshooting¶

Migration Hanging¶

If a migration hangs, check database connectivity:

# PostgreSQL
sail artisan db:show

# MySQL Monitoring
sail artisan db:show --database=mysql_monitoring

Connection Refused¶

Check if containers are running:

sail ps

Start if needed:

sail up -d pgsql mysql_monitoring

Wrong Database¶

If migrations run on the wrong database:

Check .env file:

DB_CONNECTION=pgsql  # Main app should use pgsql

Verify config/database.php connections

Use explicit commands:

sail artisan migrate:app          # PostgreSQL
sail artisan migrate:monitoring   # MySQL

Migration Already Exists¶

If you get "migration already exists" error:

# Check what's already migrated
sail artisan migrate:status

# If needed, rollback
sail artisan migrate:rollback

# Or fresh start
sail artisan migrate:all --fresh

Best Practices¶

Always use migrate:all for full stack migrations
Never manually run migrations on wrong database
Keep monitoring migrations separate - they're vendor-specific
Test migrations locally before deploying
Backup production before running migrations
Use transactions in migrations when possible

CI/CD Integration¶

GitHub Actions Example¶

- name: Run migrations
  run: |
    php artisan migrate:all --force

Deployment Script¶

#!/bin/bash
set -e

echo "Running database migrations..."

# Main app
php artisan migrate:app --force

# Monitoring
php artisan migrate:monitoring --force

echo "Migrations completed!"

Database Seeding¶

Seed Main App¶

sail artisan db:seed

Seed Specific Seeder¶

sail artisan db:seed --class=UserSeeder

Fresh with Seeding¶

sail artisan migrate:all --fresh --seed

Monitoring Tools Access¶

After running monitoring migrations:

Telescope: http://rawdigs.local/telescope
Pulse: http://rawdigs.local/pulse

Additional Resources¶

Need help? Check the logs:

sail artisan migrate:all --verbose