Files

Alex-larget 8778a42429 2026年3月14日14:37:06

2026-03-14 14:37:17 +08:00

4.4 KiB

Raw Blame History

name, description

name	description
soul-mysql-direct	Soul 创业派对 MySQL 直接操作。MCP 无法连接时用 db-exec 脚本执行 SQL。ALTER TABLE、迁移、字段增减。Use when 数据库操作, MCP 连不上, 增减字段, 执行迁移.

Soul 创业派对 - MySQL 直接操作 Skill

当 MCP MySQL 因端口非 3306 无法连接，或需要执行数据库字段增减、迁移、修复时，使用本 Skill。通过 db-exec 脚本读取 soul-api 的 .env 中的 DB_DSN，直接执行 SQL，无需 MCP。

1. 何时使用本 Skill

MCP MySQL 连接失败（端口非 3306、网络不通等）
soul-api 需要增减数据库字段，需执行 ALTER TABLE
需要执行迁移 SQL、数据修复、紧急 DDL/DML
用户提供账户密码，要求直接操作数据库

2. 凭证来源（按优先级）

来源	说明
环境变量 `DB_DSN`	运行时 `DB_DSN=xxx node run.js "SQL"`
参数 `--dsn=`	`node run.js --dsn="user:pass@tcp(host:port)/db" "SQL"`
soul-api/.env	自动读取 `DB_DSN`（格式含端口，如 `@tcp(host:14413)/db`）

安全：凭证只从 .env 或环境变量读取，不得写入 Skill 或提交到仓库。

3. 执行方式

3.1 安装依赖（首次）

cd .cursor/scripts/db-exec && npm install

3.2 执行单条 SQL

cd e:\Gongsi\Mycontent
node .cursor/scripts/db-exec/run.js "SELECT 1"
node .cursor/scripts/db-exec/run.js "DESCRIBE orders"
node .cursor/scripts/db-exec/run.js "ALTER TABLE users ADD COLUMN new_field VARCHAR(64) DEFAULT ''"

3.3 执行 SQL 文件

node .cursor/scripts/db-exec/run.js -f migrations/20260225_add_xxx.sql

3.4 指定 DSN（覆盖 .env）

node .cursor/scripts/db-exec/run.js --dsn="user:pass@tcp(host:14413)/db" "SELECT 1"

4. Agent 执行流程

当用户要求「增减数据库字段」「直接操作 MySQL」「执行迁移」时：

确认凭证：soul-api/.env 中是否有 DB_DSN？若无，请用户提供或设置环境变量。
编写 SQL：按需求写 ALTER TABLE、INSERT、UPDATE 等。
执行：cd 项目根目录 && node .cursor/scripts/db-exec/run.js "SQL"。
同步 model：若改了表结构，同步修改 soul-api 的 internal/model 对应结构体。

5. DSN 格式说明

soul-api 的 DB_DSN 格式：

user:password@tcp(host:port)/database?charset=utf8mb4&parseTime=True

端口：写在 tcp(host:port) 中，支持非 3306（如 14413）。
密码含特殊字符：需 URL 编码（@ → %40，# → %23 等）。

6. 与 MCP 的配合

场景	推荐方式
MCP 可连接（端口已正确配置）	优先用 `mcp_MySQL_*` 工具
MCP 无法连接（端口/网络问题）	用本 Skill + db-exec 脚本
生产库操作	务必谨慎，建议先备份或本地测试

MCP 配置参考：开发文档/8、部署/Soul-MySQL-MCP配置说明.md（连接串方式可带端口）。

7. 与 soul-api 的配合

执行 ALTER TABLE 后，必须同步修改 internal/model 中的 GORM 结构体。
迁移 SQL 建议放在 soul-api/scripts/ 或 soul-api/migrations/，便于版本管理。

8. 迁移脚本最佳实践（吸收 vip_roles 经验）

新增表或字段时，编写可重复执行或幂等的 SQL 脚本：

场景	写法	说明
新建表	`CREATE TABLE IF NOT EXISTS xxx (...)`	幂等，重复执行不报错
新增列	`ALTER TABLE xxx ADD COLUMN yyy ...`	MySQL 不支持 IF NOT EXISTS，重复执行会报错；可单独执行或注释掉已执行部分
插入默认数据	`INSERT IGNORE INTO xxx (name, sort) VALUES (...)`	配合 `UNIQUE(name)` 防重复；不指定 id 让 AUTO_INCREMENT 生效
脚本位置	`soul-api/scripts/add-xxx.sql`	命名清晰，便于部署时按顺序执行

完整流程：1) 编写 SQL 脚本 → 2) 同步修改 internal/model → 3) 执行迁移脚本（node .cursor/scripts/db-exec/run.js -f soul-api/scripts/add-xxx.sql）→ 4) 重启 soul-api。

重要：GORM AutoMigrate 不一定自动新增列（取决于启动时机与连接），Model 新增字段后必须显式执行 ALTER 脚本，否则会报 Unknown column 'xxx' in 'field list'。

创建时间：2026-02
适用：MCP 无法连接时的 MySQL 直接操作、字段增减、迁移执行

4.4 KiB Raw Blame History Unescape Escape