第二章：核心概念

本章深入介绍 VSDB 的核心数据模型、类型定义和关键概念。

2.1 连接模型

DbConnection 接口

export interface DbConnection {
  id: string;                    // UUID，唯一标识
  name: string;                  // 用户自定义名称，如 "dev-mysql"
  type: 'mysql' | 'postgresql';  // 数据库类型
  host: string;                  // 主机地址
  port: number;                  // 端口号
  username: string;              // 用户名
  password: string;              // 密码（存储时加密）
  database?: string;             // 默认数据库
  options?: Record<string, any>; // 扩展选项（SSL、charset 等）
  group?: string;                // 分组名称
  color?: string;                // 颜色标记
  scope: 'project' | 'global';   // 存储范围
}

连接范围

graph TD
    subgraph "项目级 scope: project"
        P1[".vsdb/connections.json"]
        P2["仅当前项目可见"]
        P3["团队可共享（git）"]
    end
    
    subgraph "全局级 scope: global"
        G1["~/.vsdb/connections.json"]
        G2["所有项目可见"]
        G3["个人私有"]
    end
    
    P1 --> P2
    P2 --> P3
    
    G1 --> G2
    G2 --> G3

范围	存储位置	可见性	用途
`project`	`.vsdb/connections.json`	当前项目	团队共享开发数据库
`global`	`~/.vsdb/connections.json`	所有项目	个人私有数据库

连接状态

export interface ConnectionState {
  connectionId: string;
  status: 'disconnected' | 'connecting' | 'connected' | 'error';
  error?: string;
  activeDatabase?: string;
  lastQuery?: string;
  lastQueryTime?: number;
}

状态流转：

stateDiagram-v2
    [*] --> disconnected
    disconnected --> connecting: 用户点击连接
    connecting --> connected: 连接成功
    connecting --> error: 连接失败
    connected --> disconnected: 用户断开
    error --> connecting: 重试
    connected --> error: 连接丢失

2.2 扫描模型

ScannedConnection 接口

export interface ScannedConnection {
  name: string;                  // 生成的连接名称
  type: 'mysql' | 'postgresql';
  host: string;
  port: number;
  username: string;
  password: string;
  database?: string;
  source: 'env' | 'docker-compose' | 'framework';
  sourceFile: string;            // 来源文件路径
  confidence: 'high' | 'medium' | 'low';
}

置信度分级

置信度	来源	特点
`high`	DATABASE_URL, docker-compose	信息完整，可直接使用
`medium`	框架配置解析	信息可能不完整
`low`	部分 DB_* 变量	缺少关键信息（如密码）

ScannerResult 接口

export interface ScannerResult {
  connections: ScannedConnection[];  // 发现的连接
  errors: Array<{ file: string; error: string }>;  // 解析错误
  scannedFiles: string[];            // 扫描过的文件列表
}

2.3 IPC 协议模型

WorkerRequest 接口

export interface WorkerRequest {
  id: string;           // 请求 UUID
  type: 'connect' | 'disconnect' | 'query' | 
        'streamQuery' | 'schema' | 'cancel' | 'ping' | 'shutdown';
  connectionId: string;
  payload: {
    config?: DbConnection;
    sql?: string;
    params?: unknown[];
    schemaType?: 'databases' | 'tables' | 'columns' | 
                 'views' | 'procedures' | 'indexes' | 
                 'constraints' | 'triggers' | 'ddl';
    database?: string;
    table?: string;
  };
}

WorkerResponse 接口

export interface WorkerResponse {
  id: string;           // 匹配请求 UUID
  type: 'result' | 'stream' | 'streamEnd' | 'error' | 'pong';
  data?: QueryResult | SchemaResult;
  error?: {
    code: string;
    message: string;
    errorClass?: 'connection' | 'syntax' | 'timeout' | 'permission' | 'unknown';
    retryable?: boolean;
  };
}

StreamChunk 接口（流式传输）

export interface StreamChunk {
  requestId: string;          // 匹配请求 UUID
  chunkIndex: number;         // 分块索引
  rows: Record<string, unknown>[];  // 数据行
  totalRows?: number;         // 总行数（仅最后一块）
}

流式传输示意：

sequenceDiagram
    participant Host as Extension Host
    participant Worker as Worker Process
    
    Host->>Worker: streamQuery (id=001)
    Worker-->>Host: StreamChunk (index=0, rows=[...1000])
    Worker-->>Host: StreamChunk (index=1, rows=[...1000])
    Worker-->>Host: StreamChunk (index=2, rows=[...500], totalRows=2500)
    Worker-->>Host: streamEnd (id=001)

2.4 查询结果模型

QueryResult 接口

export interface QueryResult {
  columns: string[];                // 列名数组
  rows: Record<string, unknown>[];  // 数据行数组
  rowCount: number;                 // 行数
  affectedRows?: number;            // 影响行数（INSERT/UPDATE/DELETE）
  executionTime: number;            // 执行时间（毫秒）
}

SchemaResult 接口

export interface SchemaResult {
  type: 'databases' | 'tables' | 'columns' | 'views' | 
        'procedures' | 'indexes' | 'constraints' | 'triggers' | 'ddl';
  data: unknown[];
}

2.5 Schema 信息模型

表信息

export interface TableInfo {
  name: string;
  schema?: string;            // PostgreSQL schema
  columns: ColumnInfo[];
  indexes: IndexInfo[];
  rowCount?: number;
}

列信息

export interface ColumnInfo {
  name: string;
  type: string;               // 如 "varchar(255)", "int"
  nullable: boolean;
  defaultValue?: string;
  isPrimaryKey: boolean;
  isAutoIncrement: boolean;
}

索引信息

export interface IndexInfo {
  name: string;
  columns: string[];          // 索引包含的列
  isUnique: boolean;
  isPrimary: boolean;
}

Schema 结构示例

graph TD
    A["数据库"] --> B["表: users"]
    B --> C["列"]
    C --> C1["id: int, PK, auto_increment"]
    C --> C2["name: varchar(255), NOT NULL"]
    C --> C3["email: varchar(255), NULL"]
    
    B --> D["索引"]
    D --> D1["PRIMARY (id)"]
    D --> D2["idx_email (email), UNIQUE"]
    
    B --> E["约束"]
    E --> E1["PRIMARY KEY (id)"]
    E --> E2["UNIQUE (email)"]

2.6 查询历史模型

export interface QueryHistoryItem {
  id: string;              // UUID
  sql: string;             // SQL 语句
  connectionId: string;    // 执行连接
  connectionName: string;  // 连接名称
  executedAt: Date;        // 执行时间
  rowCount?: number;       // 结果行数
  executionTime?: number;  // 执行时间（毫秒）
  pinned?: boolean;        // 固定标记（不被自动清理）
}

历史记录管理策略：

graph TD
    A["执行 SQL"] --> B["记录到历史"]
    B --> C["检查上限"]
    C -->|"超过 100 条"| D["清理未固定的旧记录"]
    C -->|"未超过"| E["保持"]
    D --> F["保留固定记录"]

2.7 书签模型

Bookmark 接口

export interface Bookmark {
  id: string;
  type: 'connection' | 'database' | 'table' | 'query';
  name: string;            // 显示名称
  target: {
    connectionId?: string;
    database?: string;
    table?: string;
    sql?: string;
  };
  createdAt: Date;
  groupId?: string;        // 所属分组 ID
}

BookmarkGroup 接口

export interface BookmarkGroup {
  id: string;
  name: string;
  color?: string;          // 颜色标识
}

书签类型结构：

graph TD
    A["Bookmark"] --> B["connection"]
    A --> C["database"]
    A --> D["table"]
    A --> E["query"]
    
    B --> B1["target: connectionId"]
    C --> C1["target: connectionId + database"]
    D --> D1["target: connectionId + database + table"]
    E --> E1["target: connectionId + sql"]

2.8 搜索模型

SearchResult 接口

export interface SearchResult {
  type: 'table' | 'column' | 'data';
  connectionId: string;
  connectionName: string;
  database: string;
  name: string;            // 表名/列名
  detail?: string;         // 列类型、表名等详细信息
}

SearchOptions 接口

export interface SearchOptions {
  searchTables?: boolean;      // 搜索表名（默认 true）
  searchColumns?: boolean;     // 搜索列名（默认 true）
  searchData?: boolean;        // 搜索数据内容（默认 false）
  connectionIds?: string[];    // 限制特定连接
  tables?: string[];           // 数据搜索范围
  caseSensitive?: boolean;     // 大小写敏感
}

Schema 缓存

export interface SchemaCacheEntry {
  tables: TableInfo[];
  columns: ColumnInfo[];
  cachedAt: Date;
}

缓存策略：

graph TD
    A["搜索请求"] --> B{"缓存存在?"}
    B -->|是| C["使用缓存"]
    B -->|否| D["查询 Worker"]
    D --> E["存入缓存"]
    E --> C
    C --> F["返回结果"]

2.9 小结

本章介绍了 VSDB 的核心概念：

概念	用途
`DbConnection`	数据库连接配置
`ConnectionState`	连接状态跟踪
`ScannedConnection`	扫描发现的连接
`WorkerRequest/Response`	IPC 通信协议
`StreamChunk`	大数据流式传输
`QueryResult`	查询结果封装
`TableInfo/ColumnInfo`	Schema 元信息
`QueryHistoryItem`	查询历史记录
`Bookmark`	书签收藏
`SearchResult`	搜索结果

下一章将深入系统架构设计。

Keyboard shortcuts

VSDB 技术文档