# 7.6 数据库迁移工具

:::tip 概述
`db:migrate` 是一个 CLI 命令行工具，支持在 MySQL / PostgreSQL / SQL Server / Oracle / SQLite 五种数据库之间任意组合迁移。完整迁移流程包含自动建库、建表结构（含索引、外键、注释、自增、collation）、分批迁移数据、重置自增序列、逐表行数校验 5 个步骤。数据迁移基于主键稳定排序，支持事务保护与自动回滚。目标库不存在时自动创建，支持含点号的数据库名。
:::

## 迁移流程

```text
┌──────────────────────────────────────────────────────────────┐
│                   数据库迁移 5 步流程                         │
└──────────────────────────────────────────────────────────────┘

[1/5] 建目标库
│  目标库不存在时自动创建（所有驱动均支持）
│  自动从源库读取 collation 并应用（仅源与目标驱动相同时）
│  MySQL: CREATE DATABASE ... COLLATE | PgSQL: LC_COLLATE
│  SqlServer: CREATE DATABASE ... COLLATE | Oracle: CREATE USER
│  SQLite: 自动创建文件
▼
[2/5] 建表结构 + 索引 + 注释 + 外键
│  源库 getTableFields() → DbSchemaBuilder 生成 DDL → 目标库执行
│  自动迁移字段注释（MySQL: COMMENT 子句 | PgSQL/Oracle: COMMENT ON COLUMN | SqlServer: sp_addextendedproperty）
│  自动迁移表注释（MySQL: ALTER TABLE COMMENT | PgSQL/Oracle: COMMENT ON TABLE）
│  自动迁移非主键索引（UNIQUE INDEX / 普通 INDEX / 全文索引）
│  自动迁移外键约束（所有表创建后统一添加，避免引用顺序问题）
│  字段默认值完整保留（含空字符串 DEFAULT ''，函数型默认值自动识别）
│  enum/set 类型自动迁移候选值（生成 CHECK 约束）
│  decimal/datetime 精度保留（如 decimal(10,2)、datetime(3)）
│  排序规则（collation）自动迁移：表级 + 列级（MySQL/PostgreSQL）
│  Oracle 自增：自动创建序列+触发器
│  支持 --drop-target-first 先删后建
▼
[3/5] 逐表迁移数据（事务保护）
│  按 batch-size（默认 1000）分页读取，每页再拆为 100 行的 INSERT 语句
│  每个 batch-size 为一个独立事务，提交后即生效
│  当前批次失败时回滚，已提交的历史批次不受影响
│  基于主键 ORDER BY 稳定排序，避免分页漏行/重复
│  blob 字段使用 PDO::PARAM_LOB 绑定
│  SQL Server: 自动开关 IDENTITY_INSERT
▼
[4/5] 重置自增序列
│  PostgreSQL: SELECT setval 重置序列到 MAX(id)+1
│  SQL Server: DBCC CHECKIDENT 重置标识种子
│  Oracle: ALTER SEQUENCE 重置序列
│  MySQL / SQLite: 跳过（无需重置）
▼
[5/5] 逐表行数校验
   SELECT COUNT(*) 对比源和目标，输出 PASS/FAIL
```

## 命令格式

```bash
# =============================================================================
# 数据库迁移命令
# =============================================================================
# php artisan db:migrate → 调用 Laravel Artisan 的数据库迁移工具
# [选项]                 → 通过 --key=value 格式传入源/目标数据库连接参数
# =============================================================================
php artisan db:migrate [选项]
```

### 必填选项

| 选项 | 说明 |
|------|------|
| `--src-type` | 源数据库驱动：`mysql` / `pgsql` / `sqlsrv` / `oracle` / `sqlite` |
| `--src-database` | 源数据库名 |
| `--dst-type` | 目标数据库驱动：`mysql` / `pgsql` / `sqlsrv` / `oracle` / `sqlite` |
| `--dst-database` | 目标数据库名（SQLite 时为文件路径） |

### 源连接选项

| 选项 | 默认值 | 说明 |
|------|--------|------|
| `--src-host` | `127.0.0.1` | 源主机地址 |
| `--src-port` | 自动推断 | 源端口（mysql=3306, pgsql=5432, sqlsrv=1433, oracle=1521） |
| `--src-username` | - | 源用户名（SQLite 除外） |
| `--src-password` | - | 源密码（SQLite 除外） |

### 目标连接选项

| 选项 | 默认值 | 说明 |
|------|--------|------|
| `--dst-host` | `127.0.0.1` | 目标主机地址 |
| `--dst-port` | 自动推断 | 目标端口 |
| `--dst-username` | - | 目标用户名（SQLite 除外） |
| `--dst-password` | - | 目标密码（SQLite 除外） |

### 迁移选项

| 选项 | 默认值 | 说明 |
|------|--------|------|
| `--drop-target-first` | 否 | 迁移前先删除目标库中的同名表 |
| `--batch-size` | `1000` | 每批读取的行数（影响内存占用与迁移速度） |
| `--tables` | 全部 | 只迁移指定表（逗号分隔，不含前缀） |

:::warning 参数名为 `--src-port` / `--dst-port`
选项是 `--src-port` / `--dst-port`（**不是** `hostport`），与签名 `DbMigrateCommand::$signature` 保持一致。端口缺省时按驱动自动推断。
:::

## 迁移命令签名

### MySQL → PostgreSQL

```bash
# -----------------------------------------------------------------------------
# MySQL 迁移到 PostgreSQL
# -----------------------------------------------------------------------------
# --src-* → 源数据库连接参数（MySQL）
# --dst-* → 目标数据库连接参数（PostgreSQL）
# --drop-target-first → 迁移前先删除目标库中的同名表（避免表已存在报错）
php artisan db:migrate \
  --src-type=mysql --src-host=127.0.0.1 --src-port=3306 \
  --src-database=rxthinkcmf.laravel13.elevue --src-username=root --src-password=root \
  --dst-type=pgsql --dst-host=127.0.0.1 --dst-port=5432 \
  --dst-database=rxthinkcmf.laravel13.elevue --dst-username=postgres --dst-password=123456 \
  --drop-target-first
```

### MySQL → SQL Server

```bash
# -----------------------------------------------------------------------------
# MySQL 迁移到 SQL Server
# -----------------------------------------------------------------------------
# --dst-type=sqlsrv → 目标驱动为 SQL Server
# --dst-port=1433 → SQL Server 默认端口
php artisan db:migrate \
  --src-type=mysql --src-host=127.0.0.1 --src-port=3306 \
  --src-database=rxthinkcmf.laravel13.elevue --src-username=root --src-password=root \
  --dst-type=sqlsrv --dst-host=127.0.0.1 --dst-port=1433 \
  --dst-database=rxthinkcmf.laravel13.elevue --dst-username=sa --dst-password=123456 \
  --drop-target-first
```

### MySQL → SQLite

```bash
# -----------------------------------------------------------------------------
# MySQL 迁移到 SQLite
# -----------------------------------------------------------------------------
# --dst-type=sqlite → 目标驱动为 SQLite（无需用户名密码）
# --dst-database → SQLite 文件路径（文件不存在时自动创建）
php artisan db:migrate \
  --src-type=mysql --src-host=127.0.0.1 --src-port=3306 \
  --src-database=rxthinkcmf.laravel13.elevue --src-username=root --src-password=root \
  --dst-type=sqlite --dst-database=database/rxthinkcmf.laravel13.elevue.db
```

### MySQL → Oracle

```bash
# -----------------------------------------------------------------------------
# MySQL 迁移到 Oracle
# -----------------------------------------------------------------------------
# --dst-type=oracle → 目标驱动为 Oracle（自动建用户 + 序列 + 触发器）
php artisan db:migrate \
  --src-type=mysql --src-host=127.0.0.1 --src-port=3306 \
  --src-database=rxthinkcmf.laravel13.elevue --src-username=root --src-password=root \
  --dst-type=oracle --dst-host=127.0.0.1 --dst-port=1521 \
  --dst-database=rxthinkcmf.laravel13.elevue --dst-username=system --dst-password=123456 \
  --drop-target-first
```

### MySQL → MySQL（同实例跨库复制）

```bash
# -----------------------------------------------------------------------------
# MySQL 同库复制（源和目标在同一 MySQL 实例，数据库名不同）
# -----------------------------------------------------------------------------
# 不带 --drop-target-first → 目标表已存在时跳过（不删除）
php artisan db:migrate \
  --src-type=mysql --src-host=127.0.0.1 --src-port=3306 \
  --src-database=source_db --src-username=root --src-password=root \
  --dst-type=mysql --dst-host=127.0.0.1 --dst-port=3306 \
  --dst-database=target_db --dst-username=root --dst-password=root
```

### PostgreSQL → MySQL

```bash
# -----------------------------------------------------------------------------
# PostgreSQL 迁移到 MySQL
# -----------------------------------------------------------------------------
php artisan db:migrate \
  --src-type=pgsql --src-host=127.0.0.1 --src-port=5432 \
  --src-database=rxthinkcmf.laravel13.elevue --src-username=postgres --src-password=123456 \
  --dst-type=mysql --dst-host=127.0.0.1 --dst-port=3306 \
  --dst-database=rxthinkcmf.laravel13.elevue --dst-username=root --dst-password=root \
  --drop-target-first
```

### SQL Server → MySQL

```bash
# -----------------------------------------------------------------------------
# SQL Server 迁移到 MySQL
# -----------------------------------------------------------------------------
php artisan db:migrate \
  --src-type=sqlsrv --src-host=127.0.0.1 --src-port=1433 \
  --src-database=rxthinkcmf.laravel13.elevue --src-username=sa --src-password=123456 \
  --dst-type=mysql --dst-host=127.0.0.1 --dst-port=3306 \
  --dst-database=rxthinkcmf.laravel13.elevue --dst-username=root --dst-password=root \
  --drop-target-first
```

### 只迁移指定表

```bash
# -----------------------------------------------------------------------------
# 只迁移指定表（逗号分隔表名，不含前缀）
# -----------------------------------------------------------------------------
# --tables=laravel_user,laravel_role,laravel_menu → 只迁移这 3 张表
php artisan db:migrate \
  --src-type=mysql --src-host=127.0.0.1 --src-port=3306 \
  --src-database=rxthinkcmf.laravel13.elevue --src-username=root --src-password=root \
  --dst-type=pgsql --dst-host=127.0.0.1 --dst-port=5432 \
  --dst-database=rxthinkcmf.laravel13.elevue --dst-username=postgres --dst-password=123456 \
  --tables=laravel_user,laravel_role,laravel_menu \
  --drop-target-first
```

## 迁移输出日志

### MySQL → PostgreSQL 完整日志

```bash
$ php artisan db:migrate \
    --src-type=mysql --src-host=127.0.0.1 --src-port=3306 \
    --src-database=rxthinkcmf.laravel13.elevue --src-username=root --src-password=root \
    --dst-type=pgsql --dst-host=127.0.0.1 --dst-port=5432 \
    --dst-database=rxthinkcmf.laravel13.elevue --dst-username=postgres --dst-password=123456 \
    --drop-target-first

==============================================================
[迁移开始] 源: mysql:rxthinkcmf.laravel13.elevue → 目标: pgsql:rxthinkcmf.laravel13.elevue
[迁移开始] 待迁移 25 张表
==============================================================
[·] [1/5] 建目标库...
  · 目标库 "rxthinkcmf.laravel13.elevue" 已就绪
[✓] [1/5] 建目标库 完成（耗时 0ms）
[·] [2/5] 建表结构（25 张表）...
[✓] [2/5] 建表结构 完成（耗时 440ms），25 张表，118 个索引，0 个外键
[·] [3/5] 逐表迁移数据...
  · [1/25] 正在迁移 laravel_article...
  [laravel_article] +13（累计 13）
  [✓ laravel_article] 共 13 行（耗时 10ms）
  · [2/25] 正在迁移 laravel_city...
  [laravel_city] +1000（累计 1000）
  ...（大表分批输出进度，每批 1000 行）...
  [laravel_city] +562（累计 783562）
  [✓ laravel_city] 共 783562 行（耗时 10m10s）
  ...（其余表类似）...
[✓] [3/5] 逐表迁移数据 完成（耗时 10m10s），共 785215 行
[·] [4/5] 重置自增序列...
[✓] [4/5] 重置自增序列 完成（耗时 23ms）
[·] [5/5] 逐表行数校验...
  [laravel_article] source=13 target=13 PASS
  [laravel_city] source=783562 target=783562 PASS
  ...（其余表类似）...
[✓] [5/5] 逐表行数校验 完成（耗时 452ms），25 张表全部 PASS
==============================================================
[迁移完成] 成功：785215 行 / 25 张表 / 总耗时 10m11s
==============================================================
```

### MySQL → Oracle 日志摘要

```bash
$ php artisan db:migrate \
    --src-type=mysql --src-host=127.0.0.1 --src-port=3306 \
    --src-database=rxthinkcmf.laravel13.elevue --src-username=root --src-password=root \
    --dst-type=oracle --dst-host=127.0.0.1 --dst-port=1521 \
    --dst-database=rxthinkcmf --dst-username=system --dst-password=123456 \
    --drop-target-first

==============================================================
[迁移开始] 源: mysql:rxthinkcmf.laravel13.elevue → 目标: oracle:rxthinkcmf.laravel13.elevue
==============================================================
[·] [1/5] 建目标库...
  · 目标库 "rxthinkcmf" 已就绪（CREATE USER + GRANT）
[✓] [1/5] 建目标库 完成（耗时 0ms）
[·] [2/5] 建表结构（25 张表）...
  · 为 laravel_article 创建序列+触发器（自增列 id）
  · 为 laravel_city 创建序列+触发器（自增列 id）
  ...（其余含自增列的表类似）...
[✓] [2/5] 建表结构 完成（耗时 2.1s）
[·] [3/5] 逐表迁移数据...
  ...（Oracle INSERT 耗时较 MySQL/SQLite 更长）...
[✓] [3/5] 逐表迁移数据 完成（耗时 15m30s），共 785215 行
[·] [4/5] 重置自增序列...
  · 重置序列: laravel_article_id_seq → 14
  · 重置序列: laravel_city_id_seq → 783563
[✓] [4/5] 重置自增序列 完成（耗时 180ms）
[·] [5/5] 逐表行数校验...
  ...（25 张表全部 PASS）...
==============================================================
[迁移完成] 成功：785215 行 / 25 张表 / 总耗时 15m33s
==============================================================
```

:::tip Oracle 迁移要点
- **建库**：Oracle 通过 `CREATE USER` 创建用户，库名即用户名，需要 DBA 权限
- **自增列**：自动创建序列（`_seq`）和触发器（`_trg`），插入时自动填充——与应用侧 `OracleProcessor` 的主键回填约定一致
- **序列重置**：迁移完成后重置到 MAX+1
- **分页**：使用 `ROW_NUMBER() OVER (ORDER BY 主键)` 保证稳定排序
- **字段名**：Oracle 默认大写，工具自动处理大小写转换
:::

### 只迁移指定表日志

```bash
$ php artisan db:migrate \
    --src-type=mysql --src-host=127.0.0.1 --src-port=3306 \
    --src-database=rxthinkcmf.laravel13.elevue --src-username=root --src-password=root \
    --dst-type=pgsql --dst-host=127.0.0.1 --dst-port=5432 \
    --dst-database=rxthinkcmf.laravel13.elevue --dst-username=postgres --dst-password=123456 \
    --tables=laravel_user,laravel_role,laravel_menu \
    --drop-target-first

==============================================================
[迁移开始] 待迁移 3 张表
==============================================================
[·] [2/5] 建表结构（3 张表）...
  · 已删除目标表: laravel_user
  · 已删除目标表: laravel_role
  · 已删除目标表: laravel_menu
[✓] [2/5] 建表结构 完成（耗时 85ms），3 张表，5 个索引，0 个外键
[·] [3/5] 逐表迁移数据...
  · [1/3] 正在迁移 laravel_user...
  [laravel_user] +22（累计 22）
  [✓ laravel_user] 共 22 行（耗时 9ms）
  ...（其余表类似）...
[✓] [3/5] 逐表迁移数据 完成（耗时 30ms），共 274 行
[·] [4/5] 重置自增序列...
[✓] [4/5] 重置自增序列 完成（耗时 25ms）
[·] [5/5] 逐表行数校验...
  [laravel_user] source=22 target=22 PASS
  [laravel_role] source=24 target=24 PASS
  [laravel_menu] source=228 target=228 PASS
[✓] [5/5] 逐表行数校验 完成（耗时 60ms），3 张表全部 PASS
==============================================================
[迁移完成] 成功：274 行 / 3 张表 / 总耗时 250ms
==============================================================
```

## 类型映射

| 源类型 | MySQL | PostgreSQL | SqlServer | Oracle | SQLite |
|--------|-------|------------|-----------|--------|--------|
| bigint | bigint | bigint | bigint | NUMBER(19) | INTEGER |
| int | int | integer | int | NUMBER(10) | INTEGER |
| smallint | smallint | smallint | smallint | NUMBER(5) | INTEGER |
| tinyint | tinyint | smallint | tinyint | NUMBER(3) | INTEGER |
| decimal | decimal | numeric | decimal | NUMBER | REAL |
| float | float | real | float | BINARY_FLOAT | REAL |
| double | double | double precision | float | BINARY_DOUBLE | REAL |
| varchar | varchar | varchar | nvarchar | VARCHAR2 | TEXT |
| char | char | char | nchar | CHAR | TEXT |
| text | text | text | ntext | CLOB | TEXT |
| blob | blob | bytea | varbinary | BLOB | BLOB |
| datetime | datetime | timestamp | datetime | TIMESTAMP | TEXT |
| timestamp | timestamp | timestamp | datetime | TIMESTAMP | TEXT |
| date | date | date | date | DATE | TEXT |
| boolean | tinyint(1) | boolean | bit | NUMBER(1) | INTEGER |
| json | json | jsonb | ntext | CLOB | TEXT |

:::tip 精度保留
- `decimal(10,2)` → PostgreSQL `numeric(10,2)`（精度不丢失）
- `datetime(3)` → PostgreSQL `timestamp(3)`（毫秒精度保留）
- `enum('a','b','c')` → PostgreSQL `varchar` + `CHECK (col IN ('a','b','c'))`（候选值保留）
:::

## 各驱动特殊处理

| 驱动 | 建库方式 | 分页排序 | 自增语法 | 索引 | 外键 | 字段注释 | 表注释 | collation | 序列重置 |
|------|----------|----------|----------|------|------|----------|--------|-----------|----------|
| MySQL | `CREATE DATABASE ... COLLATE` | 主键 `ORDER BY` | `AUTO_INCREMENT` | ✅ | ✅ | ✅ `COMMENT` | ✅ | ✅ 库/表/列 | 跳过 |
| PostgreSQL | `LC_COLLATE` | 主键 `ORDER BY` | `GENERATED BY DEFAULT AS IDENTITY` | ✅ | ✅ | ✅ `COMMENT ON COLUMN` | ✅ | ✅ 库/列 | ✅ `setval` |
| SQL Server | `COLLATE` | 主键 `ORDER BY` | `IDENTITY(1,1)` | ✅ | ✅ | ✅ `sp_addextendedproperty` | ✅ | ✅ 库级 | ✅ `DBCC CHECKIDENT` |
| Oracle | `CREATE USER` + `GRANT` | `ROW_NUMBER()` | 序列+触发器 | ✅ | ✅ | ✅ `COMMENT ON COLUMN` | ✅ | ❌ | ✅ `ALTER SEQUENCE` |
| SQLite | 自动创建文件 | 主键 `ORDER BY` | `INTEGER PRIMARY KEY AUTOINCREMENT` | ✅ | ✅ | ❌ | ❌ | ❌ | 跳过 |

## PostgreSQL 特殊处理

### 建库

迁移到 PostgreSQL 时，工具会自动连接 `postgres` 维护库执行：

```sql
-- 创建目标数据库（UTF-8 编码）
-- 若数据库已存在则跳过
-- LC_COLLATE / LC_CTYPE：仅当源与目标驱动相同时，从源库读取 collation 并应用
CREATE DATABASE "数据库名" WITH ENCODING 'UTF8'
```

:::warning PgSQL 数据库不存在的判定
PostgreSQL 数据库不存在时返回的 SQLSTATE 可能是 `3D000`（明确不存在）或 `08006`（连接异常，中文环境下错误信息可能乱码）。工具会主动连接 `postgres` 维护库查询 `pg_database` 确认目标库是否真的不存在，避免误判。
:::

### 序列重置

迁移完成后，对每张有自增主键的表分两步重置序列：

```php
// 第一步：通过 pg_get_serial_sequence() 获取列关联的实际序列名
// 兼容 serial（序列名如 table_id_seq）和 IDENTITY（序列名由系统自动生成）两种风格
$seqName = $dstPdo->query(
    "SELECT pg_get_serial_sequence('表名', '字段名') AS s"
)->fetch()['s'];

// 第二步：查询当前最大值，将序列重置到 max+1
// setval 的第三个参数 false 表示下一个 nextval 返回给定值
$maxId = $dstPdo->query(
    "SELECT COALESCE(MAX(\"字段名\"), 0) AS m FROM \"表名\""
)->fetch()['m'];
$dstPdo->exec("SELECT setval({$quotedSeq}, {$maxId} + 1, false)");
```

## SQL Server 特殊处理

### 建库

```sql
-- 连接 master 库，创建目标数据库
-- COLLATE：仅当源与目标驱动相同时，从源库读取 collation 并应用
CREATE DATABASE [数据库名]
```

:::warning SQL Server "登录失败"的判定
SQL Server 数据库不存在时返回 SQLSTATE `28000` 并提示"登录失败"，容易与密码错误混淆。工具会尝试连接 `master` 库验证凭据：若 master 连接成功说明凭据正确、是数据库不存在；若 master 也失败则为密码错误。
:::

### 自增列迁移

数据迁移时自动处理 `IDENTITY_INSERT`：

```sql
-- 迁移前开启（允许显式写入自增列的值）
SET IDENTITY_INSERT [表名] ON
-- 批量 INSERT ...
-- 迁移后关闭
SET IDENTITY_INSERT [表名] OFF
```

### 序列重置

```sql
-- 重置标识种子到指定值，下一次插入自动加一
DBCC CHECKIDENT ('[表名]', RESEED, {$maxId})
```

## Oracle 特殊处理

### 建库

Oracle 的"建库"实际上是创建用户并授权。工具自动连接 Oracle 实例（默认服务名 `XE`），执行：

```sql
-- 创建用户（库名即用户名，密码与连接密码一致）
CREATE USER "用户名" IDENTIFIED BY "密码" DEFAULT TABLESPACE USERS;

-- 授权：CONNECT（连接）、RESOURCE（建表等基础对象操作）
GRANT CONNECT, RESOURCE TO "用户名";
```

:::warning Oracle 连接串
Oracle 的 DSN 格式为 `oci:dbname=//host:port/service_name`，其中 `service_name` 默认为 `XE`（Express Edition）。生产环境需根据实际的 Oracle 服务名修改，可通过 `lsnrctl status` 查看。
:::

### 自增列

Oracle 没有原生自增语法，工具自动创建序列+触发器实现等效功能：

```sql
-- 创建序列（从 1 开始，每次递增 1，不缓存）
-- 序列名规则：表名_列名_SEQ（大写）
CREATE SEQUENCE "TABLE_ID_SEQ" START WITH 1 INCREMENT BY 1 NOCACHE;

-- 创建触发器（插入前自动取序列值填充自增列）
-- 触发器名规则：表名_列名_TRG（大写）
-- IF :NEW.COL IS NULL 判断：允许显式传值，仅当未指定时才自动取序列
CREATE OR REPLACE TRIGGER "TABLE_ID_TRG"
BEFORE INSERT ON "TABLE" FOR EACH ROW
BEGIN
  IF :NEW.ID IS NULL THEN
    SELECT "TABLE_ID_SEQ".NEXTVAL INTO :NEW.ID FROM dual;
  END IF;
END;
```

:::tip 与应用侧的衔接
序列命名 `{表}_{列}_seq`（大写）与应用侧 `App\Support\Database\OracleProcessor` 的 `insertGetId` 回填约定完全一致（见 [5.16 统一响应与异常抛出](/zh/core/exception.html) 相关说明与 [4.9 数据库设计](/zh/architecture/database-design.html)）。
:::

### 序列重置

```sql
-- 重置序列到 MAX(id)+1
ALTER SEQUENCE "TABLE_ID_SEQ" RESTART START WITH 1234;
```

:::warning Oracle 建库权限
Oracle 建库实际上是通过 `CREATE USER` + `GRANT CONNECT, RESOURCE` 创建用户。需要 DBA 权限或具有 CREATE USER 权限的账号。连接串中的服务名默认为 `XE`（Express Edition），正式环境需根据实际配置修改。
:::

## 驱动安装与环境配置

迁移工具基于 PDO 直连数据库，各驱动需要对应的 PDO 扩展。Laragon 默认自带 MySQL、PostgreSQL 和 SQLite 驱动，SQL Server 和 Oracle 需手动安装。

运行以下命令检查已安装的驱动：

```bash
# 检查已安装的 PDO 驱动（-m 列出扩展，findstr /i 不区分大小写过滤）
$PHP_HOME\php.exe -m | findstr /i pdo

# 列出所有可用的 PDO 驱动
$PHP_HOME\php.exe -r "print_r(PDO::getAvailableDrivers());"
```

### MySQL（Laragon 默认自带）

无需额外操作。验证：

```bash
$PHP_HOME\php.exe -m | findstr mysql
```

### PostgreSQL（DLL 随包自带，php.ini 默认注释）

`ext\php_pdo_pgsql.dll` 与 `libpq.dll` 已随 PHP 包附带，但 `$PHP_HOME\php.ini` 扩展区的
`extension=pdo_pgsql` 默认是注释状态，**需去掉分号启用**：

```ini
;extension=pdo_odbc
extension=pdo_pgsql        ← 去掉此行分号
extension=pdo_sqlite
```

验证（`pdo_pgsql` 出现即可，`PDO::getAvailableDrivers()` 应包含 `pgsql`）：

```bash
$PHP_HOME\php.exe -m | findstr pgsql
$PHP_HOME\php.exe -r "print_r(PDO::getAvailableDrivers());"
```

CLI 每次进程都会重读 `php.ini`，无需重启；跑在 Apache（mod_php）下的需重启 Apache 才生效。
未启用时执行 `--dst-type=pgsql` 会报 `could not find driver`。

### SQL Server（需手动安装）

Laragon 默认不带 SQL Server 驱动，需要安装两个组件。

:::warning 先决条件
安装 ODBC 驱动前，系统需要 Microsoft Visual C++ Redistributable。大多数 Windows 已预装，如果安装失败，先安装它再重试。
:::

**步骤 1：安装 Microsoft ODBC Driver for SQL Server**

这是底层通信组件，sqlsrv 扩展依赖它，必须安装。

- 下载地址：https://learn.microsoft.com/zh-cn/sql/connect/odbc/download-odbc-driver-for-sql-server
- 版本选择：推荐 ODBC Driver 18（最新），两者可与 17 并存
- 安装：下载 x64 版本的 `msodbcsql.msi`，双击按向导完成

**步骤 2：下载 PHP 扩展 DLL**

从微软官方 GitHub 下载：

- 下载地址（Releases 页面）：https://github.com/Microsoft/msphpsql/releases
- 下载文件：`Windows_5.13.3RTW.zip`（本项目基于 **PHP 8.3 起步**，该包覆盖 PHP 8.3 / 8.4 / 8.5）

解压后目录结构（平铺，无子目录），文件命名规则：`php_{驱动}_{PHP版本}_{线程安全}_{架构}.dll`

- 驱动：`sqlsrv` 或 `pdo_sqlsrv`
- PHP 版本：`83`（PHP 8.3）/ `84`（PHP 8.4）/ `85`（PHP 8.5）
- 线程安全：`ts`（Thread Safe）/ `nts`（Non-Thread Safe）
- 架构：`x64` / `x86`

`Windows_5.13.3RTW.zip` 解压后共 24 个 DLL：

```text
php_sqlsrv_83_nts_x64.dll       php_sqlsrv_83_nts_x86.dll
php_sqlsrv_83_ts_x64.dll        php_sqlsrv_83_ts_x86.dll
php_sqlsrv_84_nts_x64.dll       php_sqlsrv_84_nts_x86.dll
php_sqlsrv_84_ts_x64.dll        php_sqlsrv_84_ts_x86.dll
php_sqlsrv_85_nts_x64.dll       php_sqlsrv_85_nts_x86.dll
php_sqlsrv_85_ts_x64.dll        php_sqlsrv_85_ts_x86.dll
php_pdo_sqlsrv_83_nts_x64.dll   php_pdo_sqlsrv_83_nts_x86.dll
php_pdo_sqlsrv_83_ts_x64.dll    php_pdo_sqlsrv_83_ts_x86.dll
php_pdo_sqlsrv_84_nts_x64.dll   php_pdo_sqlsrv_84_nts_x86.dll
php_pdo_sqlsrv_84_ts_x64.dll    php_pdo_sqlsrv_84_ts_x86.dll
php_pdo_sqlsrv_85_nts_x64.dll   php_pdo_sqlsrv_85_nts_x86.dll
php_pdo_sqlsrv_85_ts_x64.dll    php_pdo_sqlsrv_85_ts_x86.dll
```

将以下两个文件复制到 `$PHP_HOME\ext\`（本项目用 **PHP 8.3 TS x64**）：

- `php_sqlsrv_83_ts_x64.dll`
- `php_pdo_sqlsrv_83_ts_x64.dll`

:::tip 版本匹配（PHP 8.3 + TS + x64）
- PHP 版本：`83` = PHP 8.3
- 线程安全：Laragon 的 Apache 用 TS（运行 `$PHP_HOME\php.exe -i | findstr "Thread Safety"` 确认 → `enabled`）
- 架构：`x64`（64 位系统）
:::

**步骤 3：在 php.ini 中启用扩展**

编辑 `$PHP_HOME\php.ini`：

1. 启用前置扩展：找到 `;extension=mbstring` 去掉分号（sqlsrv 依赖 mbstring）
2. 在 mbstring 之后添加以下两行（文件名必须与 ext 目录中的实际文件一致）：

```ini
; SQL Server PHP 扩展（必须在 mbstring 之后加载）
extension=php_sqlsrv_83_ts_x64.dll          ; SQL Server 核心驱动
extension=php_pdo_sqlsrv_83_ts_x64.dll      ; SQL Server PDO 驱动（迁移工具使用）
```

3. 保存后重启 Apache（命令行验证无需重启 Apache，只需重新运行 php 命令）

**步骤 4：验证安装**

```bash
# 检查 SQL Server 驱动是否已加载（应看到 sqlsrv 和 pdo_sqlsrv 两行）
$PHP_HOME\php.exe -m | findstr sqlsrv
```

### Oracle（需手动配置）

迁移工具基于 PDO 连接数据库，需要 `pdo_oci` 扩展，需安装 Oracle Instant Client 并在 php.ini 中启用 `pdo_oci`（完整图文步骤见 [2.1 开发环境准备](/zh/quickstart/environment.html)「数据库安装 → Oracle」）。

**步骤摘要：**

1. 安装 Oracle Instant Client（Basic Package，x64，推荐 19c），解压到固定路径 `C:\oracle\instantclient_19_20`（⚠️ 避免空格与中文）
2. 将该路径添加到系统 `PATH`
3. 安装 VC++ 2015-2022 Redistributable（x64）：https://aka.ms/vc14/vc_redist.x64.exe
4. 编辑 `$PHP_HOME\php.ini`，启用 `extension=pdo_oci`
5. 完全重启 Laragon（不是只重启 Apache）

:::warning 安装 VC++ 运行库
Oracle Instant Client 19c 依赖 VC++ 2015-2022 Redistributable，缺少会导致 DLL 加载失败。
:::

**验证安装：**

```bash
# 检查 pdo_oci 扩展是否已加载
$PHP_HOME\php.exe -m | findstr -i "pdo_oci"

# 列出所有可用的 PDO 驱动（应包含 oci）
$PHP_HOME\php.exe -r "print_r(PDO::getAvailableDrivers());"
```

应看到 `pdo_oci` 输出，且 `PDO::getAvailableDrivers()` 返回的数组中包含 `oci`。

### SQLite（默认自带）

无需额外操作。验证：

```bash
$PHP_HOME\php.exe -m | findstr sqlite
```

### 驱动安装速查表

| 驱动 | Laragon 默认 | 安装方式 | 验证命令 |
|------|-----------|----------|----------|
| pdo_mysql | ✅ 自带 | 无需安装 | `php -m \| findstr mysql` |
| pdo_pgsql | ✅ 自带 | php.ini 启用 | `php -m \| findstr pgsql` |
| pdo_sqlsrv | ❌ 需安装 | ODBC 驱动 + 扩展 DLL（83_ts_x64） | `php -m \| findstr sqlsrv` |
| pdo_oci | ❌ 需配置 | InstantClient + VC++ 运行库 + php.ini 启用 | `php -m \| findstr pdo_oci` |
| pdo_sqlite | ✅ 自带 | 无需安装 | `php -m \| findstr sqlite` |

## 相关代码

| 文件 | 说明 |
|------|------|
| `app/Console/Commands/DbMigrateCommand.php` | CLI 命令入口（参数解析、退出码，Laravel 自动发现注册） |
| `app/Services/DbMigrateService.php` | 迁移引擎服务（连接、建库、建表、数据迁移、序列重置、行数校验） |
| `app/Services/DbSchemaBuilder.php` | DDL 生成器（类型映射、CREATE TABLE / INDEX / FK / COMMENT 语句生成） |

## 注意事项

:::warning 迁移前检查
1. 确保目标数据库用户有 CREATE TABLE / INSERT / CREATE INDEX / ALTER TABLE（外键）权限
2. PostgreSQL 迁移还需要 CREATE DATABASE 权限
3. SQL Server 迁移需要 sa 或有 CREATE DATABASE 权限的用户
4. Oracle 迁移需要 DBA 权限或具有 CREATE USER / CREATE SEQUENCE / CREATE TRIGGER 权限的账号
5. `--drop-target-first` 会删除目标表的全部数据（含索引、外键和注释），请谨慎使用
6. 大表迁移建议调大 `--batch-size`（如 5000）以提高效率
7. 迁移过程中如遇中断，已提交的 `--batch-size` 批次数据不会回滚，建议使用 `--drop-target-first` 重试
8. 含点号的数据库名（如 `rxthinkcmf.laravel13.elevue`）各驱动均已适配
9. 索引、外键和注释在建表阶段同步迁移，使用 `--drop-target-first` 重建时会一并重建
10. 外键约束在所有表创建后统一添加，避免引用顺序问题
11. 命令退出码：成功返回 0，失败或行数校验未通过返回 1（可用于 CI/CD 判断）
:::

## 常见问题

### Q: 迁移失败后如何重试？

A: 使用 `--drop-target-first` 选项重新执行，会先删除目标表再重建。

### Q: 如何只迁移部分表？

A: 使用 `--tables` 选项指定表名，逗号分隔（不含前缀）：

```bash
php artisan db:migrate ... --tables=laravel_user,laravel_role
```

### Q: 大表迁移很慢怎么办？

A: 调大 `--batch-size`，如 `--batch-size=5000`。默认 1000 行一批，增大批量可减少数据库交互次数。

### Q: 目标库不存在会自动创建吗？

A: 会。所有驱动（MySQL / PostgreSQL / SQL Server / Oracle / SQLite）在目标库不存在时都会自动创建，无需手动建库。建库时会自动从源库读取 collation 并应用（仅当源与目标驱动相同时）。

PostgreSQL 走维护库 `postgres` 执行 `CREATE DATABASE`，含点号的库名会自动加双引号（如 `"rxthinkcmf.laravel13.elevue"`）；建库失败时抛出 `创建目标数据库失败: …` 并把原始异常保留在 previous 中。

### Q: 报 `could not find driver` 怎么办？

A: PHP 缺少目标驱动的 PDO 扩展。迁到 PostgreSQL 需要 `pdo_pgsql`：在 `$PHP_HOME\php.ini` 扩展区去掉 `extension=pdo_pgsql` 的分号（DLL 随包自带，无需下载），CLI 重读 `php.ini` 即生效；Linux 用 `apt install php8.3-pgsql`。可用 `$PHP_HOME\php.exe -r "print_r(PDO::getAvailableDrivers());"` 确认驱动已加载。

### Q: PostgreSQL 报 SQLSTATE 08006 错误怎么办？

A: `08006` 是连接异常的通用错误码，服务端消息可能是英文（`database "x" does not exist`）或中文（`数据库 "x" 不存在`），中文环境下控制台还可能出现乱码（先 `chcp 65001` 或换 Windows Terminal 查看）。工具对两种语言的消息都会识别，并**主动连接 `postgres` 维护库查询 `pg_database`** 权威确认目标库是否缺失：确认缺失则自动建库后重连；维护库也连不上时按原始异常抛出，请检查 PostgreSQL 服务是否启动、端口是否正确、密码是否正确。

### Q: SQL Server 报"登录失败"怎么办？

A: SQL Server 数据库不存在时会返回"登录失败"（SQLSTATE 28000），工具会自动连接 `master` 库验证凭据并区分。如果确实是密码错误，请检查 `--dst-password`。

### Q: 索引、外键、注释、默认值会迁移吗？

A: 会。迁移工具在建表阶段会同步迁移以下元数据：

- **索引**：自动读取源表的非主键索引（UNIQUE / 普通 / 全文），在目标表创建后执行 `CREATE INDEX`
- **外键**：自动读取源表的外键约束，在所有表创建后统一添加 `ALTER TABLE ... ADD CONSTRAINT ... FOREIGN KEY`，避免引用顺序问题
- **字段注释**：MySQL 目标直接写入 `COMMENT` 子句；PostgreSQL / Oracle 使用 `COMMENT ON COLUMN`；SQL Server 使用 `sp_addextendedproperty`
- **表注释**：MySQL 使用 `ALTER TABLE COMMENT`；PostgreSQL / Oracle 使用 `COMMENT ON TABLE`
- **默认值**：完整保留，包括空字符串 `DEFAULT ''`、数值默认值、`CURRENT_TIMESTAMP`、`CURRENT_DATE`、函数调用等
- **enum/set**：自动迁移候选值，生成 `CHECK` 约束
- **decimal/datetime 精度**：保留精度参数（如 `decimal(10,2)` → `numeric(10,2)`，`datetime(3)` → `timestamp(3)`）
- **collation**：建库时自动应用源库 collation（仅同驱动时）；建表时迁移表级和列级 collation（MySQL / PostgreSQL）

### Q: 数据迁移的可靠性如何保证？

A: 迁移工具有以下保障机制：

- **事务保护**：每个 `--batch-size`（默认 1000 行）为一个独立事务，提交后即生效；当前批次失败时回滚，已提交的历史批次不受影响
- **稳定排序**：分页查询基于主键列 `ORDER BY`，确保大表分批迁移不会漏行或重复
- **退出码**：命令成功返回 0，失败或行数校验未通过返回 1，可用于 CI/CD 自动化判断
- **行数校验**：迁移完成后逐表对比源和目标的行数，输出 PASS/FAIL

### Q: Oracle 自增列如何处理？

A: Oracle 没有原生自增语法。迁移工具会自动为自增列创建序列（`CREATE SEQUENCE`）和触发器（`CREATE TRIGGER`），实现等效的自增功能；序列命名与应用侧 `OracleProcessor` 主键回填约定一致。

### Q: 含点号的数据库名支持吗？

A: 支持。如 `rxthinkcmf.laravel13.elevue` 这类含点号的库名，各驱动均已适配。

### Q: SQLite 作为目标有什么限制？

A: SQLite 不支持字段注释、表注释和 collation。迁移完成后数据完整，索引和外键正常迁移。

### Q: 与 document/ 下的 SQL 脚本有何区别？

A: `document/` 下的五套 SQL 脚本是**静态初始化脚本**（建库 + 初始数据，见 [2.5 数据库初始化](/zh/quickstart/database-init.html)）；`db:migrate` 是**活的迁移工具**，用于把一个已有数据库完整搬到另一个数据库（结构 + 数据 + 元数据），两者互补。