CircleCI环境执行dbt docs generate失败的相关技术问题咨询

1. 本次Database Error的具体含义 #

本次报错的Database Error是dbt在执行文档生成流程的初始化阶段，尝试和profiles.yml中配置的目标数据库建立连接时，触发了连接超时阈值，最终连接建立失败，导致任务终止。该错误属于底层连接层面的故障，不是SQL逻辑执行报错。

2. 连接超时的常见触发原因 #

• CircleCI运行环境的访问权限受限：CircleCI任务的出口IP没有被添加到目标数据库的访问白名单中，或者CI环境的防火墙规则禁止访问数据库对应的IP和端口
• 数据库侧负载饱和：目标数据库此时的活跃连接数已经达到上限，没有空闲资源处理新的连接请求，导致请求排队超时
• 网络链路故障：CircleCI环境到目标数据库的公网/专线网络出现丢包、拥塞，连接握手请求无法在dbt默认的超时时间内得到响应
• 数据库处于不可用状态：数据库正在进行重启、维护、版本升级等操作，暂时无法响应外部连接请求

3. dbt docs generate需要连接数据库的原因 #

很多人误以为dbt docs generate只需要读取本地的项目配置、模型文件即可生成文档，实际该命令需要连接数据库的原因如下：

• 需要查询数据库的INFORMATION_SCHEMA系统表，拉取项目中涉及的表、视图的真实元数据，包括字段类型、分区规则、存储大小等信息，补充到生成的文档内容中
• 校验本地定义的模型、数据源的结构和数据库中实际的表结构是否一致，避免生成的文档内容和线上实际表结构存在差异
• 如果你在项目中配置了persist_docs参数，dbt还会拉取已经写入到数据库表、字段级的注释内容，同步到文档中，保证内容一致性

内容的提问来源于stack exchange，提问作者Jwan622