---
name: soul-mysql-direct
description: 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 安装依赖（首次）

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

### 3.2 执行单条 SQL

```bash
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 文件

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

### 3.4 指定 DSN（覆盖 .env）

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

---

## 4. Agent 执行流程

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

1. **确认凭证**：soul-api/.env 中是否有 `DB_DSN`？若无，请用户提供或设置环境变量。
2. **编写 SQL**：按需求写 `ALTER TABLE`、`INSERT`、`UPDATE` 等。
3. **执行**：`cd 项目根目录 && node .cursor/scripts/db-exec/run.js "SQL"`。
4. **同步 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 直接操作、字段增减、迁移执行