NewLife.MySql — 纯国产高性能 MySQL 驱动

🌐 中文 | English | 日本語 | 한국어 | Español | Português

NewLife.MySql 是新生命团队出品的纯国产 MySQL 客户端驱动，基于 ADO.NET 标准接口，直接通过 TCP 实现 MySQL 协议层（Protocol Version 10）。仅依赖 NewLife.Core，零第三方依赖、全链路真异步、MIT 协议商用无忧。

独创的管道化批量执行（Pipeline）在万级行批量写入场景下可达 2×~3× 加速（vs 逐行基线），是大数据批量操作、信创国产化替代的理想选择。

设计目标

核心功能

亮点特性

🚀 管道化批量执行（Pipeline）

独创的管道化模式，基于 COM_STMT_PREPARE + COM_STMT_EXECUTE 二进制协议：

• Phase 1：批量构建并发送所有 EXECUTE 包，仅最后一个包 Flush
• Phase 2：按顺序批量读取所有 OK/Error 响应，累加影响行数
• TCP 协议栈合并小包（Nagle 算法），网络往返仅一次

实测数据（.NET 10 + MySQL 8.0.26 本机，管道化+事务 vs 逐行基线）：

三驱动性能数据（10,000 行批量操作）：

本机内网已有 4×~8× 加速，跨机房场景收益更大。详细数据参见 性能测试报告。

🔧 五种批量操作方案

🛡️ 零第三方依赖

仅依赖 NewLife.Core（同为 NewLife 团队出品），无 GPL 许可风险，MIT 协议商用无忧，适合信创环境和安全审计严格的场景。

⚡ 极致性能优化

• ArrayPool<T> + OwnerPacket 零额外分配
• Pool.StringBuilder / Pool.MemoryStream 全面池化
• 全链路 async/await，无 sync-over-async 反模式
• 精简协议解析，只解析必要字段

🌐 广泛兼容

• 框架：net45 / net461 / netstandard2.0 / netstandard2.1 / net6.0 / net10.0
• MySQL：5.5 ~ 9.0+，mysql_native_password + caching_sha2_password
• 兼容库：OceanBase、TiDB、Doris（自动检测）、Aurora / CloudSQL（云数据库）、MariaDB（基础）
• 条件编译：针对不同框架自动选择最优实现

功能特性

完整功能和架构分析参见 架构设计。

安装

dotnet add package NewLife.MySql

<PackageReference Include="NewLife.MySql" Version="1.0.*" />

快速开始

连接字符串

Server=localhost;Port=3306;Database=mydb;User Id=root;Password=pass;

打开连接

using var conn = new MySqlConnection("Server=localhost;Database=mydb;User Id=root;Password=pass;");
conn.Open();
// using 结束时自动关闭并归还连接池

查询结果集

using var conn = new MySqlConnection(connStr);
conn.Open();

using var cmd = new MySqlCommand(conn, "SELECT id, name, age FROM users WHERE age > 18");
using var reader = cmd.ExecuteReader();

while (reader.Read())
{
    var id = reader.GetInt64(0);
    var name = reader.GetString(1);
    var age = reader.GetInt64(2);
    Console.WriteLine($"{id}: {name}, {age}");
}

查询单值

using var cmd = new MySqlCommand(conn, "SELECT COUNT(*) FROM users");
var count = cmd.ExecuteScalar();

执行 DML

using var cmd = new MySqlCommand(conn, "INSERT INTO users(name, age) VALUES('Tom', 25)");
var affectedRows = cmd.ExecuteNonQuery();

// 快捷方式
var rows = conn.ExecuteNonQuery("DELETE FROM logs WHERE created < '2024-01-01'");

参数化查询

使用 @参数名 语法绑定参数，自动转义防注入：

using var cmd = new MySqlCommand(conn, "SELECT * FROM users WHERE name = @name AND age > @age");
cmd.Parameters.AddWithValue("name", "Tom");
cmd.Parameters.AddWithValue("age", 18);

using var reader = cmd.ExecuteReader();
while (reader.Read())
{
    Console.WriteLine(reader.GetString(0));
}

// 参数化插入
using var cmd = new MySqlCommand(conn, "INSERT INTO users(name, age, created) VALUES(@name, @age, @dt)");
cmd.Parameters.AddWithValue("name", "Alice");
cmd.Parameters.AddWithValue("age", 30);
cmd.Parameters.AddWithValue("dt", DateTime.Now);
cmd.ExecuteNonQuery();

// NULL 值传递
cmd.Parameters.AddWithValue("email", DBNull.Value);

支持的参数类型：

事务

using var conn = new MySqlConnection(connStr);
conn.Open();

using var tr = conn.BeginTransaction();
try
{
    conn.ExecuteNonQuery("INSERT INTO orders(product, qty) VALUES('Widget', 10)");
    conn.ExecuteNonQuery("UPDATE inventory SET qty = qty - 10 WHERE product = 'Widget'");
    tr.Commit();
}
catch
{
    tr.Rollback();
    throw;
}

支持四种隔离级别：ReadUncommitted / ReadCommitted / RepeatableRead（默认）/ Serializable

using var tr = conn.BeginTransaction(IsolationLevel.ReadCommitted);

事务 Dispose 时如果未提交也未回滚，会自动执行回滚。

存储过程

using var cmd = new MySqlCommand { Connection = conn, CommandType = CommandType.StoredProcedure };
cmd.CommandText = "my_proc";
cmd.Parameters.AddWithValue("p_id", 1);

var outParam = new MySqlParameter { ParameterName = "p_result", Direction = ParameterDirection.Output };
cmd.Parameters.Add(outParam);

cmd.ExecuteNonQuery();
var result = outParam.Value; // 输出参数值

预编译语句

通过 Prepare() 在服务端预编译 SQL，后续执行走二进制协议：

using var cmd = new MySqlCommand(conn, "INSERT INTO users(name, age) VALUES(@name, @age)");
cmd.Parameters.AddWithValue("name", "Tom");
cmd.Parameters.AddWithValue("age", 25);

cmd.Prepare(); // 服务端预编译

cmd.ExecuteNonQuery(); // 第一次执行

// 修改参数后再次执行（无需重新编译）
cmd.Parameters[0].Value = "Jerry";
cmd.Parameters[1].Value = 30;
cmd.ExecuteNonQuery();

也可通过连接字符串全局启用，所有参数化查询自动走二进制协议：

UseServerPrepare=true;

批量操作

方案 A：字典参数集

同一 SQL 绑定多组参数执行，内部自动预编译：

using var cmd = new MySqlCommand(conn, "INSERT INTO users(name, age) VALUES(@name, @age)");
cmd.Parameters.AddWithValue("name", "");
cmd.Parameters.AddWithValue("age", 0);

var paramSets = new List<IDictionary<String, Object?>>
{
    new Dictionary<String, Object?> { ["name"] = "Alice", ["age"] = 25 },
    new Dictionary<String, Object?> { ["name"] = "Bob", ["age"] = 30 },
    new Dictionary<String, Object?> { ["name"] = "Charlie", ["age"] = 22 },
};
var totalAffected = cmd.ExecuteBatch(paramSets);
// 或 await cmd.ExecuteBatchAsync(paramSets);

方案 B：数组绑定（Oracle 风格）

参数值设为数组，指定执行次数：

using var cmd = new MySqlCommand(conn, "INSERT INTO users(name, age) VALUES(@name, @age)");
cmd.Parameters.AddWithValue("name", new[] { "Alice", "Bob", "Charlie" });
cmd.Parameters.AddWithValue("age", new[] { 25, 30, 22 });

var totalAffected = cmd.ExecuteArrayBatch(3);
// 或 await cmd.ExecuteArrayBatchAsync(3);

方案 C：管道化执行

连接字符串开启 Pipeline=true，批量发送后批量接收，网络往返仅一次：

var connStr = "Server=localhost;Database=mydb;User Id=root;Password=pass;Pipeline=true;";
using var conn = new MySqlConnection(connStr);
conn.Open();

using var cmd = new MySqlCommand(conn, "UPDATE users SET age=@age WHERE name=@name");
cmd.Parameters.AddWithValue("age", agesArray);    // Int32[10000]
cmd.Parameters.AddWithValue("name", namesArray);   // String[10000]
var totalAffected = cmd.ExecuteArrayBatch(10000);

管道化对 INSERT / UPDATE / DELETE 均有效，搭配字典参数集或数组绑定使用。网络延迟越高（如跨机房），收益越大。

方案 D：多行 VALUES

var sql = "INSERT INTO users(name, age) VALUES('Alice', 25), ('Bob', 30), ('Charlie', 22)";
conn.ExecuteNonQuery(sql);

方案 E：DbBatch API（.NET 6+）

var batch = conn.CreateBatch();
batch.BatchCommands.Add(new MySqlBatchCommand("INSERT INTO users(name, age) VALUES('X1', 10)"));
batch.BatchCommands.Add(new MySqlBatchCommand("INSERT INTO users(name, age) VALUES('X2', 20)"));
batch.BatchCommands.Add(new MySqlBatchCommand("UPDATE users SET age = age + 1 WHERE name = 'X1'"));

using var reader = batch.ExecuteReader();

EF Core 支持

NewLife.MySql.EntityFrameworkCore 包提供 EF Core 数据库提供程序，支持 .NET 6 / .NET 8 / .NET 10。

dotnet add package NewLife.MySql.EntityFrameworkCore

public class AppDbContext : DbContext
{
    public DbSet<User> Users { get; set; } = null!;

    public AppDbContext(DbContextOptions<AppDbContext> options) : base(options) { }

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        modelBuilder.Entity<User>(entity =>
        {
            entity.ToTable("users");
            entity.HasKey(e => e.Id);
            entity.Property(e => e.Name).HasMaxLength(100).IsRequired();
        });
    }
}

var options = new DbContextOptionsBuilder<AppDbContext>()
    .UseMySql("Server=localhost;Database=mydb;User Id=root;Password=pass;")
    .Options;

using var context = new AppDbContext(options);

已支持功能：

SSL/TLS 加密连接

// 服务器支持则加密，不支持则明文
var connStr = "Server=localhost;Database=mydb;User Id=root;Password=pass;SslMode=Preferred;";

// 必须加密，不支持则抛异常
var connStr2 = "Server=localhost;Database=mydb;User Id=root;Password=pass;SslMode=Required;";

Schema 信息查询

var databases = conn.GetSchema("Databases");  // 数据库列表
var tables = conn.GetSchema("Tables");         // 表列表
var columns = conn.GetSchema("Columns");       // 列信息
var indexes = conn.GetSchema("Indexes");       // 索引信息

异步方法

所有核心操作均支持异步版本：

using var conn = new MySqlConnection(connStr);
await conn.OpenAsync();

using var cmd = new MySqlCommand(conn, "SELECT * FROM users");
using var reader = await cmd.ExecuteReaderAsync();

while (await reader.ReadAsync())
{
    Console.WriteLine(reader.GetString(0));
}

连接池

连接池默认启用，无需额外配置。每个唯一连接字符串对应独立连接池。

• 打开连接时自动从池中获取
• 关闭连接时自动归还（不断开 TCP）
• 无效连接自动剔除
• 新连接按需创建
• 网络断线自动重连：检测到连接断开时自动重试，提升长连接场景稳定性

连接池参数配置

var connStr = "Server=localhost;Database=mydb;...;MinPoolSize=5;MaxPoolSize=50;ConnectionLifeTime=3600;";

XCode ORM 集成

通过 MySqlClientFactory 自动注册为 XCode 的 MySQL 驱动：

using XCode.DataAccessLayer;

DAL.AddConnStr("mysql", "Server=localhost;Database=mydb;User Id=root;Password=pass;", null, "MySql");

var dal = DAL.Create("mysql");
var tables = dal.Tables;

切换数据库

ChangeDatabase（推荐）

using var conn = new MySqlConnection("Server=localhost;Database=db1;...");
conn.Open();
conn.ChangeDatabase("db2"); // 内部 Close + Reopen

⚠️ 不支持在事务中途切换（事务会丢失），推荐为每个数据库创建独立连接。

SqlClient.SetDatabaseAsync（低级 API）

await conn.Client.SetDatabaseAsync("information_schema"); // COM_INIT_DB

不关闭连接，仅切换服务端当前数据库，适合临时查询场景。

OceanBase / TiDB 支持

驱动根据握手包版本字符串自动检测数据库类型，连接方式与 MySQL 完全相同：

// OceanBase
var connStr = "Server=oceanbase-host;Port=2881;Database=test;User Id=root;Password=pass;";
using var conn = new MySqlConnection(connStr);
conn.Open();
Console.WriteLine($"数据库类型: {conn.DatabaseType}");  // OceanBase

// TiDB
var connStr2 = "Server=tidb-host;Port=4000;Database=test;User Id=root;Password=pass;";
using var conn2 = new MySqlConnection(connStr2);
conn2.Open();
Console.WriteLine($"数据库类型: {conn2.DatabaseType}");  // TiDB

基础 SQL、事务、参数化查询、批量操作均兼容。

多目标框架

注意事项

1. MySQL 版本：支持 5.x 及以上，推荐 8.0+
2. 字符编码：默认 UTF-8
3. ChangeDatabase：通过 Close/Reopen 实现，不支持事务中切换，推荐独立连接
4. 管道化执行：仅适用于 DML 批量操作，不适用于 SELECT 查询

相关文档