Linux环境下Laravel数据库迁移指南

Linux环境下 Laravel 数据库迁移指南

一 环境准备与项目初始化

• 检查依赖：确保已安装 PHP 与 Composer，在项目根目录执行 php -v、composer --version 验证版本。
• 创建项目：
  • 使用 Composer 全局安装 Laravel 安装器：composer global require laravel/installer
  • 新建项目：laravel new your_project_name 或 composer create-project --prefer-dist laravel/laravel your_project_name
• 进入项目：cd your_project_name
• 配置数据库：编辑 .env，设置 DB_CONNECTION、DB_HOST、DB_PORT、DB_DATABASE、DB_USERNAME、DB_PASSWORD 等连接参数，确保数据库已创建且用户具备相应权限。

二 迁移全流程与常用命令

• 生成迁移文件：
  • 新建表：php artisan make:migration create_users_table --create=users
  • 修改表：php artisan make:migration add_votes_to_users_table --table=users
• 编辑迁移：在生成的文件 database/migrations/xxxx_create_xxx_table.php 的 up() 中定义结构，down() 中编写回滚逻辑（成对可逆）。
• 执行迁移：php artisan migrate（按时间戳顺序执行未运行迁移，并在数据库中维护 migrations 表记录）。
• 回滚与重置：
  • 回滚上一批：php artisan migrate:rollback
  • 回滚指定步数：php artisan migrate:rollback --step=N
  • 全部回滚：php artisan migrate:reset
  • 刷新（回滚并重新运行全部）：php artisan migrate:refresh（开发环境常用，生产慎用）
• 数据填充：
  • 生成种子：php artisan make:seeder UsersTableSeeder
  • 运行种子：php artisan db:seed --class=UsersTableSeeder 或全量 php artisan db:seed

三 常见迁移操作示例

• 创建表（示例 users）：
  • php artisan make:migration create_users_table --create=users
  • 在 up() 中使用 Schema::create('users', function (Blueprint $table) { ... })，常见字段：$table->id(); $table->string('name'); $table->string('email')->unique(); $table->timestamp('email_verified_at')->nullable(); $table->string('password'); $table->rememberToken(); $table->timestamps();
  • 在 down() 中 Schema::dropIfExists('users');
• 修改表（添加列）：
  • php artisan make:migration add_phone_to_users_table --table=users
  • Schema::table('users', function (Blueprint $table) { $table->string('phone')->nullable(); $table->after('email'); });
• 修改列类型/长度（需 Doctrine DBAL）：
  • 安装：composer require doctrine/dbal
  • Schema::table('users', function (Blueprint $table) { $table->string('name', 100)->change(); $table->text('bio')->nullable()->change(); });
• 重命名列/表：
  • Schema::rename('old_table', 'new_table');
  • Schema::table('users', function (Blueprint $table) { $table->renameColumn('old_name', 'new_name'); });
• 索引与外键：
  • 索引：$table->index('user_id'); $table->unique('slug'); $table->fullText('content');
  • 外键：$table->foreignId('user_id')->constrained()->onDelete('cascade');
  • 删除：$table->dropIndex(['user_id']); $table->dropUnique(['slug']); $table->dropForeign(['user_id']);
• 原生 SQL：
  • DB::statement('ALTER TABLE users ADD COLUMN points INT DEFAULT 0;');（在 down() 中编写对应回滚语句）

四 生产环境注意事项与故障排查

• 安全与确认：生产环境执行破坏性迁移前会进行确认；如需强制执行，可使用相应命令的 –force 选项（务必在备份与维护窗口内操作）。
• 数据保护：避免使用 migrate:refresh、migrate:reset 等会丢失数据的命令；上线前在预备环境演练，并做好 全量备份。
• 协作规范：不要修改已提交并推送到远程的迁移文件；如需变更，新增迁移文件修正结构，保持迁移链可回滚。
• 常见问题速查：
  • 表已存在：检查是否重复执行迁移或忘记在 down() 中回滚；必要时手动清理或新建修正迁移。
  • 列不存在/类型不匹配：确认迁移顺序、字段名拼写与变更是否成对可逆。
  • 外键约束失败：检查被引用表与列是否存在、字段类型是否一致、删除/更新策略是否合理。
  • 修改列失败：确认已安装 doctrine/dbal，否则无法变更列类型/长度。
  • 权限问题：确保数据库用户具备 CREATE、ALTER、DROP、INDEX 等必要权限。