Hasura Data Connector SDK 完全指南从零构建、测试与部署 GraphQL Engine 数据连接器 Agent【免费下载链接】graphql-engineBlazing fast, instant realtime GraphQL APIs on all your data with fine grained access control, also trigger webhooks on database events.项目地址: https://gitcode.com/gh_mirrors/gr/graphql-engine本篇指南围绕当前仓库 dc-agents/sdk/README.md 展开系统讲解 Hasura GraphQL Engine Data Connector数据连接器Agent 的概念、SDK 组成、基于 Docker Compose 的开发测试工作流以及官方推荐的设计原则。读完你将掌握如何用docker compose up一键拉起参考 Agent 与 HGE、如何运行官方集成测试套件、如何基于 TypeScript 参考实现改造或替换出自己的 Agent并通过 Metadata API 将其接入 GraphQL Engine。什么是 Data Connector AgentData Connector Agent数据连接器代理是一个把数据源抽象在 REST API 与一套明确定义的线上传输格式wire format之后的服务。它扮演 HGE 与数据库之间的中间层middlewareHGE 将查询计划编码为 JSON 请求发送给 AgentAgent 负责对接底层数据源并返回符合规范的 JSON 响应。其核心价值在于无需修改 HGE 核心代码即可扩展数据库支持。开发者通过 HGE 的 Metadata API 在运行时配置 Agent 的 URI就能接入此前不受支持的数据库Agent 甚至可以不依赖任何上游数据库直接提供全新功能。这种服务化架构支持动态重配置——连接哪些 Agent、支持哪些数据库都可以随场景变化而调整非常适合固定驱动集不适用的场景。关于该特性的完整设计与架构说明参见仓库中的 dc-agents/DOCUMENTATION.md官方支持的 Agent 清单见 dc-agents/HUB.md。SDK 的定位与版本管理SDK 是一整套文档 资源的组合包用于帮助开发者理解、构建并测试 Data Connector Agent 实现确保其完整complete、正确correct、符合惯例idiomatic并能快速且有信心地开发。SDK 会随时间演进持续吸收 Hasura 推荐的 Agent 开发最佳实践因此 SDK 本身有版本管理并通过随包附带的.env文件与 Hasura GraphQL EngineHGE版本建立关联——不同版本 SDK 对应不同版本的 HGE、参考 Agent 与测试镜像。推荐工作流从零到跑通SDK 的默认工作流由 Docker Compose 驱动目的是把依赖数量降到最低当然每个组件也都可以脱离 Docker 原生运行。官方推荐的开发流程如下用docker compose up启动整个技术栈检查测试是否通过若计划使用 TypeScript按需修改参考 Agentreference agent或者用你自己的 Agent 实现替换参考 Agent按需重建 Agent 镜像用docker compose run tests重新运行测试通过暴露在 http://localhost:8080 的 GraphQL Engine 与 Agent 交互在 http://localhost:8300 浏览 OpenAPI SchemaSwaggerUI。整套 SDK 本身就是模板可以随意增删改任何组件。SDK 组件全景SDK 以 zip 压缩包形式分发仓库中的 dc-agents/sdk/ 目录即其内容包含以下组件组件说明文档README.md、README_DATA_CONNECTORS.md说明 SDK 组件如何组装、如何启动并运行测试、Data Connector 特性架构OpenAPI 类型agent.openapi.json描述 Agent API 的格式化 JSON Schema参考 Agentreference-agent/TypeScript 实现docker-compose.yaml编排 HGE、PostgresHGE 元数据存储、Agent 测试套件、参考 Agent、SwaggerUI 五个服务.env文件指定 SDK 资源的构建版本号HGE 元数据metadata/用于引导bootstrap把参考 Agent 添加为数据源docker-compose.yaml 逐服务解析仓库中的 dc-agents/sdk/docker-compose.yaml 定义了完整的开发栈reference-agent使用hasura/dc-reference-agent:${HASURA_VERSION}镜像暴露端口8100:8100。文件里预留了# build: ./reference注释——如果你要修改参考 Agent可以启用 Docker Compose 的 build 配置本地构建。postgrespostgres:13作为 HGE 元数据存储密码为postgrespassword数据持久化在命名卷db_data。enginehasura/graphql-engine:${HASURA_VERSION}暴露8080:8080通过HASURA_GRAPHQL_METADATA_DATABASE_URL连接 Postgres并开启 ConsoleHASURA_GRAPHQL_ENABLE_CONSOLE: true与开发模式HASURA_GRAPHQL_DEV_MODE: true日志类型覆盖 startup、http-log、webhook-log、websocket-log、query-log。文件中还注释了 Intel/ARM 特定平台镜像的写法。replace-metadata使用curlimages/curl在 engine 就绪后向http://engine:8080/v1/metadataPOST./metadata/metadata-api.json把参考 Agent 引导进 HGE 元数据restart: on-failure保证失败重试。tests使用hasura/dc-agent-tests:${HASURA_VERSION}镜像执行tests-dc-api test --agent-base-url http://reference-agent:8100即对参考 Agent 跑完整集成测试。swagger-uiswaggerapi/swagger-ui:v4.10.3挂载./agent.openapi.json暴露8300:8080。若你是原生 Docker混合部署尤其是开发自己的 Agent 时需要注意Docker 服务要正确暴露端口且当 Docker 服务指向原生服务时要使用合适的主机 URI例如host.docker.internal。Agent 开发与架构的通用原则参考 Agent 给出了一个 Agent 能做什么、应该怎么开发的完整示例但官方还总结了以下推荐原则指导 Agent 的结构与演进自描述能力Capabilities Self DescribingAgent 必须通过capabilities特性描述自身能力无状态StatelessAgent 应该是透明地无状态的每个请求自带执行所需的全部信息逻辑下沉Defer logic to backend尽可能把处理逻辑下放到后端数据库类型安全Type-safe严格按 OpenAPI Schema 中描述的类型进行接收与返回向后兼容Backwards compatible演进过程中保持向后兼容测试Testing必须用官方提供的测试套件进行测试。自描述/capabilities 与 /schema 端点参考 Agent 的入口是 dc-agents/reference/src/index.ts一个基于 Fastify 的 HTTP 服务从静态 JSON 文件加载 Chinook 数据集。其核心端点包括GET /capabilities返回 Agent 的能力声明以及X-Hasura-DataConnector-Config请求头所携带配置的 JSON SchemaPOST /schema返回数据 schema 信息表、列请求体可携带配置POST /query接收编码为 JSON 的查询结构并执行返回请求的字段GET /health健康检查POST /mutation数据变更请求文档中标注为 DEPRECATED 的旧版GET /schema也存在。其中/capabilities的具体声明在 dc-agents/reference/src/capabilities.ts声明支持主键/外键、可空与不可空列nullable_and_non_nullable、foreach 查询、redaction、基于关系的子查询supports_relations: true并为DateTime、string、number三类标量类型声明了各自的比较运算符如same_day_as、in_year、聚合函数max、min、stddev、sum等与更新列运算符inc。/capabilities响应中还包含config_schemas即对配置 JSON 的 Schema 描述见 dc-agents/reference/src/config.ts。OpenAPI Schema 与类型Agent API 的 OpenAPI Schema 与类型集中定义在一个格式化 JSON 文件中agent.openapi.json。除了该文件本身SDK 还通过docker-compose.yaml内置了 SwaggerUI 界面启动后可在 http://localhost:8300 交互式浏览和调试该 Schema。这也是开发阶段对照协议最直观的工具。运行集成测试套件测试架构要求先有一个正在运行的 Agent测试套件再指向该 Agent 执行一系列集成测试。测试逻辑遵循以下规则首先对 Agent 运行若干强制mandatory场景若未给测试套件额外选项它会自动发现 Agent 的能力见 DOCUMENTATION.md 的 Capabilities 章节遍历其声明的能力并运行对应测试验证这些能力是否被正确实现若声明了非法能力则报告错误能力也可以通过测试套件的 CLI 选项显式列出——此时无论 Agent 如何声明都会测试这些列出的能力并展示列出能力与声明能力的差异。这对于确认 Agent 声明的能力符合你的预期非常有用若发现错误会随测试运行打印出来只要遇到任何错误进程就会设置错误状态码非零退出。用 Docker 运行测试针对参考 Agent 运行测试docker compose run tests该命令在docker compose up启动时也会自动执行一次。参考 Agent模板与改造起点参考 Agent 源码位于 dc-agents/reference/其独立说明见 dc-agents/reference/README.md。它是一份极简实现用 TypeScript 编写数据来自静态 JSON 文件既可作为测试基准也可作为后端服务开发者的参照。运行要求NodeJS 16本地运行执行npm install npm startDocker 构建运行可执行docker build . -t dc-reference-agent:latest与docker run -it --rm -p 8100:8100 dc-reference-agent:latest。数据集参考 Agent 暴露的是 Chinook 示例数据库Chinook.xml.gz为压缩后的数据源schema 由各数据库厂商 SQL 脚本手工推导。配置参考 Agent 支持通过 HGE 元数据中 source 的configuration.value属性传入配置该配置会在每次请求时以X-Hasura-DataConnector-Config请求头传给 Agent。支持属性默认值可对照 dc-agents/reference/src/config.ts 源码确认属性说明默认值tables要暴露的表名列表省略则暴露全部 Chinook 表null全部暴露schema将表放入指定 schema 名下如[my_schema,Album]省略则不带 schema 命名空间nulldb数据库名省略使用默认 dbnulltable_name_casing表名大小写风格pascal_casecolumn_name_casing列名大小写风格pascal_case仅暴露 Artist 与 Album 表并放到my_schema命名空间下的配置示例{ tables: [Artist, Album], schema: my_schema }暴露全部表且不带命名空间的配置示例{}要改造现有 Agent官方建议先从 dc-agents/reference/src/index.ts 中声明的/capabilities与/schema端点入手——它们分别把实现委托给capabilities.ts和config.ts。参考 Agent 的配置文件说明参考 Agent 支持两种配置一种是本地config.json文件tables过滤表、schema命名空间另一种是运行时通过X-Hasura-DataConnector-Config请求头传入的配置。前者用于本地调试后者用于生产环境——每次请求时 HGE 会把 source 的configuration对象以该请求头发送给 Agent。通过 Metadata 将 Agent 接入 GraphQL Engine参考 Agent 启动后需要把对应元数据导入 HGE。SDK 的docker compose up流程中replace-metadata服务会自动完成这一步POSTmetadata/metadata-api.json到/v1/metadata而手动方式见 dc-agents/DOCUMENTATION.md要点如下backend_configs.dataconnector段可配置任意多个 Agent 的 URI这里定义了一个名为reference的 AgentURI 为http://localhost:8100/创建 source 时kind必须设置为backend_configs.dataconnector中给 Agent 起的名字此处为referencesource 下的configuration可以是任意 JSON 对象HGE 会在每次请求时通过X-Hasura-DataConnector-Config头把它发给 Agent该 JSON 必须符合 Agent 在/capabilities端点声明的配置 Schemasource 的name会通过X-Hasura-DataConnector-SourceName头在每次请求时发送给 Agent用于在 HGE 实例内唯一标识一个 source元数据导入后即可在 GraphiQL 控制台查询数据。SDK 自带的 dc-agents/sdk/metadata/metadata-api.json 已为chinooksourcekind 为reference预置了 Album、Artist、Customer、Employee、Genre、Invoice、InvoiceLine、MediaType、Playlist、PlaylistTrack、Track 等表及其对象/数组关系映射manual_configuration并指向http://reference-agent:8100。示例查询在文档的 README 对应章节中给出query { artists { name albums { title } } }小结Data Connector SDK 为开发者提供了一条低门槛的 Agent 开发路径先用docker compose up一键复现官方推荐的完整环境HGE Postgres 参考 Agent SwaggerUI 测试套件再对照/capabilities、/schema、/query端点与 OpenAPI Schema 理解协议最后以 TypeScript 参考实现为蓝本改造出自己的 Agent并用docker compose run tests持续验证其完整性、正确性与合规性。这套文档 模板 自动化测试的组合正是 HGE 生态得以快速扩展数据库支持的关键基础设施。【免费下载链接】graphql-engineBlazing fast, instant realtime GraphQL APIs on all your data with fine grained access control, also trigger webhooks on database events.项目地址: https://gitcode.com/gh_mirrors/gr/graphql-engine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Hasura Data Connector SDK 完全指南：从零构建、测试与部署 GraphQL Engine 数据连接器 Agent
Hasura Data Connector SDK 完全指南从零构建、测试与部署 GraphQL Engine 数据连接器 Agent【免费下载链接】graphql-engineBlazing fast, instant realtime GraphQL APIs on all your data with fine grained access control, also trigger webhooks on database events.项目地址: https://gitcode.com/gh_mirrors/gr/graphql-engine本篇指南围绕当前仓库 dc-agents/sdk/README.md 展开系统讲解 Hasura GraphQL Engine Data Connector数据连接器Agent 的概念、SDK 组成、基于 Docker Compose 的开发测试工作流以及官方推荐的设计原则。读完你将掌握如何用docker compose up一键拉起参考 Agent 与 HGE、如何运行官方集成测试套件、如何基于 TypeScript 参考实现改造或替换出自己的 Agent并通过 Metadata API 将其接入 GraphQL Engine。什么是 Data Connector AgentData Connector Agent数据连接器代理是一个把数据源抽象在 REST API 与一套明确定义的线上传输格式wire format之后的服务。它扮演 HGE 与数据库之间的中间层middlewareHGE 将查询计划编码为 JSON 请求发送给 AgentAgent 负责对接底层数据源并返回符合规范的 JSON 响应。其核心价值在于无需修改 HGE 核心代码即可扩展数据库支持。开发者通过 HGE 的 Metadata API 在运行时配置 Agent 的 URI就能接入此前不受支持的数据库Agent 甚至可以不依赖任何上游数据库直接提供全新功能。这种服务化架构支持动态重配置——连接哪些 Agent、支持哪些数据库都可以随场景变化而调整非常适合固定驱动集不适用的场景。关于该特性的完整设计与架构说明参见仓库中的 dc-agents/DOCUMENTATION.md官方支持的 Agent 清单见 dc-agents/HUB.md。SDK 的定位与版本管理SDK 是一整套文档 资源的组合包用于帮助开发者理解、构建并测试 Data Connector Agent 实现确保其完整complete、正确correct、符合惯例idiomatic并能快速且有信心地开发。SDK 会随时间演进持续吸收 Hasura 推荐的 Agent 开发最佳实践因此 SDK 本身有版本管理并通过随包附带的.env文件与 Hasura GraphQL EngineHGE版本建立关联——不同版本 SDK 对应不同版本的 HGE、参考 Agent 与测试镜像。推荐工作流从零到跑通SDK 的默认工作流由 Docker Compose 驱动目的是把依赖数量降到最低当然每个组件也都可以脱离 Docker 原生运行。官方推荐的开发流程如下用docker compose up启动整个技术栈检查测试是否通过若计划使用 TypeScript按需修改参考 Agentreference agent或者用你自己的 Agent 实现替换参考 Agent按需重建 Agent 镜像用docker compose run tests重新运行测试通过暴露在 http://localhost:8080 的 GraphQL Engine 与 Agent 交互在 http://localhost:8300 浏览 OpenAPI SchemaSwaggerUI。整套 SDK 本身就是模板可以随意增删改任何组件。SDK 组件全景SDK 以 zip 压缩包形式分发仓库中的 dc-agents/sdk/ 目录即其内容包含以下组件组件说明文档README.md、README_DATA_CONNECTORS.md说明 SDK 组件如何组装、如何启动并运行测试、Data Connector 特性架构OpenAPI 类型agent.openapi.json描述 Agent API 的格式化 JSON Schema参考 Agentreference-agent/TypeScript 实现docker-compose.yaml编排 HGE、PostgresHGE 元数据存储、Agent 测试套件、参考 Agent、SwaggerUI 五个服务.env文件指定 SDK 资源的构建版本号HGE 元数据metadata/用于引导bootstrap把参考 Agent 添加为数据源docker-compose.yaml 逐服务解析仓库中的 dc-agents/sdk/docker-compose.yaml 定义了完整的开发栈reference-agent使用hasura/dc-reference-agent:${HASURA_VERSION}镜像暴露端口8100:8100。文件里预留了# build: ./reference注释——如果你要修改参考 Agent可以启用 Docker Compose 的 build 配置本地构建。postgrespostgres:13作为 HGE 元数据存储密码为postgrespassword数据持久化在命名卷db_data。enginehasura/graphql-engine:${HASURA_VERSION}暴露8080:8080通过HASURA_GRAPHQL_METADATA_DATABASE_URL连接 Postgres并开启 ConsoleHASURA_GRAPHQL_ENABLE_CONSOLE: true与开发模式HASURA_GRAPHQL_DEV_MODE: true日志类型覆盖 startup、http-log、webhook-log、websocket-log、query-log。文件中还注释了 Intel/ARM 特定平台镜像的写法。replace-metadata使用curlimages/curl在 engine 就绪后向http://engine:8080/v1/metadataPOST./metadata/metadata-api.json把参考 Agent 引导进 HGE 元数据restart: on-failure保证失败重试。tests使用hasura/dc-agent-tests:${HASURA_VERSION}镜像执行tests-dc-api test --agent-base-url http://reference-agent:8100即对参考 Agent 跑完整集成测试。swagger-uiswaggerapi/swagger-ui:v4.10.3挂载./agent.openapi.json暴露8300:8080。若你是原生 Docker混合部署尤其是开发自己的 Agent 时需要注意Docker 服务要正确暴露端口且当 Docker 服务指向原生服务时要使用合适的主机 URI例如host.docker.internal。Agent 开发与架构的通用原则参考 Agent 给出了一个 Agent 能做什么、应该怎么开发的完整示例但官方还总结了以下推荐原则指导 Agent 的结构与演进自描述能力Capabilities Self DescribingAgent 必须通过capabilities特性描述自身能力无状态StatelessAgent 应该是透明地无状态的每个请求自带执行所需的全部信息逻辑下沉Defer logic to backend尽可能把处理逻辑下放到后端数据库类型安全Type-safe严格按 OpenAPI Schema 中描述的类型进行接收与返回向后兼容Backwards compatible演进过程中保持向后兼容测试Testing必须用官方提供的测试套件进行测试。自描述/capabilities 与 /schema 端点参考 Agent 的入口是 dc-agents/reference/src/index.ts一个基于 Fastify 的 HTTP 服务从静态 JSON 文件加载 Chinook 数据集。其核心端点包括GET /capabilities返回 Agent 的能力声明以及X-Hasura-DataConnector-Config请求头所携带配置的 JSON SchemaPOST /schema返回数据 schema 信息表、列请求体可携带配置POST /query接收编码为 JSON 的查询结构并执行返回请求的字段GET /health健康检查POST /mutation数据变更请求文档中标注为 DEPRECATED 的旧版GET /schema也存在。其中/capabilities的具体声明在 dc-agents/reference/src/capabilities.ts声明支持主键/外键、可空与不可空列nullable_and_non_nullable、foreach 查询、redaction、基于关系的子查询supports_relations: true并为DateTime、string、number三类标量类型声明了各自的比较运算符如same_day_as、in_year、聚合函数max、min、stddev、sum等与更新列运算符inc。/capabilities响应中还包含config_schemas即对配置 JSON 的 Schema 描述见 dc-agents/reference/src/config.ts。OpenAPI Schema 与类型Agent API 的 OpenAPI Schema 与类型集中定义在一个格式化 JSON 文件中agent.openapi.json。除了该文件本身SDK 还通过docker-compose.yaml内置了 SwaggerUI 界面启动后可在 http://localhost:8300 交互式浏览和调试该 Schema。这也是开发阶段对照协议最直观的工具。运行集成测试套件测试架构要求先有一个正在运行的 Agent测试套件再指向该 Agent 执行一系列集成测试。测试逻辑遵循以下规则首先对 Agent 运行若干强制mandatory场景若未给测试套件额外选项它会自动发现 Agent 的能力见 DOCUMENTATION.md 的 Capabilities 章节遍历其声明的能力并运行对应测试验证这些能力是否被正确实现若声明了非法能力则报告错误能力也可以通过测试套件的 CLI 选项显式列出——此时无论 Agent 如何声明都会测试这些列出的能力并展示列出能力与声明能力的差异。这对于确认 Agent 声明的能力符合你的预期非常有用若发现错误会随测试运行打印出来只要遇到任何错误进程就会设置错误状态码非零退出。用 Docker 运行测试针对参考 Agent 运行测试docker compose run tests该命令在docker compose up启动时也会自动执行一次。参考 Agent模板与改造起点参考 Agent 源码位于 dc-agents/reference/其独立说明见 dc-agents/reference/README.md。它是一份极简实现用 TypeScript 编写数据来自静态 JSON 文件既可作为测试基准也可作为后端服务开发者的参照。运行要求NodeJS 16本地运行执行npm install npm startDocker 构建运行可执行docker build . -t dc-reference-agent:latest与docker run -it --rm -p 8100:8100 dc-reference-agent:latest。数据集参考 Agent 暴露的是 Chinook 示例数据库Chinook.xml.gz为压缩后的数据源schema 由各数据库厂商 SQL 脚本手工推导。配置参考 Agent 支持通过 HGE 元数据中 source 的configuration.value属性传入配置该配置会在每次请求时以X-Hasura-DataConnector-Config请求头传给 Agent。支持属性默认值可对照 dc-agents/reference/src/config.ts 源码确认属性说明默认值tables要暴露的表名列表省略则暴露全部 Chinook 表null全部暴露schema将表放入指定 schema 名下如[my_schema,Album]省略则不带 schema 命名空间nulldb数据库名省略使用默认 dbnulltable_name_casing表名大小写风格pascal_casecolumn_name_casing列名大小写风格pascal_case仅暴露 Artist 与 Album 表并放到my_schema命名空间下的配置示例{ tables: [Artist, Album], schema: my_schema }暴露全部表且不带命名空间的配置示例{}要改造现有 Agent官方建议先从 dc-agents/reference/src/index.ts 中声明的/capabilities与/schema端点入手——它们分别把实现委托给capabilities.ts和config.ts。参考 Agent 的配置文件说明参考 Agent 支持两种配置一种是本地config.json文件tables过滤表、schema命名空间另一种是运行时通过X-Hasura-DataConnector-Config请求头传入的配置。前者用于本地调试后者用于生产环境——每次请求时 HGE 会把 source 的configuration对象以该请求头发送给 Agent。通过 Metadata 将 Agent 接入 GraphQL Engine参考 Agent 启动后需要把对应元数据导入 HGE。SDK 的docker compose up流程中replace-metadata服务会自动完成这一步POSTmetadata/metadata-api.json到/v1/metadata而手动方式见 dc-agents/DOCUMENTATION.md要点如下backend_configs.dataconnector段可配置任意多个 Agent 的 URI这里定义了一个名为reference的 AgentURI 为http://localhost:8100/创建 source 时kind必须设置为backend_configs.dataconnector中给 Agent 起的名字此处为referencesource 下的configuration可以是任意 JSON 对象HGE 会在每次请求时通过X-Hasura-DataConnector-Config头把它发给 Agent该 JSON 必须符合 Agent 在/capabilities端点声明的配置 Schemasource 的name会通过X-Hasura-DataConnector-SourceName头在每次请求时发送给 Agent用于在 HGE 实例内唯一标识一个 source元数据导入后即可在 GraphiQL 控制台查询数据。SDK 自带的 dc-agents/sdk/metadata/metadata-api.json 已为chinooksourcekind 为reference预置了 Album、Artist、Customer、Employee、Genre、Invoice、InvoiceLine、MediaType、Playlist、PlaylistTrack、Track 等表及其对象/数组关系映射manual_configuration并指向http://reference-agent:8100。示例查询在文档的 README 对应章节中给出query { artists { name albums { title } } }小结Data Connector SDK 为开发者提供了一条低门槛的 Agent 开发路径先用docker compose up一键复现官方推荐的完整环境HGE Postgres 参考 Agent SwaggerUI 测试套件再对照/capabilities、/schema、/query端点与 OpenAPI Schema 理解协议最后以 TypeScript 参考实现为蓝本改造出自己的 Agent并用docker compose run tests持续验证其完整性、正确性与合规性。这套文档 模板 自动化测试的组合正是 HGE 生态得以快速扩展数据库支持的关键基础设施。【免费下载链接】graphql-engineBlazing fast, instant realtime GraphQL APIs on all your data with fine grained access control, also trigger webhooks on database events.项目地址: https://gitcode.com/gh_mirrors/gr/graphql-engine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考