openclaw-config/workspace-sql/skills/mysql-schema-sync/SKILL.md

name, description

name	description
mysql-schema-sync	MySQL 表结构同步最佳实践：跨环境同步 DDL，处理 CREATE/ALTER 失败场景

MySQL 表结构同步最佳实践

场景

将准生产/测试环境的表结构同步到生产环境，确保 DDL 一致。

核心原则

1. 表名必须带数据库前缀 - 如 dmp_smdm.dmp_md_item_info，因为生产实例有多个库
2. 不暴露敏感信息 - 脚本中只写库名和表名，IP/密码用环境变量
3. 先验证后执行 - 先 SELECT 确认表结构和数据量
4. CREATE 优先于 ALTER - 能新建不修改，减少冲突

脚本生成规范

使用 mysqldump 导出结构

mysqldump -h SOURCE_HOST -P PORT -u USER -p"PASSWORD" \
    --no-data --skip-lock-tables \
    DB_NAME > db_struct.sql

脚本格式要求

-- ============================================================
-- 表结构同步脚本：table_name
-- 源：准生产 (host:port)
-- 目标：VPS (host:port) database
-- ============================================================

CREATE TABLE IF NOT EXISTS `database`.`table_name` (
  -- 字段定义
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci COMMENT='表说明';

目录结构

scripts/YYYYMMDD/
├── README.md              # 同步记录（成功/失败清单）
├── database__table__struct.sql
└── run_sync.sh

执行策略

CREATE TABLE（新建表）

for sql_file in database__*_struct.sql; do
    mysql -h TARGET_HOST -u root -p"PASSWORD" -D database < "$sql_file"
done

ALTER TABLE（修改表）

1. 检查目标表是否存在

   SELECT TABLE_NAME FROM information_schema.TABLES 
   WHERE TABLE_SCHEMA = 'database' AND TABLE_NAME = 'table_name';
   

2. 对比结构差异

   SHOW CREATE TABLE source.table_name\G
   SHOW CREATE TABLE target.table_name\G
   

3. 生成差异脚本（只修改不同的字段/索引）

4. 外键约束延迟添加 - 所有表完成后，再添加外键

常见失败原因及处理

错误类型	解决方案
字段已存在	跳过或使用 ALTER TABLE ... MODIFY COLUMN
索引冲突	先 DROP INDEX 再 ADD INDEX
外键约束失败	延迟到所有表创建后添加外键
字符集冲突	保持原字符集或先转换数据
NOT NULL 约束	先更新 NULL 值为默认值

验证步骤

1. 表数量对比

   SELECT COUNT(*) FROM information_schema.TABLES WHERE TABLE_SCHEMA = 'database';
   

2. 结构对比

   SHOW CREATE TABLE database.table_name\G
   

3. 关键字段验证

   SELECT COLUMN_NAME, IS_NULLABLE, COLUMN_DEFAULT, DATA_TYPE
   FROM information_schema.COLUMNS
   WHERE TABLE_SCHEMA = 'database' AND TABLE_NAME = 'table_name';
   

回滚方案

1. 执行前备份

   mysqldump -h TARGET_HOST -u root -p"PASSWORD" \
       --no-data --routines --triggers \
       database > backup_before_sync.sql
   

2. 记录执行日志

   ./run_sync.sh > sync_log.txt 2>&1
   

3. 失败表单独处理 - 记录失败的表和错误信息，人工分析后生成修复脚本