学习如何配置和管理ORMX的数据库连接，包括SQLite、MySQL、PostgreSQL、SQL Server和MongoDB。 关键字:数据库连接, 连接字符串, 连接池, MongoDB连接, 资源管理

第四章：数据库连接

4.1 数据库提供程序

ORMX 通过数据库提供程序支持多种数据库。每个提供程序都实现了 IDbProvider 接口，提供了特定数据库的 SQL 语法和功能。

4.1.1 IDbProvider 接口

IDbProvider 接口定义了数据库提供程序的核心功能：

public interface IDbProvider
{
    // 获取自增ID的SQL查询
    string IdentitySelectQuery { get; }

    // 生成分页查询
    string BuildPagedQuery(string query, int pageNumber, int pageSize);

    // 获取参数前缀
    string ParameterPrefix { get; }
    
    // 格式化表名
    string FormatTableName(string tableName);
    
    // 格式化列名
    string FormatColumnName(string columnName);
    
    // 创建类型映射器
    IDbTypeMapper CreateTypeMapper();
    
    // 创建表管理器
    ITableManager GetTableManager();
    
    // 创建数据库连接
    DbConnection CreateConnection();
}

4.1.2 SQLite 提供程序

ORMX 提供了两种连接管理方式：

方式一：传入连接字符串（推荐）

using JCode.ORMX.DataProviders.SQLite;

// 创建数据库提供程序（内部自动创建连接）
using var provider = new SqliteDatabaseProvider("Data Source=:memory:");

// 获取表管理器（无需额外参数）
var tableManager = provider.GetTableManager();

// 获取表对象
var userTable = tableManager.Table<User>();

方式二：传入已创建的连接实例

using JCode.ORMX.DataProviders.SQLite;
using Microsoft.Data.Sqlite;

// 创建数据库连接
using var connection = new SqliteConnection("Data Source=:memory:");
connection.Open();

// 创建数据库提供程序
using var provider = new SqliteDatabaseProvider(connection);

// 获取表管理器
var tableManager = provider.GetTableManager();

// 获取表对象
var userTable = tableManager.Table<User>();

SQLite 连接字符串：

// 内存数据库（测试用）
"Data Source=:memory:"

// 文件数据库
"Data Source=mydatabase.db"

// 带密码的数据库
"Data Source=mydatabase.db;Password=mypassword;"

SqliteDatabaseProvider 类的主要方法：

public class SqliteDatabaseProvider : DbProviderBase, IDisposable
{
    // 构造函数：传入连接字符串
    public SqliteDatabaseProvider(string connectionString)
    
    // 构造函数：传入已创建的连接实例
    public SqliteDatabaseProvider(DbConnection connection)
    
    // 获取表管理器（无需额外参数）
    public ITableManager GetTableManager()
    
    // 获取 SQL 执行器
    public ISqlExecutor GetSqlExecutor()
    
    // 释放资源
    public void Dispose()
}

设计优势：

• 简化 API：无需手动创建 SqlExecutor，内部自动管理
• 资源管理：实现 IDisposable，支持 using 语句自动释放资源
• 灵活选择：支持两种连接管理方式，满足不同场景需求
• 向后兼容：保留了接口方法 GetTableManager(DbConnection, ISqlExecutor)

4.1.3 MySQL 提供程序

using JCode.ORMX.DbProvider.MySql;

var dbProvider = new MySqlDatabaseProvider("Server=localhost;Database=mydb;Uid=root;Pwd=password;");

MySQL 连接字符串：

// 基本连接
"Server=localhost;Database=mydb;Uid=root;Pwd=password;"

// 指定端口
"Server=localhost;Port=3306;Database=mydb;Uid=root;Pwd=password;"

// 带字符集
"Server=localhost;Database=mydb;Uid=root;Pwd=password;Charset=utf8mb4;"

4.1.4 PostgreSQL 提供程序

using JCode.ORMX.DbProvider.PgSql;

var dbProvider = new PgSqlDatabaseProvider("Host=localhost;Database=mydb;Username=postgres;Password=password;");

PostgreSQL 连接字符串：

// 基本连接
"Host=localhost;Database=mydb;Username=postgres;Password=password;"

// 指定端口
"Host=localhost;Port=5432;Database=mydb;Username=postgres;Password=password;"

// 带超时设置
"Host=localhost;Database=mydb;Username=postgres;Password=password;Timeout=30;"

4.1.5 SQL Server 提供程序

using JCode.ORMX.DbProvider.SqlServer;

var dbProvider = new SqlServerDatabaseProvider("Server=localhost;Database=mydb;User Id=sa;Password=password;");

SQL Server 连接字符串：

// 基本连接
"Server=localhost;Database=mydb;User Id=sa;Password=password;"

// 使用 Windows 身份验证
"Server=localhost;Database=mydb;Integrated Security=True;"

// 指定端口
"Server=localhost,1433;Database=mydb;User Id=sa;Password=password;"

4.1.6 MongoDB 提供程序

ORMX 提供了简洁的 MongoDB 连接管理方式：

基本连接：

using JCode.ORMX.DbProvider.MongoDB;

// 创建数据库提供程序
using var provider = new MongoDBProvider("mongodb://localhost:27017", "mydb");

// 获取表管理器
var tableManager = provider.GetTableManager();

// 获取表对象
var userTable = tableManager.Table<User>();

MongoDB 连接字符串：

// 基本连接
"mongodb://localhost:27017"

// 带认证的连接
"mongodb://username:password@localhost:27017"

// 连接到复制集（支持事务）
"mongodb://host1:27017,host2:27017,host3:27017/?replicaSet=myReplicaSet"

// 带连接选项的连接
"mongodb://localhost:27017/?connectTimeoutMS=30000&socketTimeoutMS=30000"

// 连接到分片集群
"mongodb://mongos1:27017,mongos2:27017"

MongoDBProvider 类的主要方法：

public class MongoDBProvider : IDbProvider, IDisposable
{
    // 构造函数：传入连接字符串和数据库名称
    public MongoDBProvider(string connectionString, string databaseName)
    
    // 获取表管理器
    public ITableManager GetTableManager()
    
    // 获取 SQL 执行器
    public ISqlExecutor GetSqlExecutor()
    
    // 释放资源
    public void Dispose()
}

MongoDB 连接管理特性：

• 自动连接池：MongoDB 驱动内置连接池管理，无需手动配置
• 资源管理：实现 IDisposable，支持 using 语句自动释放资源
• 会话支持：内部自动管理 MongoDB 会话，支持事务操作
• 跨版本兼容：使用反射机制兼容不同版本的 MongoDB 驱动

MongoDB 连接最佳实践：

1. 使用复制集：生产环境推荐使用 MongoDB 复制集，支持完整的事务功能
2. 合理设置超时：根据网络环境设置适当的连接超时和 socket 超时
3. 使用环境变量：将 MongoDB 连接字符串存储在环境变量中，避免硬编码
4. 连接字符串加密：对于包含密码的连接字符串，建议使用加密存储

4.1.7 Rides 数据库提供程序

ORMX 新增了 Rides 数据库提供程序支持：

基本连接：

using JCode.ORMX.DbProvider.Rides;

// 创建数据库提供程序
using var provider = new RidesDatabaseProvider("Server=localhost;Port=3306;Database=rides;Uid=root;Pwd=password;");

// 获取表管理器
var tableManager = provider.GetTableManager();

// 获取表对象
var userTable = tableManager.Table<User>();

Rides 连接字符串：

// 基本连接
"Server=localhost;Port=3306;Database=rides;Uid=root;Pwd=password;"

// 带连接选项的连接
"Server=localhost;Port=3306;Database=rides;Uid=root;Pwd=password;Connect Timeout=30;"

RidesDatabaseProvider 类的主要方法：

public class RidesDatabaseProvider : DbProviderBase, IDisposable
{
    // 构造函数：传入连接字符串
    public RidesDatabaseProvider(string connectionString)
    
    // 构造函数：传入已创建的连接实例
    public RidesDatabaseProvider(DbConnection connection)
    
    // 获取表管理器
    public ITableManager GetTableManager()
    
    // 获取 SQL 执行器
    public ISqlExecutor GetSqlExecutor()
    
    // 释放资源
    public void Dispose()
}

Rides 数据库特性：

• 高性能：针对 Rides 数据库进行了性能优化
• 兼容性：兼容 MySQL 协议，可使用 MySQL 客户端工具连接
• 资源管理：实现 IDisposable，支持 using 语句自动释放资源
• 事务支持：支持完整的事务操作

Rides 数据库最佳实践：

1. 使用连接池：Rides 数据库支持连接池，提高并发性能
2. 合理设置超时：根据应用需求设置适当的连接超时
3. 使用环境变量：将连接字符串存储在环境变量中，避免硬编码
4. 监控连接状态：定期检查连接状态，确保数据库连接正常

配置文件示例：

// appsettings.json
{
  "ConnectionStrings": {
    "DefaultConnection": "Data Source=mydatabase.db",
    "MySQLConnection": "Server=localhost;Database=mydb;Uid=root;Pwd=password;",
    "PostgresConnection": "Host=localhost;Database=mydb;Username=postgres;Password=password;",
    "MongoDBConnection": "mongodb://localhost:27017",
    "MongoDBDatabase": "mydb",
    "RidesConnection": "Server=localhost;Port=3306;Database=rides;Uid=root;Pwd=password;"
  }
}

// 读取 MongoDB 配置
var configuration = new ConfigurationBuilder()
    .SetBasePath(Directory.GetCurrentDirectory())
    .AddJsonFile("appsettings.json")
    .Build();

var mongoConnection = configuration.GetConnectionString("MongoDBConnection");
var mongoDatabase = configuration.GetConnectionString("MongoDBDatabase");

using var provider = new MongoDBProvider(mongoConnection, mongoDatabase);
var tableManager = provider.GetTableManager();

// 读取 Rides 数据库配置
var ridesConnection = configuration.GetConnectionString("RidesConnection");

using var ridesProvider = new RidesDatabaseProvider(ridesConnection);
var ridesTableManager = ridesProvider.GetTableManager();
var ridesUserTable = ridesTableManager.Table<User>();

4.2 连接生命周期管理

4.2.1 推荐方式：使用 using 语句

using JCode.ORMX.DataProviders.SQLite;

// 短期连接（推荐方式：传入连接字符串）
using (var provider = new SqliteDatabaseProvider("Data Source=test.db"))
{
    var tableManager = provider.GetTableManager();
    var userTable = tableManager.Table<User>();
    // 执行操作
} // 自动释放资源（provider 释放时会自动释放内部的连接和 SQL 执行器）

说明：

• SqliteDatabaseProvider 实现了 IDisposable 接口
• 使用 using 语句可以自动释放资源
• 内部会自动释放数据库连接和 SQL 执行器
• ITable<T> 接口没有实现 IDisposable，不需要使用 using 语句

4.2.2 长期连接：手动管理

using JCode.ORMX.DataProviders.SQLite;

// 创建连接
var provider = new SqliteDatabaseProvider("Data Source=test.db");

try
{
    var tableManager = provider.GetTableManager();
    
    // 执行多个操作
    var userTable = tableManager.Table<User>();
    userTable.Insert(new User { Name = "张三" });
    
    var orderTable = tableManager.Table<Order>();
    orderTable.Insert(new Order { Amount = 100 });
}
finally
{
    // 确保释放资源
    provider.Dispose();
}

4.3 连接池管理

ORMX 内置了连接池管理，自动复用数据库连接。连接池由底层的 ADO.NET 提供程序管理，无需手动配置。

连接池工作原理：

1. 连接获取：请求连接时，首先从连接池获取可用连接
2. 连接创建：如果池为空且未达最大连接数，创建新连接
3. 连接归还：使用完毕的连接归还到池中，而非直接关闭
4. 空闲清理：定期清理长时间空闲的连接，释放资源
5. 线程安全：完全线程安全，支持多线程并发访问

4.4 连接字符串管理

4.4.1 使用配置文件

将连接字符串放在配置文件中，而不是硬编码：

// appsettings.json
{
  "ConnectionStrings": {
    "DefaultConnection": "Data Source=mydatabase.db",
    "MySQLConnection": "Server=localhost;Database=mydb;Uid=root;Pwd=password;",
    "PostgresConnection": "Host=localhost;Database=mydb;Username=postgres;Password=password;"
  }
}

// 读取配置
var configuration = new ConfigurationBuilder()
    .SetBasePath(Directory.GetCurrentDirectory())
    .AddJsonFile("appsettings.json")
    .Build();

var connectionString = configuration.GetConnectionString("DefaultConnection");

using var connection = new SqliteConnection(connectionString);
connection.Open();

4.4.2 环境变量

在生产环境中，建议使用环境变量存储连接字符串：

var connectionString = Environment.GetEnvironmentVariable("DATABASE_CONNECTION_STRING");

if (string.IsNullOrEmpty(connectionString))
{
    throw new InvalidOperationException("未配置数据库连接字符串");
}

using var connection = new SqliteConnection(connectionString);
connection.Open();

4.5 实践示例

4.5.1 数据库连接和表管理

using JCode.ORMX.DataProviders.SQLite;

// 创建数据库提供程序（推荐方式）
using var provider = new SqliteDatabaseProvider("Data Source=:memory:");

// 获取表管理器
var tableManager = provider.GetTableManager();

// 获取表对象
var userTable = tableManager.Table<User>();
var orderTable = tableManager.Table<Order>();

Console.WriteLine(<div class="latex">$"用户表名：{userTable.TableName}");
Console.WriteLine($</div>"订单表名：{orderTable.TableName}");

4.5.2 资源管理

using JCode.ORMX.DataProviders.SQLite;

// 使用 using 语句自动释放资源（推荐方式）
using var provider = new SqliteDatabaseProvider("Data Source=:memory:");
var tableManager = provider.GetTableManager();

var userTable = tableManager.Table<User>();
var orderTable = tableManager.Table<Order>();

// 执行操作...
// 自动释放资源（provider 释放时会自动释放内部的连接和 SQL 执行器）

**说明：**
- `SqliteDatabaseProvider` 实现了 `IDisposable` 接口
- 使用 `using` 语句可以自动释放资源
- 内部会自动释放数据库连接和 SQL 执行器
- `ITable<T>` 接口没有实现 `IDisposable`，不需要使用 `using` 语句

4.5.3 使用 CreateConnection 方法

using JCode.ORMX.DataProviders.SQLite;

// 创建数据库提供程序
using var provider = new SqliteDatabaseProvider("Data Source=:memory:");

// 手动创建连接（适用于需要直接操作连接的场景）
using var connection = provider.CreateConnection();
connection.Open();

// 使用连接执行原生 SQL
using var command = connection.CreateCommand();
command.CommandText = "SELECT COUNT(*) FROM users";
var count = command.ExecuteScalar();

Console.WriteLine($"用户总数：{count}");

// 也可以将连接传递给表管理器
var tableManager = provider.GetTableManager();
var userTable = tableManager.Table<User>();

// 执行操作...

说明：

• CreateConnection() 方法返回一个新的数据库连接实例
• 需要手动调用 Open() 方法打开连接
• 使用 using 语句确保连接被正确释放
• 适用于需要直接执行原生 SQL 或需要更细粒度控制连接的场景

总结

本章介绍了 ORMX 框架的数据库连接管理机制。ORMX 支持多种主流数据库，包括 SQLite、MySQL、PostgreSQL、SQL Server、MongoDB 和 Rides，每种数据库都有专门的提供程序实现。ORMX 提供了两种连接管理方式：推荐使用传入连接字符串的方式，由框架自动管理连接；也可以传入已创建的连接实例，实现更灵活的控制。使用 using 语句可以确保资源正确释放，连接字符串应该存储在配置文件或环境变量中。对于 MongoDB，ORMX 提供了专门的连接管理特性，支持复制集、会话管理和事务操作。对于 Rides 数据库，ORMX 提供了高性能的连接管理，兼容 MySQL 协议，支持完整的事务操作。

扩展思考

在分布式系统中，如何实现数据库连接的动态切换和负载均衡？对于读写分离的场景，ORMX 是否支持主从数据库的自动路由？在云原生应用中，如何与 Kubernetes 的 Service Discovery 和 ConfigMap 集成，实现数据库连接的自动发现和配置？这些问题值得在深入学习后进一步探索。