<?php

declare(strict_types=1);

namespace App\Framework\Database\Migration;

use App\Framework\Database\ConnectionInterface;

/**
 * Interface for migrations that support safe rollback operations
 *
 * ONLY implement this interface if the migration can be rolled back WITHOUT data loss.
 *
 * ✅ Safe to implement SafelyReversible:
 * - Adding nullable columns (can be dropped without data loss)
 * - Creating/dropping indexes (no data affected)
 * - Renaming columns/tables (data preserved during rename)
 * - Adding constraints (can be removed cleanly)
 * - Creating empty tables (no data to lose)
 * - Adding foreign keys (can be removed)
 *
 * ❌ DO NOT implement SafelyReversible when:
 * - Dropping columns with existing data
 * - Transforming data formats (original format lost)
 * - Merging/splitting tables with data
 * - Changing column types with potential data loss
 * - Any operation where information cannot be restored
 *
 * For unsafe changes, use fix-forward migrations instead of rollback.
 *
 * @see Migration Base migration interface (forward-only)
 */
interface SafelyReversible
{
    /**
     * Rollback this migration safely (no data loss)
     *
     * This method should reverse the changes made in up() method.
     * It will only be called if the migration explicitly implements this interface.
     *
     * IMPORTANT: Only implement this if you are certain no data will be lost.
     *
     * @param ConnectionInterface $connection Database connection
     * @throws \Throwable If rollback fails
     */
    public function down(ConnectionInterface $connection): void;
}
