Catalog (0.2.1)

Vega Backend Catalog（数据目录）API。

Catalog 是一个数据源连接的抽象，对应一个物理数据源（MySQL / SQL Server / OpenSearch / S3 等） 或逻辑目录（虚拟视图）。资源（Resource）按 catalog 归属注册。

SQL Server 连接器（connector_type: sqlserver）

{
  "connector_type": "sqlserver",
  "connector_config": {
    "host": "sqlserver.example.com",
    "port": 1433,
    "username": "vega_reader",
    "password": "<encrypted-password>",
    "database": "sales",
    "schemas": ["dbo", "reporting"],
    "options": {
      "encrypt": true,
      "trustservercertificate": false,
      "hostnameincertificate": "sqlserver.example.com",
      "connection timeout": 30,
      "app name": "vega-backend"
    }
  }
}

• host、port、username、password、database 必填；schemas 为空时发现当前账号可见的非系统 schema。
• options 仅允许 encrypt、trustservercertificate、hostnameincertificate、 connection timeout 和 app name（名称不区分大小写）；其中前两项必须是 boolean。
• 推荐使用独立只读账号，并授予目标数据库的连接、元数据查看和查询权限。例如： GRANT CONNECT TO [vega_reader]、GRANT VIEW DEFINITION TO [vega_reader]，以及 ALTER ROLE [db_datareader] ADD MEMBER [vega_reader]；不要授予 db_datawriter、db_ddladmin 或 db_owner。
• TLS 可通过上述驱动参数启用；trustservercertificate: true 会跳过服务端证书校验，只适合受控测试环境。 未配置 encrypt 时使用 go-mssqldb v1.9.2 的 EncryptionOff 默认行为，即客户端不主动要求全程加密； 如需确定启用 TLS，应显式配置 encrypt: true 和 trustservercertificate: false。 当前未提供自定义 CA 文件配置，TLS 成功与失败路径尚待真实 SQL Server 环境验收。
• 一个 Catalog 只连接一个 database，并在其中按 schema 发现对象；不支持跨数据库发现、CDC 和 Windows 集成认证。

可检索业务 KV（extensions，Issue #382，方案 B）

• 与 tags（最多 5 个、用于展示的短字符串列表）不同，extensions 为 扁平 string→string， 用于 DIP 等域外元数据及 列表按 key/value 筛选；持久化见 **t_entity_extension**（仅存一套行）。
• 创建 / 更新：请求体可选 extensions。根对象出现 extensions 键（含 {}） 即对该 catalog 做 KV 整包替换；键不出现则不修改已有 KV。
• 读取：详情与列表（include_extensions=true 时）返回 **extensions**。
• 列表：默认不返回各条目的 KV object；include_extensions=true 时返回。 可选 include_extension_keys 仅投影部分 key。
• 列表筛选：**extension_key/extension_value**（数组 query，style=form + explode=true），等长成对 AND。
• 设计依据： catalog-resource-labels-scheme-b-design.md

持久化（与 migrations/mariadb、migrations/dm8 惯例对齐）

• 表名：t_entity_extension（不改 t_catalog / t_resource 主表结构）。
• 列：f_entity_id VARCHAR(40) NOT NULL（与 t_catalog.f_id 同一取值空间、全局唯一）、 f_key VARCHAR(128) NOT NULL、f_value VARCHAR(512) NOT NULL、 f_create_time / f_update_time BIGINT（与现有表时间字段风格一致）。
• 主键：PRIMARY KEY (f_entity_id, f_key)（单值语义；无 f_scope 列，依赖 catalog/resource id 全局不冲突之前提，见设计文档）。
• 索引（MariaDB 示例，DM8 同源语义）：KEY idx_entity (f_entity_id)； KEY idx_entity_key_value (f_entity_id, f_key, f_value(191)) 等（前缀长度以方言上限为准）。
• 删除 catalog 时应用层同事务删除 t_entity_extension 中 f_entity_id 等于该 catalog f_id 的行； 若级联删除其下 resource，须一并删除对应 resource 的 f_entity_id 行。

本文件仅包含 catalog 自身的 CRUD 与状态相关端点。跨资源的便利端点：

• POST /catalogs/{id}/discover（手动发现一次） → 见 discover-task.yaml
• GET /catalogs/{ids}/resources（按 catalog 列资源） → 见 resource.yaml
• GET /catalogs/{cid}/discover-schedules（按 catalog 列调度） → 见 discover-schedule.yaml
• GET/PUT /catalogs/{id}/health-check-schedule（健康检查计划） → 见 catalog-health-check-schedule.yaml

每个外部接口都有一一对应的内部版本，路径前缀为 /api/vega-backend/in/v1，请求体与 响应结构与外部完全一致；区别仅在于鉴权方式：外部走 OAuth Token 校验，内部从请求头 （X-Account-ID / X-Account-Type）解析访问者。

本文档仅描述外部接口。