rspade_system/docs/skills/migrations/SKILL.md

name, description

name	description
migrations	RSX database migrations with raw SQL enforcement, forward-only philosophy, and automatic normalization. Use when creating database tables, understanding migration workflow, or troubleshooting Schema builder violations.

RSX Database Migrations

Philosophy

RSX enforces a forward-only migration strategy with raw SQL:

1. Forward-only - No rollbacks, no down() methods
2. Raw SQL only - Direct MySQL statements, no Schema builder
3. Fail loud - Migrations must succeed or fail with clear errors
4. Snapshot safety - Development requires database snapshots

---

Schema Builder is Prohibited

All migrations must use DB::statement() with raw SQL:

// ✅ CORRECT
DB::statement("CREATE TABLE products (
    id BIGINT NOT NULL AUTO_INCREMENT PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    price DECIMAL(10,2) NOT NULL DEFAULT 0.00
)");

// ❌ WRONG - Schema builder prohibited
Schema::create('products', function (Blueprint $table) {
    $table->id();
    $table->string('name');
});

Prohibited: Schema::create(), Schema::table(), Schema::drop(), Blueprint, $table-> chains

---

Development Workflow

# 1. Create migration
php artisan make:migration:safe create_products_table

# 2. Write migration with raw SQL

# 3. Run migrations (auto-snapshot in development)
php artisan migrate

In development mode, migrate automatically:

• Creates database snapshot before running
• Commits on success (regenerates constants, recompiles bundles)
• Auto-rollbacks on failure (database restored to pre-migration state)

---

Automatic Normalization

The system auto-normalizes types after migration. You can write simpler SQL:

You Write	System Converts To
INT	BIGINT
TEXT	LONGTEXT
FLOAT	DOUBLE
TINYINT(1)	Preserved (boolean)

Auto-added columns (don't include manually):

• created_at TIMESTAMP(3)
• updated_at TIMESTAMP(3)
• created_by BIGINT
• updated_by BIGINT

---

Migration Examples

Simple Table (Recommended)

public function up()
{
    DB::statement("
        CREATE TABLE products (
            id INT NOT NULL AUTO_INCREMENT PRIMARY KEY,
            name VARCHAR(255) NOT NULL,
            description TEXT,
            price DECIMAL(10,2) NOT NULL DEFAULT 0.00,
            stock_quantity INT NOT NULL DEFAULT 0,
            is_active TINYINT(1) NOT NULL DEFAULT 1,
            category_id INT NULL,
            INDEX idx_category (category_id),
            INDEX idx_active (is_active)
        )
    ");
}

Notes:

• INT becomes BIGINT automatically
• TEXT becomes LONGTEXT automatically
• created_at/updated_at added automatically
• TINYINT(1) preserved for booleans

Adding Columns

public function up()
{
    DB::statement("
        ALTER TABLE products
        ADD COLUMN sku VARCHAR(50) NULL AFTER name,
        ADD COLUMN weight DECIMAL(8,2) NULL,
        ADD INDEX idx_sku (sku)
    ");
}

Foreign Keys

public function up()
{
    DB::statement("
        ALTER TABLE orders
        ADD CONSTRAINT fk_orders_customer
        FOREIGN KEY (customer_id) REFERENCES customers(id)
        ON DELETE CASCADE
    ");
}

---

Required Table Structure

Every table MUST have:

id BIGINT NOT NULL AUTO_INCREMENT PRIMARY KEY

This is non-negotiable. Use SIGNED (not UNSIGNED) for easier future migrations.

---

Foreign Key Columns

Foreign key columns must match the referenced column type exactly:

-- If users.id is BIGINT, then:
user_id BIGINT NULL  -- ✅ Matches

-- Column names ending in _id are assumed to be foreign keys

---

Debug/Production Workflow

# In debug or production mode (RSX_MODE=debug or production)
php artisan migrate

In debug/production mode:

• No snapshot protection (source code is read-only)
• Schema normalization still runs
• Constants and bundles NOT regenerated

Ensure migrations are thoroughly tested in development first.

---

Validation

The migration validator automatically checks for:

• Schema builder usage
• down() methods (auto-removed)
• Proper SQL syntax

Violations show clear error messages with remediation advice.

---

Troubleshooting

Error	Solution
"Found forbidden Schema builder usage"	Replace with DB::statement()
"Validation failed"	Check migration for prohibited patterns
Foreign key constraint fails	Ensure column types match exactly

More Information

Details: php artisan rsx:man migrations