Storage.RelationDb

关系型数据库存储

NuGet：Shashlik.EventBus.RelationDbStorage

所有关系型数据库（MySQL / PostgreSQL / SqlServer / Sqlite / Oracle 等）已统一到本包，不再需要为每种数据库引入独立存储包。

说明

Shashlik.EventBus.RelationDbStorage 基于 FreeSql 实现跨数据库支持，FreeSql 仅在 EventBus 内部使用，对业务系统本身无侵入。你的业务代码可以继续使用 EF Core、Dapper 或任何其他 ORM，互不影响。唯一需要做的就是在项目中引入 FreeSql 对应数据库的 Provider 包，确保 EventBus 内部能够正确连接数据库。

⚠️ FreeSql Provider 驱动一致性

需自行引入对应数据库的 FreeSql Provider 包。

FreeSql Provider 文档：https://freesql.net/guide/freesql-provider-mysqlconnector.html

重要：FreeSql Provider 使用的底层 ADO.NET 驱动必须与应用本身使用的驱动一致！

驱动不一致会导致连接池冲突、类型映射异常等不可预期的问题。

以 MySQL 为例：

• 应用使用 Pomelo.EntityFrameworkCore.MySql（底层驱动为 MySqlConnector）→ FreeSql 应引入 FreeSql.Provider.MySqlConnector
• 应用使用官方 MySql.Data 驱动 → FreeSql 应引入 FreeSql.Provider.MySql

其他数据库同理：如果 EF Core / 应用层 ORM 使用的是某种 ADO.NET 驱动，FreeSql Provider 也必须使用基于同一驱动的版本。常见对照：

数据库	应用用 Connector 驱动	应用用官方驱动
MySQL	FreeSql.Provider.MySqlConnector	FreeSql.Provider.MySql
PostgreSQL	FreeSql.Provider.PostgreSQL (Npgsql)	—
SqlServer	FreeSql.Provider.SqlServer (System.Data.SqlClient)	FreeSql.Provider.MicrosoftData.SqlClient
Sqlite	FreeSql.Provider.Sqlite (Microsoft.Data.Sqlite)	—

务必根据应用实际使用的底层驱动选择对应的 FreeSql Provider！

注册方式

方式一：直接指定数据库类型和连接字符串

services.AddEventBus()
    .AddRelationDb(options => options.UseConnection(DataType.MySql, "Server=...;Database=...;Uid=...;Pwd=...;"));

DataType 枚举值包括：MySql、PostgreSQL、SqlServer、Sqlite、Oracle、Dameng 等，详见 FreeSql 文档。

方式二：通过 EF Core DbContext 获取连接信息

需引入包 Shashlik.EventBus.Extensions.EfCore：

services.AddEventBus()
    .AddRelationDb<TDbContext>(DataType.MySql);

此方式自动从 DbContext 中获取连接字符串，同时可使用 DbContext.PublishEventAsync() 等扩展方法。

方式三：自定义连接工厂

services.AddEventBus()
    .AddRelationDb(options => options.UseConnection(typeof(MyConnectionFactory)));

自定义工厂需实现 IConnectionFactory 接口。

配置项 EventBusRelationDbOptions

配置项	默认值	说明
DataType	无（必填）	FreeSql 方言类型
ConnectionString	无（必填）	数据库连接字符串
ConnectionFactory	null	自定义连接工厂类型，优先级高于 ConnectionString
Schema	"" (空)	数据库 Schema（PostgreSQL / SqlServer 等）
PublishedTableName	eventbus_published	已发布消息表名
ReceivedTableName	eventbus_received	已接收消息表名

事务上下文

关系型数据库事务上下文为 RelationDbStorageTransactionContext，基于 IDbTransaction。

获取方式详见 事件发布 - 事务集成。

存储表结构

RelationDbStorage 启动时通过 IMessageStorageInitializer 自动创建消息表。内部时间字段使用 UTC ticks (long) 持久化，以兼容各数据库方言。

已发布消息表（默认 eventbus_published）：

字段	类型	说明
Id	long	存储 ID (雪花 ID)
MsgId	string	全局唯一消息 ID
Environment	string	环境标识
EventName	string	事件名称
EventBody	string	事件内容 (JSON)
CreateTimeTicks	long	创建时间 (UTC ticks)
IsDelay	bool	是否延迟消息
DelayAtTicks	long?	延迟执行时间 (UTC ticks)
ExpireTimeTicks	long?	过期时间 (UTC ticks)
EventItems	string	附加数据 (JSON)
Status	string	状态
RetryCount	int	已重试次数
IsLocking	bool	是否已锁定
LockEndTicks	long?	锁定结束时间 (UTC ticks)

已接收消息表（默认 eventbus_received）额外包含 EventHandlerName 字段。