> For the complete documentation index, see [llms.txt](https://docs.zongsoft.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zongsoft.com/framework/data/connections.md).
# 连接配置
配置数据连接、驱动和读写分离。
数据连接配置项名称与访问器名称匹配（取得方式见[数据访问接口](/framework/data/data-access.md)）。一个 `DataAccess` 可以拥有多个数据源，用于读写分离等场景。
## 配置位置
连接配置位于 `/Data/ConnectionSettings` 选项路径下。`DataAccessProvider` 获取访问器时会从当前应用配置读取该集合：
```
/Data/ConnectionSettings
```
如果调用 `GetService(null)` 时没有指定名称，会使用默认连接；如果指定名称不存在，也会回退到默认连接。没有默认连接且指定名称不存在时会抛出数据配置异常。
访问器名称如何匹配连接配置？
Discussions 传入的访问器名来自 Module.NAME。没有传入名称或指定名称不存在时，会按提供者规则使用默认连接；因此不能仅凭业务代码中的模块名推断实际连接到了哪个数据库。需要强隔离的部署应核对最终匹配项，避免意外回退。
## 单数据源
Discussions 的 Module.Accessor 按模块名取得访问器：
来源：[src/Module.cs](https://github.com/Zongsoft/Zongsoft.Discussions/blob/main/src/Module.cs#L52)（节选；上下文见源文件）。
{% code title="Module.cs" %}
```csharp
public IDataAccess Accessor => _accessor ??= this.Services.ResolveRequired().GetAccessor(this.Name);
```
{% endcode %}
下列 db1 配置来自 framework 的 XML 解析测试，用于解释 option 结构；它不是 Discussions 的现成数据库连接。部署 Discussions 时应配置对应访问器名称或明确默认连接，驱动与实际数据库环境一起核对。
来源：[framework/Zongsoft.Core/test/Configuration/Xml/OptionConfigurationTest-1.option](https://github.com/Zongsoft/framework/blob/main/Zongsoft.Core/test/Configuration/Xml/OptionConfigurationTest-1.option#L30)（节选；上下文见源文件）。
{% code title="OptionConfigurationTest-1.option" %}
```xml
```
{% endcode %}
`connectionSetting.name` 应与数据访问名称一致。业务模块通常用模块名作为数据访问名称，例如 `Security`、`Administratives` 或 `Discussions`。
## 连接字符串属性
`value` 是传给对应驱动的连接字符串，通常由分号分隔的键值项组成。连接设置对象会把这些键值项映射到驱动定义的属性，并按属性类型转换，例如端口、布尔值、时间间隔、网络端点或集合。
来源：[framework/Zongsoft.Core/test/Configuration/ConnectionSettingsTest.cs](https://github.com/Zongsoft/framework/blob/main/Zongsoft.Core/test/Configuration/ConnectionSettingsTest.cs#L16)（节选；上下文见源文件）。
{% code title="ConnectionSettingsTest.cs" %}
```csharp
private static readonly DateTime DATE = new(1979, 5, 15);
private static readonly string ConnectionString = $" ;; server=192.168.0.1:8080, localhost:8088 ; Integer=100 ; enabled ; double= 1.23; ; boolean= true ; text= MyString; dateTime={DATE:yyyy-M-d}; ; mapping=s1:t1,s2 = t2, same ";
```
{% endcode %}
集合属性可以写成一个文本值，放在连接字符串 `value` 内时通常使用逗号或竖线分隔元素，因为分号已经被外层连接项用作分隔符；具体元素如何转换由属性类型或属性上声明的转换器决定。驱动如果为某个集合属性声明了元素转换器，就可以把 `mapping=s1:t1,s2=t2,same` 这类短格式解析成结构化条目。
上面的 DATE 和 ConnectionString 来自 ConnectionSettingsTest，其 MyDriver 是测试驱动，不能用来连接 MySQL。这个输入用于检验空白、布尔值、端点集合和元素转换。
驱动设置对象还可以把多个扁平键组装成一个复合属性。下面的框架测试不会要求连接字符串里出现完整的 cluster 值，而是用 `cluster.` 前缀为 `Cluster` 属性填充子成员：
来源：[framework/Zongsoft.Core/test/Configuration/ConnectionSettingsTest.cs](https://github.com/Zongsoft/framework/blob/main/Zongsoft.Core/test/Configuration/ConnectionSettingsTest.cs#L178)（节选；上下文见源文件）。
{% code title="ConnectionSettingsTest.cs" %}
```csharp
public void TestConnectionSettingsCompositeProperty()
{
var settings = MyDriver.Instance.GetSettings("a.b.c=none;cluster.address=192.168.0.100;nothing.property=none;cluster.heartbeat=30s");
Assert.NotNull(settings);
Assert.False(settings.Cluster.IsEmpty);
Assert.Equal("192.168.0.100", settings.Cluster.Address);
Assert.Equal(TimeSpan.FromSeconds(30), settings.Cluster.Heartbeat);
Assert.Equal("none", settings.Properties["a.b.c"]);
Assert.Equal("none", settings.Properties["nothing.property"]);
}
```
{% endcode %}
这类写法适合描述集群、证书、代理、重试策略等结构化设置。能否使用取决于驱动的连接设置类是否定义了对应属性，以及该属性类型是否可以被自动创建并写入公共成员。
## 读写分离
连接名称使用 `#` 追加数据源标识。应保留与访问器同名的基础连接，因为默认访问器工厂先检查精确连接名；仅配置后缀项可能在取得访问器时回退或失败：
当前 Discussions 没有配置读写副本的完整用例。部署者可以通过同一访问器名称下的数据源设置 Mode；实际筛选逻辑见 [DataSourceProvider](https://github.com/Zongsoft/framework/blob/main/Zongsoft.Data/src/Common/DataSourceProvider.cs) 与 [DataSourceSelector](https://github.com/Zongsoft/framework/blob/main/Zongsoft.Data/src/Common/DataSourceSelector.cs)。数据库复制、故障切换和读后写一致性仍由基础设施及业务约定保证。
`mode="WriteOnly"` 的数据源用于写入，`mode="ReadOnly"` 的数据源用于读取。驱动和数据源提供器会根据操作类型选择合适的数据源。
## 驱动名称
`driver` 属性必须匹配已部署驱动注册的名称。例如 MySQL 驱动插件会注册：
* `/Workbench/Configuration/ConnectionSettings/Drivers/MySql`
* `/Workbench/Data/Drivers/MySql`
如果插件目录中没有部署对应驱动，连接字符串即使正确也无法被解析和执行。
{% content-ref url="/pages/UWZab2cpmLjNJd0dDlb2" %}
[按驱动阅读](/framework/data/drivers.md)
{% endcontent-ref %}
## 注意事项
连接字符串由对应数据库驱动解释。配置时应同时确认驱动包已经部署到宿主插件目录。
生产环境中建议把敏感信息交给环境配置、密钥系统或部署平台注入，避免把账号密码提交到源码仓库。
配置文件里可以放真实连接串吗？
开发环境可以使用本地测试连接串，但生产环境不建议把账号、密码、访问密钥写入仓库。更稳妥的做法是由部署平台、环境变量、密钥管理服务或站点级配置注入敏感值。
## 路由与一致性
数据源提供器选择精确名称及 `名称#后缀` 项，再按操作从可读或可写集合选择数据源。查询、存在判断和聚合走可读源；命名命令根据映射中的 mutability 路由。只读命令应明确写 `mutability="none"`，详见[映射文件](/framework/data/mapping.md)。
读写分离依赖数据库自身的复制与一致性策略。刚写完立即读取可能受到复制延迟影响；需要读到本次写入时，应根据业务的事务和数据源方案处理，不能认为配置多个连接就自动保证强一致。
## 连接故障保护
当前引擎通过 DataConnector 管理物理连接建立。同一数据源的连接建立受串行保护，失败后的一段时间内可快速拒绝后续连接，避免大量请求同时冲击不可用数据库。
首次物理连接失败通常保留数据库提供程序的原始异常；熔断期间快速拒绝使用 DataConnectionException，可读取 RetryAt、RetryAfter 等信息。恢复数据库后仍应考虑重试等待时间，不要把每次快速拒绝都当成新的网络故障。
实现定位：[连接名筛选](https://github.com/Zongsoft/framework/blob/main/Zongsoft.Data/src/Common/DataSourceProvider.cs)、[分隔符和访问模式](https://github.com/Zongsoft/framework/blob/main/Zongsoft.Data/src/Common/DataSource.cs)、[访问器名称](https://github.com/Zongsoft/framework/blob/main/Zongsoft.Core/src/Data/DataAccessProviderBase.cs)、[连接保护](https://github.com/Zongsoft/framework/blob/main/Zongsoft.Data/src/Common/DataConnector.cs)。
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.zongsoft.com/framework/data/connections.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.