WrenAI 连接配置完全指南connection_info 格式、数据源参数与连接器实现原理【免费下载链接】WrenAIGenBI (Generative BI) for AI agents, an open-source, governed text-to-SQL through an open context layer that turns natural-language questions into trusted dashboards, charts, and SQL across 20 data sources, such as BigQuery, Snowflake, PostgreSQL, ClickHouse, Amazon Redshift, Databricks and more.项目地址: https://gitcode.com/GitHub_Trending/wr/WrenAI本文是 WrenAI 开源项目GenBI面向 AI Agent 的治理化 Text-to-SQL 语义层的连接配置权威指南覆盖connection_info.json的两种 JSON 组织格式、各数据源MySQL、PostgreSQL、BigQuery、Snowflake、Redshift、DuckDB 等的逐字段连接参数以及 CLI 中--connection-info/--connection-file的实际用法。读完本文你将能独立编写任意受支持数据源的连接配置、理解信封envelope格式为何被 MCP Server 与 Wren Web 采用并透过源码看清连接参数如何映射到底层驱动。一、连接信息的三种注入方式在 WrenAI 中所有数据库连接信息最终都以一个 JSON 对象表示其顶层必须包含datasource字段用于告诉引擎要使用哪一个连接器。该 JSON 可以通过以下三种方式注入注入方式说明~/.wren/connection_info.json默认位置由WREN_HOME环境变量可覆盖默认~/.wren见 cli.py 的_WREN_HOME/_DEFAULT_CONN定义--connection-file path显式指定连接文件路径--connection-info json在命令行内联传递 JSON 字符串三者优先级从高到低为--connection-info--connection-file~/.wren/connection_info.json自动发现。从源码看_load_conn会先尝试解析内联 JSON再回落文件读取最后才使用默认路径自动发现文件不存在或 JSON 非法时均会以typer.Exit(1)报错退出。# 方式一默认路径 ~/.wren/connection_info.json wren --sql SELECT COUNT(*) FROM orders # 方式二显式文件 wren --sql SELECT COUNT(*) FROM orders \ --connection-file /path/to/prod-connection_info.json # 方式三内联 JSON wren --sql SELECT COUNT(*) FROM orders \ --connection-info {datasource:mysql,host:localhost,port:3306,database:mydb,user:root,password:secret}二、两种被接受的 JSON 格式Flat 与 Envelope2.1 Flat 格式平铺格式所有连接字段平铺在顶层结构最简单适合手工编写{ datasource: postgres, host: localhost, port: 5432, database: mydb, user: postgres, password: secret }2.2 Envelope 格式信封格式连接字段嵌套在properties键下这是MCP Server 和 Wren Web采用的标准形态{ datasource: postgres, properties: { host: localhost, port: 5432, database: mydb, user: postgres, password: secret } }2.3 CLI 的自动展平机制两种格式均被接受。CLI 在加载连接信息后会调用_normalize_conn只要 JSON 中存在properties且其值为 dict就会把datasource与properties内的字段合并成平铺形态再交给后续逻辑。也就是说信封格式的{datasource: duckdb, properties: {url: /data, format: duckdb}}会被自动解包为{datasource: duckdb, url: /data, format: duckdb}生成连接文档的命令wren docs connection-info --envelope正是利用generate_json_schema(envelopeTrue)输出这一信封结构对应 CLI 文档见 docs_cli.py。小贴士datasource字段决定引擎选用哪个连接器模块。在 factory.py 的_REGISTRY中datasource与连接器模块一一映射若该数据源需要额外依赖get_connector还会抛出提示引导你执行pip install wrenai[extra]。三、各数据源连接字段详解Per-connector Fields以下示例字段均以 Flat 格式给出可原样放进connection_info.json或--connection-info。字段定义来自 model/init.py 中的 Pydantic 模型均可通过wren docs connection-info生成权威参考。3.1 MySQL{ datasource: mysql, host: localhost, port: 3306, database: mydb, user: root, password: secret }从 MySqlConnectionInfo 看host默认为localhost、port默认3306还支持sslMode默认ENABLED与sslCA可选字段。实现层面MySqlConnector 使用 MySQLdb 驱动直连当host为localhost时会被归一化为127.0.0.1强制走 TCP避免落入 unix socket并在初始化时执行SET sql_modeCONCAT(sql_mode, ,ANSI_QUOTES)使 MDL 中双引号引用的标识符能被 MySQL 接受。Doris 因为同样讲 MySQL 协议直接复用该连接器的查询路径仅连接打开方式不同因此datasource也可以是doris。3.2 PostgreSQL{ datasource: postgres, host: localhost, port: 5432, database: mydb, user: postgres, password: secret }PostgresConnectionInfo 对应的 PostgresConnector 基于 psycopg3 原生实现摆脱了 ibis-framework 依赖。它默认以autocommitTrue打开连接避免长连接停留在idle in transaction状态。另外DataSource.get_connection_info会自动为 postgres 补上connect_timeout120与statement_timeout默认 180 秒可通过x-wren-db-statement_timeout请求头覆盖确保慢查询不会长期占用会话。3.3 BigQuery{ datasource: bigquery, project_id: my-gcp-project, dataset_id: my_dataset, credentials: base64-encoded-service-account-json }credentials是base64 编码后的服务账号 JSON。从 BigQueryConnector 可以看到连接器会base64.b64decode还原 JSON再用service_account.Credentials.from_service_account_info构建凭据并附加 drive 与 cloud-platform 两个 scope。project_id/dataset_id对应 BigQueryDatasetConnectionInfo。如果你需要按整个 GCP 项目查询而非限定单一 dataset可以在配置中加bigquery_type: project并改传region与billing_project_id引擎会据此切换到 BigQueryProjectConnectionInfo。_build_connection_info正是通过bigquery_type字段来做判别见 data_source.py。3.4 Snowflake{ datasource: snowflake, user: myuser, password: secret, account: myorg-myaccount, database: MYDB, schema: PUBLIC }SnowflakeConnectionInfo 支持的可选字段还包括warehouse与private_key私钥认证以及透传的kwargs。schema是sf_schema字段的别名Pydanticaliasschema因此 JSON 中直接写schema即可与官方 Snowflake 术语保持一致。3.5 Redshift标准账号密码认证{ datasource: redshift, host: my-cluster.xxxx.us-east-1.redshift.amazonaws.com, port: 5439, database: dev, user: awsuser, password: secret }对应 RedshiftConnectionInforedshift_type固定为redshift可省略默认即标准模式注意其端口默认为 5439与 PostgreSQL 不同。3.6 RedshiftIAM 认证{ datasource: redshift, redshift_type: redshift_iam, cluster_identifier: my-cluster, database: dev, user: awsuser, region: us-east-1, access_key_id: AKIA..., access_key_secret: secret }当redshift_type为redshift_iam时引擎会改用 RedshiftIAMConnectionInfo通过 AWScluster_identifieraccess_key_id/access_key_secret临时换取 IAM 凭据无需在配置中保存数据库口令。判别逻辑见 data_source.py。3.7 DuckDB本地文件{ datasource: duckdb, url: /path/to/data, format: parquet }DuckDB 走本地文件路径而非网络连接。LocalFileConnectionInfo 中url默认/format支持csv、parquet、json、duckdb。特别地当format为duckdb时DuckDBConnector 会扫描该目录下所有.duckdb文件大小写不敏感并把每个文件以ATTACH DATABASE ... (READ_ONLY)方式挂载为只读数据库表别名取自文件名同名冲突时自动追加_1、_2后缀。该连接器同样被local_file、s3_file、minio_file、gcs_file等datasource复用分别通过 S3FileConnectionInfo、MinioFileConnectionInfo、GcsFileConnectionInfo 注入对象存储访问凭据。四、datasource 与连接器 / 依赖的映射关系从 factory.py 的_REGISTRY可以完整列出当前仓库支持的全部datasource及其底层模块datasource连接器模块备注postgreswren.connector.postgrespsycopg3mysql/doriswren.connector.mysqlMySQLdbDoris 复用mssqlwren.connector.mssqlcannerwren.connector.canner需要wrenai[postgres]extrabigquerywren.connector.bigquery服务账号认证datafusionwren.connector.datafusionlocal_file/s3_file/minio_file/gcs_file/duckdbwren.connector.duckdb本地或对象存储文件redshiftwren.connector.redshift含 IAM 变体sparkwren.connector.sparkdatabrickswren.connector.databrickstoken 或 service_principal 变体trinowren.connector.trinoclickhousewren.connector.clickhouseoraclewren.connector.oraclesnowflakewren.connector.snowflakeathenawren.connector.athena每个连接器都必须实现 ConnectorABC 的query(sql, limit)、dry_run(sql)与close()三个抽象方法返回值统一为 PyArrowpa.Table。依赖安装提示也由factory.py给出当importlib.import_module因缺少依赖失败时会抛出pip install wrenai[extra]指引其中doris→mysql、canner→postgres、local_file/s3_file/minio_file/gcs_file→duckdb见_INSTALL_EXTRA。五、连接配置的最佳实践与常见误区datasource必须存在且拼写正确它是连接器分发dispatch的唯一依据未知取值会触发Unsupported data source错误factory.py。凭证字段优先放文件不要放进 shell 历史内联--connection-info适合快速验证但生产环境建议用--connection-file指向权限受限的文件模型层将所有password、credentials、access_token等字段声明为 PydanticSecretStr敏感字段在wren docs输出中会被标记为Sensitive: yes尽量避免明文外泄。两种格式任选其一但 MCP / Web 生态固定用信封格式CLI 会自动展平因此两边配置文件可以互换如果你编写的 JSON 会被 MCP Server 或 Wren Web 消费请使用{datasource: ..., properties: {...}}。URL 式连接信息同样可用部分数据源支持connectionUrl/connection_url字段如 ClickHouse 的clickhouse://、clickhousehttp(s)://方案见 data_source.pyClickHouse 还会对 URL 中的用户名/密码做unquote解码避免被误当作空格。SSL 与超时字段按需补充MySQL 可通过sslMode/sslCA启用 CA 校验PostgreSQL、ClickHouse、Trino、BigQuery 则支持通过x-wren-db-statement_timeout请求头统一调整语句超时默认 180 秒源码见 data_source.py。六、验证连接配置dry-run 与连接文档生成wren dry-run --sql ...对活动数据库做只读验证不返回数据行。连接配置正确时输出OK失败则输出Error: reason是排查连接参数最快的方式。wren docs connection-info基于 Pydantic 模型元数据自动生成各数据源的字段表Field / Type / Required / Default / Sensitive / Alias / Example与示例 JSON实现见 docs.py加--envelope可输出信封格式。它不仅是文档工具也是你在写连接配置时最权威的“字段字典”。还可以配合 CLI 参考文档 中wren dry-plan纯方言转换、无需数据库连接先验证 MDL 到目标方言的翻译链路再落库执行。掌握上述格式与字段之后你便可以在 WrenAI 中无缝接入 20 数据源并用同一套信封结构让 CLI、MCP Server 与 Wren Web 共享连接配置。【免费下载链接】WrenAIGenBI (Generative BI) for AI agents, an open-source, governed text-to-SQL through an open context layer that turns natural-language questions into trusted dashboards, charts, and SQL across 20 data sources, such as BigQuery, Snowflake, PostgreSQL, ClickHouse, Amazon Redshift, Databricks and more.项目地址: https://gitcode.com/GitHub_Trending/wr/WrenAI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考