sqlite 不支持直接修改主键或删除列，laravel 迁移需通过临时表重建实现结构变更，本文提供可复用的封装方案与生产级实践指南。
sqlite 不支持直接修改主键或删除列，laravel 迁移需通过临时表重建实现结构变更，本文提供可复用的封装方案与生产级实践指南。
SQLite 的 ALTER TABLE 命令能力极为有限：仅允许重命名表（RENAME TO）或向表末尾添加新列（ADD COLUMN），完全不支持删除列、修改列类型、调整列顺序、更改主键定义或添加外键约束。当业务需要将 UUID 主键替换为自增 id 字段（如题中 items 表场景），或需删除冗余字段、变更主键约束时，唯一合规路径是——原子化重建表结构。
该过程本质是“数据迁移式重构”：
- 创建结构正确的新临时表；
- 将原表数据按新结构映射导入；
- 安全删除旧表；
- 将临时表重命名为原表名；
- 全程包裹在事务中确保数据一致性。
✅ 推荐方案：封装可复用的 SQLite 表重建迁移类
手动重复编写 CREATE TEMP TABLE → INSERT SELECT → DROP → RENAME 易出错且违反 DRY 原则。以下是一个生产就绪的 Laravel 扩展迁移基类，基于 Doctrine DBAL Schema Manager 实现自动化重建：
<?php use Doctrine\DBAL\Schema\Table;
use Illuminate\Database\Migrations\Migration;
use Illuminate\Support\Facades\DB;
class ExtendedSQLiteAlterTableMigration extends Migration
{
/**
* 对 SQLite 表执行结构重建式变更（支持主键修改、列删改等）
*
* @param string $tableName 表名
* @param callable $callback 接收 Doctrine Table 对象，用于定义新结构
* @return void
*/
public function extendedAlterTable(string $tableName, callable $callback): void
{
$connection = DB::connection();
$schemaManager = $connection->getDoctrineSchemaManager();
// 获取原表元信息（列、索引、外键）
$columns = $schemaManager->listTableColumns($tableName);
$indexes = $schemaManager->listTableIndexes($tableName);
$foreignKeys = $schemaManager->listTableForeignKeys($tableName);
// 创建临时表对象（名称加前缀避免冲突）
$tempTableName = 'temp_' . $tableName;
$tempTable = new Table($tempTableName, $columns, $indexes, [], $foreignKeys);
// 应用用户定义的结构变更
call_user_func($callback, $tempTable);
// 执行重建四步曲（事务保障）
$connection->transaction(function () use ($schemaManager, $tableName, $tempTable, $tempTableName) {
$schemaManager->createTable($tempTable); // ① 创建新结构临时表
// ② 数据迁移（自动映射同名列，注意：需确保列名兼容性）
$columnsToSelect = collect($tempTable->getColumns())
->map(fn($col) => $col->getName())
->implode(', ');
DB::statement("INSERT INTO {$tempTableName} ({$columnsToSelect}) SELECT {$columnsToSelect} FROM {$tableName}");
$schemaManager->dropTable($tableName); // ③ 删除旧表
$schemaManager->renameTable($tempTableName, $tableName); // ④ 重命名回原表名
});
}
}
? 使用示例：将 UUID 主键替换为自增 ID
继承上述基类，编写具体迁移：
<?php use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;
class AddAutoIncrementPrimaryKeyToItemsTable extends ExtendedSQLiteAlterTableMigration
{
public function up(): void
{
$this->extendedAlterTable('items', function (Table $table) {
// 移除原主键约束
$table->dropPrimaryKey();
// 添加新的自增 bigint 主键列（注意：SQLite 中 autoincrement 需配合 PRIMARY KEY）
$table->addColumn('id', 'bigint', [
'autoincrement' => true,
'notnull' => true,
]);
// 设置新主键
$table->setPrimaryKey(['id']);
// 可选：重命名原 uuid 字段（保留业务标识）
// $table->changeColumn('id', ['name' => 'uuid']);
});
}
public function down(): void
{
// 回滚逻辑需对称实现（例如还原为 uuid 主键）
$this->extendedAlterTable('items', function (Table $table) {
$table->dropPrimaryKey();
$table->dropColumn('id');
$table->addColumn('id', 'string', ['length' => 36, 'notnull' => true]);
$table->setPrimaryKey(['id']);
});
}
}
⚠️ 关键注意事项与最佳实践
- 事务必须启用：SQLite 的 DROP TABLE 和 CREATE TABLE 操作不可回滚，务必用 $connection->transaction() 包裹全部步骤，避免中间失败导致数据丢失。
- 列名映射需谨慎：INSERT SELECT 依赖列名严格匹配。若需重命名字段（如 id → system_id），应在 addColumn() 后显式 changeColumn() 或在 INSERT 语句中指定别名。
- 外键与索引会丢失：Doctrine listTableForeignKeys() 虽能读取，但 createTable() 不自动重建外键。如需保留，须在 $callback 中手动调用 $table->addForeignKeyConstraint(...)。
- Laravel 原生迁移不适用：$table->dropPrimary() 或 $table->id() 在 SQLite 中会静默失败或抛出异常，切勿在 Schema::table() 中尝试。
- 生产环境慎用：大表重建可能锁表较久。建议在低峰期执行，并提前备份；对超大数据量，考虑分批次迁移或应用层双写过渡。
- 替代方案评估：若项目允许引入第三方工具，sqlite-utils CLI 提供 sqlite-utils transform 命令可简化操作，但需额外部署依赖，不如纯 PHP 方案可控。
? 总结：SQLite 的结构限制是设计使然，而非缺陷。拥抱“重建即变更”的范式，配合封装良好的迁移基类，即可在 Laravel 生态中安全、可维护地演进 SQLite 表结构。记住——每一次主键变更，都是对数据契约的一次郑重升级。
