saasshop/docs/DB_SQL_MIGRATIONS.md

SaaSShop 数据库结构迁移（SQL 版）

目标：数据库结构变更以 SQL 脚本形式版本化，便于在新环境 / CI（Gitee Go）自动执行。

约束：只推结构变更，不推业务数据。

目录与命名

• 脚本目录：database/migrations/
• 命名规则：V{数字}__{描述}.sql
  • 示例：V2__add_platform_order_indexes.sql
  • 数字必须递增（V1、V2、V3...）

执行方式

1）Laravel 原生迁移

首次初始化仍执行 Laravel migration（PHP 迁移），用于建立基础表：

php artisan migrate --force

2）SQL 脚本迁移

执行 SQL 结构迁移：

composer run db:sql-migrate
# 或
php scripts/sql_migrate.php

该命令会：

• 扫描 database/migrations/V*__*.sql
• 按版本号升序执行
• 执行成功后写入记录表 schema_sql_migrations

记录表

• 表名：schema_sql_migrations
• 字段：
  • version：如 V1 / V2
  • description：从文件名解析
  • applied_at：执行时间

编写脚本建议

• 仅结构变更：CREATE/ALTER/DROP/INDEX 等
• 不写 INSERT/UPDATE 业务数据（除非是结构初始化必要数据，且要评估影响）
• 每个脚本尽量“可重复执行”或在脚本内加存在性判断（视具体 DB 方言支持）

新环境落地步骤（推荐）

git clone <repo>
cd saasshop
composer install
cp .env.example .env
php artisan key:generate
php artisan migrate --force
composer run db:sql-migrate
php artisan test

CI（Gitee Go）

仓库内提供 .gitee/go.yml 模板，需在 Gitee Go 中配置数据库连接与环境变量后启用。