UDataset.Kingbase 0.14.2

UDataset.Kingbase

UDataset.Kingbase 是 UDataset 跨数据库数据访问框架的 KingbaseES（人大金仓）数据库实现。它提供 KingbaseES 特定实现的 UDataset 核心接口，支持与 KingbaseES 数据库的无缝数据操作。

特性

• PostgreSQL 兼容模式：KingbaseES V9 高度兼容 PostgreSQL，本实现基于 PG 兼容模式
• 完整数据库支持：完整的 UDataset 所有特性实现
• 丰富数据类型：支持 KingbaseES 的数据类型系统，包括 JSON、JSONB、XML、UUID 等
• 数据库管理：完整支持数据库创建、修改、重命名操作（带 DBCOMPATIBILITY 设置）
• 用户管理：支持用户创建、权限管理、启用/禁用等操作
• ACID 事务：完整的事务支持，包括保存点和嵌套事务
• 乐观锁：使用 xid 类型实现 RowVersion 乐观锁机制
• Upsert 支持：支持 ON CONFLICT 语法的 Upsert 操作
• 批量操作优化：使用 VALUES + RETURNING 语法进行批量插入

安装

dotnet add package UDataset.Core
dotnet add package UDataset.Kingbase

快速开始

1. 注册提供者

using UDataset.Core;
using UDataset.Kingbase;

// 在应用程序启动时注册 KingbaseES 提供者
KingbaseBootstrapper.Register();

2. 创建连接

// 基本连接字符串（KingbaseES 默认端口 54321）
string connectionString = "Server=localhost;Port=54321;Database=mydatabase;User Id=system;Password=123456789;";

// 带连接池和 SSL
string pooledConnectionString = "Server=localhost;Port=54321;Database=mydatabase;User Id=system;Password=123456789;Pooling=true;Min Pool Size=5;Max Pool Size=100;SSL Mode=Require;";

IConnection connection = ProviderFactory.CreateConnection("Kingbase", connectionString);

3. 基本操作

// 创建表
var schemaManager = ProviderFactory.CreateSchemaManager("Kingbase", connectionString);
var userTable = new Table("Users")
    .WithGuidPK("UserId")
    .WithVersionControl("Version"); // 启用乐观锁
userTable.Attributes.Add(new Column("Username", DataType.String) { Properties = { [ColumnProperty.Length] = 100, [ColumnProperty.Unique] = true } });
userTable.Attributes.Add(new Column("Email", DataType.String) { Properties = { [ColumnProperty.Length] = 255 } });
userTable.Attributes.Add(new Column("Age", DataType.Int));
userTable.Attributes.Add(new Column("IsActive", DataType.Boolean));
userTable.Attributes.Add(new Column("Tags", DataType.Json)); // JSON 类型
schemaManager.Create(userTable);

// 插入数据
var user = new Row("Users")
{
    ["Username"] = "john_doe",
    ["Email"] = "john@example.com",
    ["Age"] = 30,
    ["IsActive"] = true,
    ["Tags"] = "{ \"tags\": [\"developer\", \"admin\"] }"
};
var createdUser = await connection.Create(user);

// 更新数据（带乐观锁）
var userToUpdate = new Row("Users", createdUser.Id);
userToUpdate.Version = createdUser.Version; // 乐观锁需要版本号
userToUpdate["Age"] = 31;
var updatedUser = await connection.Update(userToUpdate);

// 查询数据
var query = new QueryExpression("Users");
query.Filter = "IsActive = @isActive AND Age > @minAge";
query.Parameters["isActive"] = true;
query.Parameters["minAge"] = 25;
query.AddOrderBy("Username", SortDirection.Ascending);
var activeUsers = await connection.Query(query);

KingbaseES 特性

数据库兼容模式

创建数据库时可以指定兼容模式：

// PG 兼容模式（推荐）
var dbManager = ProviderFactory.CreateDatabaseManager("Kingbase", connectionString);
dbManager.Create("mydb", new DatabaseOptions { Charset = Charset.UTF8 });

// Oracle 兼容模式（需修改实现）
// CREATE DATABASE "mydb" WITH DBCOMPATIBILITY 'ORA'

JSON 和 JSONB

KingbaseES 支持 JSON 和 JSONB 类型：

var configTable = new Table("Configurations");
configTable.Attributes.Add(new Column("Settings", DataType.Json));
schemaManager.Create(configTable);

GUID 主键

KingbaseES 支持 UUID 类型：

var table = new Table("Orders")
    .WithGuidPK("OrderId"); // 使用 gen_random_uuid() 函数
schemaManager.Create(table);

Upsert 操作

支持 PostgreSQL 的 ON CONFLICT 语法：

var options = new InsertOptions
{
    OnConflict = OnConflictBehavior.Update,
    ConflictFields = new[] { "Email" },
    ReturnRecords = true
};
var result = await connection.Create(users, options);

连接字符串

KingbaseES 连接字符串格式（与 PostgreSQL 类似但端口不同）：

// 基本连接
"Server=localhost;Port=54321;Database=mydb;User Id=system;Password=123456789;"

// 带连接池
"Server=localhost;Port=54321;Database=mydb;User Id=system;Password=123456789;Pooling=true;Min Pool Size=5;Max Pool Size=100;"

// 带超时设置
"Server=localhost;Port=54321;Database=mydb;User Id=system;Password=123456789;Timeout=30;CommandTimeout=60;"

// Unix socket
"Host=/var/run/kingbase;Database=mydb;User Id=system;Password=123456789;"

主要差异（与 PostgreSQL）

系统视图映射

数据类型映射

SQL 函数转换

UDataset 自动将常见 SQL 函数转换为 KingbaseES 等效函数：

限制与注意事项

• 自增主键：使用 SERIAL 或 BIGSERIAL 类型
• RowVersion：使用 xid 类型 + 触发器实现
• 标识符长度：最大 63 字符（PG 兼容模式）
• Oracle 模式：使用 Oracle 兼容模式时，Boolean 需转换为 NUMBER(1)

要求

• .NET 8.0
• Kdbndp_V9 6.0.5.722（人大金仓官方 ADO.NET 驱动）
• KingbaseES V9（推荐 V9R2C13 及以上）

依赖项

• UDataset.Core
• Kdbndp_V9 6.0.5.722
• Dapper 2.1.66
• System.Data.Common

参考资料

• KingbaseES 开发指南
• UDataset.Core 文档
• PostgreSQL 实现参考

⚠️ 重要说明: 0.14.0 已修复 Kdbndp_V9 驱动的认证兼容问题（连接串需追加 DbVersion=R3），并已通过全量回归测试（8 个功能组全部通过）。生产环境使用前建议结合自身环境充分验证。

版本：0.14.0 KingbaseES 版本：V9 更新日期：2026年8月7日