附录 B：IPC协议参考

本附录详细描述 VSDB IPC 通信协议。

B.1 协议概述

VSDB 使用 JSON 序列化的消息通过 child_process.send() 进行 IPC 通信。

graph LR
    A["Extension Host"] -->|"JSON over IPC"| B["Worker Process"]
    B -->|"JSON over IPC"| A

B.2 请求类型

connect

建立数据库连接。

{
  "id": "uuid-request",
  "type": "connect",
  "connectionId": "uuid-connection",
  "payload": {
    "config": {
      "id": "uuid-connection",
      "name": "dev-mysql",
      "type": "mysql",
      "host": "localhost",
      "port": 3306,
      "username": "root",
      "password": "secret",
      "database": "myapp",
      "scope": "project"
    }
  }
}

disconnect

断开数据库连接。

{
  "id": "uuid-request",
  "type": "disconnect",
  "connectionId": "uuid-connection",
  "payload": {}
}

query

执行 SQL 查询。

{
  "id": "uuid-request",
  "type": "query",
  "connectionId": "uuid-connection",
  "payload": {
    "sql": "SELECT * FROM users LIMIT 10",
    "params": []
  }
}

streamQuery

执行流式查询（大数据集）。

{
  "id": "uuid-request",
  "type": "streamQuery",
  "connectionId": "uuid-connection",
  "payload": {
    "sql": "SELECT * FROM large_table",
    "params": []
  }
}

schema

查询数据库元信息。

{
  "id": "uuid-request",
  "type": "schema",
  "connectionId": "uuid-connection",
  "payload": {
    "schemaType": "tables",
    "database": "myapp"
  }
}

schemaType 可选值：

• databases - 数据库列表
• tables - 表列表
• columns - 列信息（需指定 table）
• views - 视图列表
• procedures - 存储过程列表
• indexes - 索引信息（需指定 table）
• constraints - 约束信息（需指定 table）
• triggers - 触发器信息（需指定 table）
• ddl - DDL 语句（需指定 table）

cancel

取消流式查询。

{
  "id": "uuid-stream-request",
  "type": "cancel",
  "connectionId": "",
  "payload": {}
}

ping

心跳检测。

{
  "id": "heartbeat",
  "type": "ping",
  "connectionId": "",
  "payload": {}
}

shutdown

关闭 Worker。

{
  "id": "",
  "type": "shutdown",
  "connectionId": "",
  "payload": {}
}

B.3 响应类型

result

成功响应。

{
  "id": "uuid-request",
  "type": "result",
  "data": {
    "columns": ["id", "name", "email"],
    "rows": [
      { "id": 1, "name": "Alice", "email": "alice@example.com" },
      { "id": 2, "name": "Bob", "email": "bob@example.com" }
    ],
    "rowCount": 2,
    "executionTime": 15
  }
}

streamEnd

流式查询结束标记。

{
  "id": "uuid-request",
  "type": "streamEnd"
}

error

错误响应。

{
  "id": "uuid-request",
  "type": "error",
  "error": {
    "code": "QUERY_ERROR",
    "message": "Syntax error near 'SELCT'",
    "errorClass": "syntax",
    "retryable": false
  }
}

错误码列表：

• CONNECT_FAILED - 连接失败
• NOT_CONNECTED - 未连接
• MISSING_SQL - 缺少 SQL
• MISSING_CONFIG - 缺少配置
• QUERY_ERROR - 查询错误
• STREAM_ERROR - 流式查询错误
• SCHEMA_ERROR - Schema 查询错误
• UNKNOWN_REQUEST_TYPE - 未知的请求类型
• WORKER_MEMORY_EXCEEDED - 内存超限

pong

心跳响应。

{
  "id": "heartbeat",
  "type": "pong"
}

B.4 流式分块

StreamChunk 格式：

{
  "requestId": "uuid-request",
  "chunkIndex": 0,
  "rows": [
    { "id": 1, "name": "Alice" },
    { "id": 2, "name": "Bob" },
    // ... 最多 1000 行
  ],
  "totalRows": 2500  // 仅最后一块包含
}

B.5 时序图示例

普通查询

sequenceDiagram
    participant Host as Extension Host
    participant Worker as Worker
    
    Host->>Worker: { type: "query", sql: "SELECT ..." }
    Worker-->>Host: { type: "result", data: { rows: [...] } }

流式查询

sequenceDiagram
    participant Host as Extension Host
    participant Worker as Worker
    
    Host->>Worker: { type: "streamQuery", sql: "SELECT ..." }
    Worker-->>Host: { requestId, chunkIndex: 0, rows: [...] }
    Worker-->>Host: { requestId, chunkIndex: 1, rows: [...] }
    Worker-->>Host: { requestId, chunkIndex: 2, rows: [...], totalRows: 2500 }
    Worker-->>Host: { type: "streamEnd" }

连接失败

sequenceDiagram
    participant Host as Extension Host
    participant Worker as Worker
    
    Host->>Worker: { type: "connect", config: {...} }
    Worker-->>Host: { type: "error", error: { code: "CONNECT_FAILED" } }

B.6 超时配置

B.7 错误分类