dsh-lh-data 0.1.0

package/src/datasource/connector/postgresql.ts

@@ -0,0 +1,212 @@
+/**
+ * PostgreSQL 连接器。
+ *
+ * 元数据走 `pg_catalog`：一次查询拿到 schema 内所有表的列、类型、注释与主键，
+ * 行数取 `reltuples`（规划器估计值，未分析过的表为 -1）。
+ */
+
+import { loadPgDriver, type PgPoolLike } from '../driver'
+import { DataSourceError, wrapConnectionError } from '../errors'
+import type { ColumnType } from '../../parse'
+import type {
+  ConnectionConfig,
+  ConnectionTestResult,
+  RemoteColumn,
+  RemoteTable,
+  SchemaSummary,
+} from '../types'
+import { DatabaseConnector } from './base'
+
+interface ColumnRow {
+  table_name: string
+  estimate: number | string | null
+  column_name: string | null
+  column_type: string | null
+  is_nullable: boolean | null
+  column_comment: string | null
+  is_primary: boolean | null
+}
+
+/** 只取普通表 / 分区表 / 物化视图：排除系统目录与索引。 */
+const RELKINDS = "'r','p','m','v','f'"
+
+const TABLE_COLUMNS_SQL = `
+SELECT c.relname AS table_name,
+       c.reltuples::bigint AS estimate,
+       a.attname AS column_name,
+       format_type(a.atttypid, a.atttypmod) AS column_type,
+       NOT a.attnotnull AS is_nullable,
+       col_description(a.attrelid, a.attnum) AS column_comment,
+       pk.attnum IS NOT NULL AS is_primary
+FROM pg_class c
+JOIN pg_namespace n ON n.oid = c.relnamespace
+LEFT JOIN pg_attribute a ON a.attrelid = c.oid AND a.attnum > 0 AND NOT a.attisdropped
+LEFT JOIN (SELECT i.indrelid, i.indkey[0] AS attnum FROM pg_index i WHERE i.indisprimary) pk
+  ON pk.indrelid = c.oid AND pk.attnum = a.attnum
+WHERE n.nspname = $1 AND c.relkind IN (${RELKINDS})
+ORDER BY c.relname, a.attnum`
+
+const ONE_TABLE_COLUMNS_SQL = `
+SELECT a.attname AS column_name,
+       format_type(a.atttypid, a.atttypmod) AS column_type,
+       NOT a.attnotnull AS is_nullable,
+       col_description(a.attrelid, a.attnum) AS column_comment,
+       pk.attnum IS NOT NULL AS is_primary
+FROM pg_class c
+JOIN pg_namespace n ON n.oid = c.relnamespace
+LEFT JOIN pg_attribute a ON a.attrelid = c.oid AND a.attnum > 0 AND NOT a.attisdropped
+LEFT JOIN (SELECT i.indrelid, i.indkey[0] AS attnum FROM pg_index i WHERE i.indisprimary) pk
+  ON pk.indrelid = c.oid AND pk.attnum = a.attnum
+WHERE n.nspname = $1 AND c.relname = $2
+ORDER BY a.attnum`
+
+function poolOptions(config: ConnectionConfig): Record<string, unknown> {
+  const options: Record<string, unknown> = {
+    host: config.host,
+    port: config.port,
+    database: config.database,
+    user: config.username,
+    password: config.password,
+    max: config.poolMax ?? 5,
+    connectionTimeoutMillis: config.connectTimeoutMs,
+  }
+  if (config.sslMode !== null && config.sslMode !== 'disable') {
+    options.ssl = { rejectUnauthorized: config.sslMode === 'verify-full' || config.sslMode === 'verify-ca' }
+  }
+  return options
+}
+
+/** `format_type` 的输出形如 `character varying(255)` / `timestamp with time zone`。 */
+function mapPgType(formatType: string): ColumnType {
+  const base = formatType.split('(')[0].trim().split(' ')[0].toLowerCase()
+  if (base === 'bool' || base === 'boolean') return 'boolean'
+  if (['int2', 'int4', 'int8', 'smallint', 'int', 'integer', 'bigint', 'serial', 'bigserial'].includes(base)) return 'numeric'
+  if (['numeric', 'decimal', 'real', 'float', 'float4', 'float8', 'double', 'money'].includes(base)) return 'numeric'
+  if (['date', 'time', 'timestamp', 'timestamptz', 'interval'].includes(base)) return 'date'
+  return 'text'
+}
+
+function toRemoteColumn(row: ColumnRow): RemoteColumn {
+  const comment = row.column_comment === null || row.column_comment === undefined ? null : String(row.column_comment)
+  return {
+    name: String(row.column_name ?? ''),
+    nativeType: mapPgType(String(row.column_type ?? '')),
+    nullable: row.is_nullable === true,
+    comment: comment === null || comment.length === 0 ? null : comment,
+  }
+}
+
+function groupTables(rows: readonly ColumnRow[], schemaName: string): RemoteTable[] {
+  const byName = new Map<string, RemoteTable>()
+  for (const row of rows) {
+    let table = byName.get(row.table_name)
+    if (table === undefined) {
+      table = {
+        tableName: row.table_name,
+        schemaName,
+        rowCount: Number(row.estimate ?? -1),
+        primaryKey: null,
+        columns: [],
+      }
+      byName.set(row.table_name, table)
+    }
+    if (row.column_name !== null) {
+      const column = toRemoteColumn(row)
+      table.columns.push(column)
+      if (row.is_primary === true && table.primaryKey === null) table.primaryKey = column.name
+    }
+  }
+  return [...byName.values()]
+}
+
+export class PostgreSQLConnector extends DatabaseConnector {
+  private pool: PgPoolLike | null = null
+
+  async connect(): Promise<void> {
+    if (this.pool !== null) return
+    const pg = await loadPgDriver()
+    this.pool = new pg.Pool(poolOptions(this.config))
+  }
+
+  async disconnect(): Promise<void> {
+    const pool = this.pool
+    this.pool = null
+    if (pool !== null) await pool.end()
+  }
+
+  async testConnection(): Promise<ConnectionTestResult> {
+    const startedAt = Date.now()
+    let pool: PgPoolLike | null = null
+    try {
+      const pg = await loadPgDriver()
+      pool = new pg.Pool({ ...poolOptions(this.config), max: 1 })
+      const result = await pool.query('SELECT version() AS version')
+      const version = (result.rows[0] as { version?: unknown } | undefined)?.version
+      return {
+        success: true,
+        latency: Date.now() - startedAt,
+        version: version === undefined ? null : String(version),
+        error: null,
+      }
+    } catch (error) {
+      return { success: false, latency: Date.now() - startedAt, version: null, error: describe(error) }
+    } finally {
+      if (pool !== null) await pool.end().catch(() => undefined)
+    }
+  }
+
+  async getSchemas(): Promise<SchemaSummary[]> {
+    const rows = await this.query(`
+      SELECT n.nspname AS schema_name, COUNT(c.oid)::int AS total
+      FROM pg_namespace n
+      LEFT JOIN pg_class c ON c.relnamespace = n.oid AND c.relkind IN (${RELKINDS})
+      WHERE n.nspname NOT LIKE 'pg\\_%' AND n.nspname <> 'information_schema'
+      GROUP BY n.nspname
+      ORDER BY n.nspname`)
+    return (rows as { schema_name: string; total: number | string }[]).map(row => ({
+      schemaName: String(row.schema_name),
+      tableCount: Number(row.total ?? 0),
+    }))
+  }
+
+  async getTables(schemaName?: string): Promise<RemoteTable[]> {
+    const schema = schemaName === undefined || schemaName.trim().length === 0 ? 'public' : schemaName.trim()
+    const rows = await this.query(TABLE_COLUMNS_SQL, [schema])
+    return groupTables(rows as ColumnRow[], schema)
+  }
+
+  async getTableColumns(tableName: string, schemaName?: string): Promise<RemoteColumn[]> {
+    const schema = schemaName === undefined || schemaName.trim().length === 0 ? 'public' : schemaName.trim()
+    const rows = await this.query(ONE_TABLE_COLUMNS_SQL, [schema, tableName])
+    return (rows as ColumnRow[]).map(toRemoteColumn)
+  }
+
+  async getTableData(
+    tableName: string,
+    schemaName?: string,
+    range?: { limit?: number; offset?: number },
+  ): Promise<Record<string, unknown>[]> {
+    const schema = schemaName === undefined || schemaName.trim().length === 0 ? 'public' : schemaName.trim()
+    return await this.query(this.buildSelectQuery(tableName, schema, range)) as Record<string, unknown>[]
+  }
+
+  protected quoteIdent(name: string): string {
+    return `"${name.replace(/"/g, '""')}"`
+  }
+
+  private async query(sql: string, params: unknown[] = []): Promise<unknown[]> {
+    const pool = this.pool
+    if (pool === null) throw new DataSourceError('UNREACHABLE', 'PostgreSQL 连接尚未建立，请先调用 connect()')
+    try {
+      const result = await pool.query(sql, params)
+      return result.rows
+    } catch (error: unknown) {
+      throw wrapConnectionError(error, this.config.host, this.config.port)
+    }
+  }
+}
+
+function describe(error: unknown): string {
+  const message = error instanceof Error ? error.message : String(error)
+  return message.replace(/(postgres(?:ql)?:\/\/)[^\s'"]*/gi, '$1***').slice(0, 300)
+}

package/src/datasource/crypto.ts

@@ -0,0 +1,61 @@
+/**
+ * 数据源密码的加解密：AES-256-GCM，密钥由 scryptSync 派生。
+ *
+ * 密文格式 `iv:authTag:encrypted`（十六进制）。落库只存密文，解密只在建立连接的
+ * 那一刻发生在内存里，任何日志 / 工具返回 / HTTP 响应都不出现明文。
+ */
+
+import { createCipheriv, createDecipheriv, randomBytes, scryptSync } from 'node:crypto'
+import { DataSourceError } from './errors'
+
+const ALGORITHM = 'aes-256-gcm'
+const IV_LENGTH = 16
+const SALT = 'dsh-lh-data-datasource'
+const DEFAULT_KEY = 'dsh-lh-data-default-key'
+
+/** 优先级：配置项 → 环境变量 `LH_DATA_ENCRYPT_KEY` → 内置默认值（不安全，启动时会告警）。 */
+export function resolveEncryptKey(configured: string): string {
+  const fromConfig = configured.trim()
+  if (fromConfig.length > 0) return fromConfig
+  const fromEnv = (process.env.LH_DATA_ENCRYPT_KEY ?? '').trim()
+  return fromEnv.length > 0 ? fromEnv : DEFAULT_KEY
+}
+
+/** 配置与环境变量都没给密钥时为 true（调用方据此告警一次）。 */
+export function usingDefaultEncryptKey(configured: string): boolean {
+  return resolveEncryptKey(configured) === DEFAULT_KEY
+}
+
+function deriveKey(password: string): Buffer {
+  return scryptSync(password, SALT, 32)
+}
+
+export function encryptPassword(password: string, key: string): string {
+  const iv = randomBytes(IV_LENGTH)
+  const cipher = createCipheriv(ALGORITHM, deriveKey(key), iv)
+  let encrypted = cipher.update(password, 'utf8', 'hex')
+  encrypted += cipher.final('hex')
+  return `${iv.toString('hex')}:${cipher.getAuthTag().toString('hex')}:${encrypted}`
+}
+
+export function decryptPassword(encrypted: string, key: string): string {
+  const parts = encrypted.split(':')
+  if (parts.length !== 3) {
+    throw new DataSourceError('BAD_REQUEST', '数据源密码格式非法（无法解密，请重新保存该数据源）')
+  }
+  const [ivHex, authTagHex, data] = parts
+  try {
+    const decipher = createDecipheriv(ALGORITHM, deriveKey(key), Buffer.from(ivHex, 'hex'))
+    decipher.setAuthTag(Buffer.from(authTagHex, 'hex'))
+    return decipher.update(data, 'hex', 'utf8') + decipher.final('utf8')
+  } catch {
+    throw new DataSourceError('BAD_REQUEST', '数据源密码解密失败（密钥可能已变更，请重新保存该数据源）')
+  }
+}
+
+export function isValidEncryptedFormat(encrypted: string): boolean {
+  const parts = encrypted.split(':')
+  if (parts.length !== 3) return false
+  const isHex = (value: string): boolean => /^[0-9a-f]+$/i.test(value)
+  return isHex(parts[0]) && parts[0].length === IV_LENGTH * 2 && isHex(parts[1]) && isHex(parts[2]) && parts[2].length > 0
+}

package/src/datasource/driver.ts

@@ -0,0 +1,108 @@
+/**
+ * 数据库驱动的运行时加载。
+ *
+ * `mysql2` / `pg` 已随插件默认安装（`dependencies`），但仍走**动态 import**：
+ * 用到哪个才加载哪个，CLI 剖面与只用文件导入的用户不会被这两个包拖慢启动。
+ * 万一运行环境里缺包（裁剪安装、pnpm 过滤等），抛 `DataSourceError('DRIVER_MISSING')`
+ * 并在消息里带上安装命令，而不是崩在裸栈上。
+ *
+ * 导入说明符必须走变量，不能用字面量——字面量会让 TypeScript 与打包器在解析期
+ * 就去解析这两个包，缺包时 typecheck / build 直接失败。
+ */
+
+import { DataSourceError } from './errors'
+import type { DataSourceType } from './types'
+
+export const DRIVER_INSTALL_HINTS: Readonly<Record<DataSourceType, string>> = {
+  mysql: 'pnpm add mysql2',
+  postgresql: 'pnpm add pg',
+}
+
+const DRIVER_SPECS: Readonly<Record<DataSourceType, string>> = {
+  mysql: 'mysql2/promise',
+  postgresql: 'pg',
+}
+
+// ── 驱动的最小结构（只声明本模块用到的成员，不引第三方 .d.ts） ──────────────
+
+interface MysqlLike {
+  createPool(options: Record<string, unknown>): MysqlPoolLike
+  createConnection(options: Record<string, unknown>): Promise<MysqlConnLike>
+}
+
+export interface MysqlPoolLike {
+  execute(sql: string, params?: unknown[]): Promise<[unknown[], unknown]>
+  end(): Promise<void>
+}
+
+interface MysqlConnLike {
+  execute(sql: string, params?: unknown[]): Promise<[unknown[], unknown]>
+  end(): Promise<void>
+}
+
+interface PgLike {
+  Pool: new (options: Record<string, unknown>) => PgPoolLike
+}
+
+export interface PgPoolLike {
+  query(sql: string, params?: unknown[]): Promise<{ rows: unknown[] }>
+  end(): Promise<void>
+}
+
+// ── 加载 ─────────────────────────────────────────────────────────────────────
+
+const cache = new Map<DataSourceType, unknown>()
+
+const MODULE_MISSING_CODES: readonly string[] = [
+  'ERR_MODULE_NOT_FOUND',
+  'MODULE_NOT_FOUND',
+  'ERR_PACKAGE_PATH_NOT_EXPORTED',
+]
+
+function isModuleMissing(error: unknown): boolean {
+  const code = (error as { code?: unknown } | null)?.code
+  return typeof code === 'string' && MODULE_MISSING_CODES.includes(code)
+}
+
+/** CJS 互操作：`await import('pg')` 拿到的是带 `default` 的命名空间。 */
+function unwrapDefault(loaded: unknown): Record<string, unknown> {
+  if (typeof loaded === 'object' && loaded !== null && 'default' in loaded) {
+    const fallback = (loaded as { default?: unknown }).default
+    if (typeof fallback === 'object' && fallback !== null) return fallback as Record<string, unknown>
+  }
+  return (loaded ?? {}) as Record<string, unknown>
+}
+
+async function load(type: DataSourceType): Promise<Record<string, unknown>> {
+  const cached = cache.get(type)
+  if (cached !== undefined) return cached as Record<string, unknown>
+  const spec = DRIVER_SPECS[type]
+  let loaded: unknown
+  try {
+    loaded = await import(spec)
+  } catch (error) {
+    if (isModuleMissing(error)) {
+      throw new DataSourceError(
+        'DRIVER_MISSING',
+        `未安装 ${type === 'mysql' ? 'MySQL' : 'PostgreSQL'} 驱动，请执行：${DRIVER_INSTALL_HINTS[type]}`,
+      )
+    }
+    throw error
+  }
+  const mod = unwrapDefault(loaded)
+  cache.set(type, mod)
+  return mod
+}
+
+/** 仅供测试：清掉模块级缓存。 */
+export function resetDriverCache(): void {
+  cache.clear()
+}
+
+export async function loadMysqlDriver(): Promise<MysqlLike> {
+  return (await load('mysql')) as unknown as MysqlLike
+}
+
+export async function loadPgDriver(): Promise<PgLike> {
+  return (await load('postgresql')) as unknown as PgLike
+}

package/src/datasource/errors.ts

@@ -0,0 +1,69 @@
+/**
+ * 数据源模块的统一错误类型。
+ *
+ * 主机侧的边界（工具 / 管理接口）把它翻译成 `ToolError` / `AdminServiceError`。
+ * 错误文本一律脱敏：不含密码、不含本地物理表名。
+ */
+
+export type DataSourceErrorCode =
+  | 'NOT_FOUND'
+  | 'DRIVER_MISSING'
+  | 'UNREACHABLE'
+  | 'BAD_REQUEST'
+  | 'TOO_MANY_ROWS'
+  | 'IMPORT_FAILED'
+
+export class DataSourceError extends Error {
+  readonly code: DataSourceErrorCode
+
+  constructor(code: DataSourceErrorCode, message: string) {
+    super(message)
+    this.name = 'DataSourceError'
+    this.code = code
+  }
+}
+
+export function isDataSourceError(error: unknown): error is DataSourceError {
+  return error instanceof DataSourceError
+}
+
+/**
+ * 原生驱动错误 → 脱敏的中文提示。
+ * 只保留可定位的主机与端口，凭据绝不进文本。
+ */
+export function describeCause(error: unknown): string {
+  const code = (error as { code?: unknown } | null)?.code
+  if (typeof code === 'string') {
+    if (code === 'ECONNREFUSED') return '连接被拒绝（主机可达，但端口未开放或服务未启动）'
+    if (code === 'ENOTFOUND' || code === 'EAI_AGAIN') return '主机名无法解析'
+    if (code === 'ETIMEDOUT' || code === 'EHOSTUNREACH') return '连接超时（主机不可达或被防火墙拦截）'
+    if (code === 'ER_ACCESS_DENIED_ERROR' || code === '28P01' || code === '28000') return '用户名或密码错误'
+    if (code === 'ER_DBACCESS_DENIED_ERROR' || code === '3D000') return '数据库不存在，或该用户无权访问'
+    if (code === 'ER_NOT_SUPPORTED_AUTH_MODE') return '服务端认证协议不被驱动支持'
+    if (code === 'EPROTO') return 'SSL 协商失败（检查 sslMode 配置）'
+  }
+  const message = error instanceof Error ? error.message.split('\n')[0] : String(error)
+  return message.trim().length > 0 ? message.trim() : '未知错误'
+}
+
+/**
+ * 连接 / 查询异常归一为 `DataSourceError`。
+ * 已经是 `DataSourceError` 的（如 DRIVER_MISSING）保持原语义，其余按「连不上」处理，
+ * 这样工具与设置页永远不会把驱动的裸栈抛给模型 / 浏览器。
+ */
+export function wrapConnectionError(error: unknown, host: string, port: number): unknown {
+  if (isDataSourceError(error)) return error
+  return new DataSourceError('UNREACHABLE', `连接 ${host}:${port} 失败：${describeCause(error)}`)
+}
+
+/** 错误码 → HTTP 状态码（管理接口用；工具侧另有一套映射）。 */
+export function dataSourceErrorStatus(code: DataSourceErrorCode): number {
+  switch (code) {
+    case 'NOT_FOUND': return 404
+    case 'DRIVER_MISSING': return 503
+    case 'UNREACHABLE': return 502
+    case 'BAD_REQUEST': return 400
+    case 'TOO_MANY_ROWS': return 413
+    default: return 500
+  }
+}