企业官网建设流程全解析

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 可以通过以下三种方式注入：

三者优先级从高到低为：--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 与 Envelope

2.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(envelope=True)输出这一信封结构（对应 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_mode=CONCAT(@@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 依赖。它默认以autocommit=True打开连接，避免长连接停留在idle in transaction状态。另外，DataSource.get_connection_info会自动为 postgres 补上connect_timeout=120与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字段的别名（Pydanticalias="schema"），因此 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" }

对应 RedshiftConnectionInfo，redshift_type固定为redshift（可省略，默认即标准模式），注意其端口默认为 5439，与 PostgreSQL 不同。

3.6 Redshift（IAM 认证）

{ "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_identifier+access_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及其底层模块：

每个连接器都必须实现 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）。

五、连接配置的最佳实践与常见误区

1. datasource必须存在且拼写正确：它是连接器分发（dispatch）的唯一依据；未知取值会触发Unsupported data source错误（factory.py）。
2. 凭证字段优先放文件，不要放进 shell 历史：内联--connection-info适合快速验证，但生产环境建议用--connection-file指向权限受限的文件；模型层将所有password、credentials、access_token等字段声明为 PydanticSecretStr（敏感字段在wren docs输出中会被标记为Sensitive: yes），尽量避免明文外泄。
3. 两种格式任选其一，但 MCP / Web 生态固定用信封格式：CLI 会自动展平，因此两边配置文件可以互换；如果你编写的 JSON 会被 MCP Server 或 Wren Web 消费，请使用{"datasource": ..., "properties": {...}}。
4. URL 式连接信息同样可用：部分数据源支持connectionUrl/connection_url字段（如 ClickHouse 的clickhouse://、clickhouse+http(s)://方案），见 data_source.py；ClickHouse 还会对 URL 中的用户名/密码做unquote解码，避免+被误当作空格。
5. 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