仓颉 database_sql 包枚举详解:ConnectionState 连接状态与事务模式配置实战
仓颉 database_sql 包枚举详解:ConnectionState 连接状态与事务模式配置实战
本篇技术指南以 std.database.sql 包中的四个核心枚举为主线,完整讲解 ConnectionState(连接状态)、TransactionAccessMode(事务读写模式)、TransactionDeferrableMode(事务延迟模式)与 TransactionIsoLevel(事务隔离级别) 的定义、语义、成员方法与使用场景。读者读完将掌握:如何通过 Connection.state 感知连接生命周期、如何通过 Transaction 接口的三个枚举属性(accessMode / deferrableMode / isoLevel)配置事务行为,以及如何结合事务示例写出可运行的仓颉数据库访问代码。
一、枚举在 database_sql 包中的定位
database.sql 包为仓颉语言提供访问数据库的接口,遵循 SQL/CLI 通用规范,配合数据库驱动 Driver 完成各项操作(见 包介绍)。该包共定义四个枚举,分别服务于“连接管理”与“事务配置”两条主线:
| 枚举名 | 功能 |
|---|---|
| ConnectionState | 描述与数据源连接的当前状态 |
| TransactionAccessMode | 事务的读写模式 |
| TransactionDeferrableMode | 事务的延迟模式 |
| TransactionIsoLevel | 事务隔离级别 |
从接口定义看,这四个枚举均已接入核心 API:Connection 接口通过 prop state: ConnectionState 暴露连接状态,Transaction 接口通过 mut prop accessMode、mut prop deferrableMode、mut prop isoLevel 三个可写属性接收对应枚举值(见 接口定义)。包级索引 readme.md 同样将四个枚举归入“数据库连接状态”与“数据库事务”两组,定位一目了然。
二、ConnectionState:连接生命周期的四种状态
public enum ConnectionState <: Equatable<ConnectionState> {
| Broken
| Closed
| Connecting
| Connected
}
功能:描述与数据源连接的当前状态。其父类型为 Equatable<ConnectionState>,即该枚举支持相等性比较。
2.1 四个枚举值的语义
| 枚举值 | 声明 | 语义说明 |
|---|---|---|
Broken |
Broken |
表示与数据源的连接已中断。只有在 Connected 之后才可能发生这种情况,即连接建立成功后才存在“被中断”的可能 |
Closed |
Closed |
表示连接对象已关闭 |
Connected |
Connected |
表示连接对象已与数据源连接上 |
Connecting |
Connecting |
表示连接对象正在与数据源连接 |
这四种状态刻画了连接对象的完整生命周期:从 Connecting(建立中)到 Connected(已建立),随后要么正常 Closed(关闭),要么异常 Broken(中断)。Broken 状态的关键约束是“必须先经过 Connected”,从源码文档描述(database_sql_package_enums.md)可直接确认这一先后关系,可用于编写连接健康检查与重连逻辑。
2.2 状态相等性判断
public operator func !=(rhs: ConnectionState): Bool
public operator func ==(rhs: ConnectionState): Bool
==(rhs: ConnectionState): Bool:判断数据源连接状态是否相同,传入状态与当前状态相同返回true,否则返回false;!=(rhs: ConnectionState): Bool:判断数据源连接状态是否不同,传入状态与当前状态相同返回false,否则返回true。
参数 rhs 为数据源连接状态,返回值类型为 Bool。由于 ConnectionState 实现自 Equatable<ConnectionState>,这两个运算符正是该接口能力的具体体现,典型用法如:
// 伪代码:检查连接是否仍可用
if (cn.state == ConnectionState.Connected) {
// 连接可用,继续执行 SQL
}
if (cn.state == ConnectionState.Broken) {
// 连接已中断,需要重建连接
}
三、TransactionAccessMode:事务读写模式
public enum TransactionAccessMode <: ToString & Hashable & Equatable<TransactionAccessMode> {
| ReadOnly
| ReadWrite
| Unspecified
}
功能:事务读写模式。父类型为 ToString、Hashable 与 Equatable<TransactionAccessMode>,因此该枚举天然支持字符串转换、哈希与相等性比较。
3.1 三个枚举值的语义
| 枚举值 | 声明 | 语义说明 |
|---|---|---|
ReadOnly |
ReadOnly |
表示只读模式,事务内只允许执行查询类操作 |
ReadWrite |
ReadWrite |
表示读 + 写模式,事务内可执行增删改查 |
Unspecified |
Unspecified |
表示未指定的事务读写模式,其行为取决于具体的数据库服务器,即交由数据库端决定默认模式 |
3.2 成员函数与运算符
public func hashCode(): Int64
public func toString(): String
public operator func != (rhs: TransactionAccessMode): Bool
public operator func == (rhs: TransactionAccessMode): Bool
hashCode(): Int64:获取事务读写模式的哈希值,返回 Int64。该能力来自Hashable父接口,使枚举可安全用于哈希集合或作为映射键;toString(): String:返回事务读写模式的字符串表示,返回类型为 String。枚举值与字符串的对应关系如下:
| 枚举值 | 字符串 |
|---|---|
| ReadOnly | "Read Only" |
| ReadWrite | "Read Write" |
| Unspecified | "Unspecified" |
注意 ReadOnly 与 ReadWrite 的字符串表示带有空格("Read Only"、"Read Write"),与枚举名并非逐字一致,这在做日志输出或协议序列化时容易踩坑;
==(rhs: TransactionAccessMode): Bool:判断两个TransactionAccessMode是否相等,相等返回true,否则返回false;!=(rhs: TransactionAccessMode): Bool:判断两个TransactionAccessMode是否不相等,不相等返回true,否则返回false。
四、TransactionDeferrableMode:事务延迟模式
public enum TransactionDeferrableMode <: ToString & Hashable & Equatable<TransactionDeferrableMode> {
| Deferrable
| NotDeferrable
| Unspecified
}
功能:事务的延迟模式。父类型同样为 ToString、Hashable 与 Equatable<TransactionDeferrableMode>。
4.1 三个枚举值的语义
| 枚举值 | 声明 | 语义说明 |
|---|---|---|
Deferrable |
Deferrable |
表示可延迟 |
NotDeferrable |
NotDeferrable |
表示不可延迟 |
Unspecified |
Unspecified |
未指定的事务延迟模式,其行为取决于具体的数据库服务器 |
关于“可延迟”的官方说明:延迟事务是指在前滚阶段结束时未提交的事务,并且遇到了阻止其回滚的错误。因为事务无法回滚,所以它被延迟。 该说明完整记录在 database_sql_package_enums.md 的 Deferrable 条目下,是理解“延迟”一词的关键:它并非“推迟执行”,而是事务在提交阶段遇到无法回滚的错误时被挂起的状态。
4.2 成员函数与运算符
public func hashCode(): Int64
public func toString(): String
public operator func != (rhs: TransactionDeferrableMode): Bool
public operator func == (rhs: TransactionDeferrableMode): Bool
| 枚举值 | 字符串 |
|---|---|
| Deferrable | "Deferrable" |
| NotDeferrable | "Not Deferrable" |
| Unspecified | "Unspecified" |
同样注意 NotDeferrable 的字符串形式为 "Not Deferrable"(带空格),与枚举名不同;
==/!=:分别判断两个TransactionDeferrableMode是否相等 / 不相等,返回 Bool。
五、TransactionIsoLevel:事务隔离级别(八个取值全解析)
public enum TransactionIsoLevel <: ToString & Hashable & Equatable<TransactionIsoLevel> {
| Chaos
| Linearizable
| ReadCommitted
| ReadUncommitted
| RepeatableRead
| Serializable
| Snapshot
| Unspecified
}
功能:事务隔离级别。官方定义为——事务隔离定义了数据库系统中,一个事务中操作的结果在何时以何种方式对其他并发事务操作可见。父类型为 ToString、Hashable 与 Equatable<TransactionIsoLevel>。
该枚举是四个枚举中取值最多的一个,覆盖了从经典 SQL 隔离级别到现代数据库扩展级别的完整谱系,逐一解读如下:
| 枚举值 | 声明 | 语义说明 |
|---|---|---|
Chaos |
Chaos |
表示无法覆盖来自隔离级别更高的事务的挂起更改 |
Linearizable |
Linearizable |
表示事务线性化 |
ReadCommitted |
ReadCommitted |
表示事务等待,直到其他事务写锁定的行被解锁;这将防止它读取任何“脏”数据 |
ReadUncommitted |
ReadUncommitted |
表示事务之间不隔离 |
RepeatableRead |
RepeatableRead |
表示事务可重复读。对同一字段的多次读取结果都是一致的,除非数据是被本身事务自己所修改 |
Serializable |
Serializable |
表示事务可串行化。此隔离级别下,所有事务顺序执行,因此脏读、不可重复读、幻读都不会出现 |
Snapshot |
Snapshot |
表示快照隔离通过使用行版本控制避免了大多数锁定和阻止 |
Unspecified |
Unspecified |
未指定的事务隔离级别,其行为取决于具体的数据库服务器 |
5.1 关于 Linearizable 的特别说明
官方文档特别强调 Linearizable(线性化)与 Serializable(串行化)的区别:
区别于串行化(Serializable),线性化主要强调单个对象上(即 db 行或 nosql 记录)的一组单个操作(比如一系列读写操作),线性化保证这些操作严格按真实时间顺序执行。比如当您查看单个对象上的操作子集时,线性化是相关的。
简单归纳:Serializable 面向“多个事务的整体交错执行顺序”,而 Linearizable 面向“单个对象上的单个操作的真实时间顺序”。选择隔离级别时应依据业务并发模型——如果关注的是单行/单记录操作的实时一致性,Linearizable 更贴切;如果关注的是多事务整体隔离,则考虑 Serializable 或 Snapshot。
5.2 经典隔离级别与并发问题的对应
结合各取值说明可以整理出经典的并发问题对照(均为文档语义的直接归纳):
ReadUncommitted:事务之间不隔离,最弱,可能产生脏读;ReadCommitted:通过等待写锁解锁避免读取脏数据,解决脏读;RepeatableRead:同一字段多次读取结果一致(除非被本事务自己修改),解决不可重复读;Serializable:所有事务顺序执行,脏读、不可重复读、幻读均不会出现;Snapshot:借助行版本控制避免大部分锁定与阻塞,属于多版本并发控制(MVCC)思路的隔离级别。
5.3 成员函数与运算符
public func hashCode(): Int64
public func toString(): String
public operator func != (rhs: TransactionIsoLevel): Bool
public operator func == (rhs: TransactionIsoLevel): Bool
| 枚举值 | 字符串 |
|---|---|
| Chaos | "Chaos" |
| Linearizable | "Linearizable" |
| ReadCommitted | "Read Committed" |
| ReadUncommitted | "Read Uncommitted" |
| RepeatableRead | "Repeatable Read" |
| Serializable | "Serializable" |
| Snapshot | "Snapshot" |
| Unspecified | "Unspecified" |
==/!=:分别判断两个TransactionIsoLevel是否相等 / 不相等,返回 Bool。
六、枚举成员的共性与实用要点
纵观四个枚举,其成员能力高度一致,可归纳为三条共性规律:
- 相等性判断(
==/!=):ConnectionState仅实现Equatable,而三个事务相关枚举(TransactionAccessMode、TransactionDeferrableMode、TransactionIsoLevel)同时实现ToString & Hashable & Equatable,能力更完整。三个事务枚举均可直接用于HashMap/HashSet等需要哈希的容器(哈希能力来自std.collection相关容器,见 collection 包接口)。 - 字符串表示(
toString)与枚举名的差异:三个事务枚举的字符串输出在部分取值上插入空格(如"Read Only"、"Not Deferrable"、"Read Committed"),与枚举标识符并非逐字相同。在日志输出、配置写入或协议对接时,应以toString()的实际返回值为准,不要直接拼接枚举名。 Unspecified的兜底语义:三个事务枚举均包含Unspecified,其共同语义是“未指定,行为取决于具体的数据库服务器”。这意味着应用层不强制约束事务模式,具体生效值由驱动对接的数据库(如 openGauss)决定。
七、实战:事务枚举如何驱动真实事务流程
Transaction 接口(完整定义见 Transaction_interface.md)通过三个可写属性暴露上述事务枚举:
public interface Transaction {
mut prop accessMode: TransactionAccessMode
mut prop deferrableMode: TransactionDeferrableMode
mut prop isoLevel: TransactionIsoLevel
func begin(): Unit
func commit(): Unit
func release(savePointName: String): Unit
func rollback(): Unit
func rollback(savePointName: String): Unit
func save(savePointName: String): Unit
}
由此,事务枚举的典型配置方式为:创建事务对象后,先设置 accessMode、deferrableMode、isoLevel,再执行 begin() / commit() / rollback() 控制事务生命周期。仓库中的事务示例 db_transactions.md 给出了完整可运行流程(基于 openGauss 驱动):
import std.database.sql.*
import std.time.*
main() {
let SQL_INSERT = "INSERT INTO EMPLOYEE (NAME, SALARY, CREATED_DATE) VALUES (?, ?, ?)"
let drv = DriverManager.getDriver("opengauss") ?? return
let db = drv.open("opengauss://localhost:5432/testdb")
try(cn = db.connect()) {
let psInsert = cn.prepareStatement(SQL_INSERT)
// 创建事务对象
let tx = cn.createTransaction()
try {
// 插入第一条数据
psInsert.set<String>(0, "mkyong")
psInsert.set<Array<Byte>>(1, Array<Byte>(1, repeat: 10))
psInsert.set<DateTime>(2, DateTime.now())
psInsert.update()
// 插入第二条数据
psInsert.set<String>(0, "kungfu")
psInsert.set<Array<Byte>>(1, Array<Byte>(1, repeat: 20))
psInsert.set<DateTime>(2, DateTime.now())
psInsert.update()
// 如果连接到数据库,测试回滚 SQLException:未为参数3指定值
psInsert.set<String>(0, "mkyong")
psInsert.set<Array<Byte>>(1, Array<Byte>(5, {i => UInt8(i + 1)}))
psInsert.update()
// 提交事务
tx.commit()
} catch (e1: SqlException) {
e1.printStackTrace()
try {
// 发生异常,回滚所有事务
tx.rollback()
} catch (e2: SqlException) {
// 如果回滚失败
e2.printStackTrace()
}
}
} catch (e: SqlException) {
// 如果连接失败
e.printStackTrace()
}
}
结合本文主题,可以从示例中提取两个与枚举直接相关的实践点:
- 连接状态与事务的先后关系:
ConnectionState的Broken语义(只有Connected之后才可能中断)决定了事务代码必须先确认连接可用;Transaction的begin()/commit()/rollback()在连接已断开时都会抛出 SqlException(见 Transaction 接口异常说明),因此异常处理中rollback失败(如连接已 Broken)需要二次捕获。 - 事务属性的设置时机:
accessMode、deferrableMode、isoLevel均为mut prop,应在事务执行 SQL 之前完成设置,以保证数据库端按期望的模式处理事务;若留Unspecified,则由具体数据库服务器决定默认行为。
八、小结
std.database.sql 的四个枚举构成了连接管理与事务配置的类型安全基础:
- ConnectionState 以
Connecting → Connected → (Closed | Broken)描述连接生命周期,并支持==/!=比较; - TransactionAccessMode 提供
ReadOnly/ReadWrite/Unspecified三种读写模式; - TransactionDeferrableMode 提供
Deferrable/NotDeferrable/Unspecified三种延迟模式,其中Deferrable对应“前滚阶段遇错无法回滚而被延迟”的数据库语义; - TransactionIsoLevel 覆盖
Chaos、Linearizable、ReadCommitted、ReadUncommitted、RepeatableRead、Serializable、Snapshot、Unspecified八个级别,是控制并发可见性的核心配置项。
三个事务枚举均实现 ToString & Hashable & Equatable,toString() 的字符串输出与枚举名存在空格差异(如 "Read Only"),实际使用时务必以其文档化映射表为准。相关源码与示例可继续查阅 database_sql_package_enums.md、数据库事务示例 与 包级索引。