仓颉 database_sql 包枚举详解:ConnectionState 连接状态与事务模式配置实战

原创2026-10-14 19:58:201,340 阅读
文章标签:人工智能AI 技能文档开发工具

仓颉 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
  • hashCode(): Int64:获取事务延迟模式的哈希值,返回 Int64;
  • toString(): String:返回事务延迟模式的字符串表示,返回 String。对应关系如下:
枚举值 字符串
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
  • hashCode(): Int64:获取事务隔离级别的哈希值,返回 Int64;
  • toString(): String:返回事务隔离级别的字符串表示,返回 String。对应关系如下:
枚举值 字符串
Chaos "Chaos"
Linearizable "Linearizable"
ReadCommitted "Read Committed"
ReadUncommitted "Read Uncommitted"
RepeatableRead "Repeatable Read"
Serializable "Serializable"
Snapshot "Snapshot"
Unspecified "Unspecified"
  • == / !=:分别判断两个 TransactionIsoLevel 是否相等 / 不相等,返回 Bool。

六、枚举成员的共性与实用要点

纵观四个枚举,其成员能力高度一致,可归纳为三条共性规律:

  1. 相等性判断(== / !=):ConnectionState 仅实现 Equatable,而三个事务相关枚举(TransactionAccessMode、TransactionDeferrableMode、TransactionIsoLevel)同时实现 ToString & Hashable & Equatable,能力更完整。三个事务枚举均可直接用于 HashMap/HashSet 等需要哈希的容器(哈希能力来自 std.collection 相关容器,见 collection 包接口)。
  2. 字符串表示(toString)与枚举名的差异:三个事务枚举的字符串输出在部分取值上插入空格(如 "Read Only"、"Not Deferrable"、"Read Committed"),与枚举标识符并非逐字相同。在日志输出、配置写入或协议对接时,应以 toString() 的实际返回值为准,不要直接拼接枚举名。
  3. 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()
    }
}

结合本文主题,可以从示例中提取两个与枚举直接相关的实践点:

  1. 连接状态与事务的先后关系:ConnectionState 的 Broken 语义(只有 Connected 之后才可能中断)决定了事务代码必须先确认连接可用;Transaction 的 begin() / commit() / rollback() 在连接已断开时都会抛出 SqlException(见 Transaction 接口异常说明),因此异常处理中 rollback 失败(如连接已 Broken)需要二次捕获。
  2. 事务属性的设置时机: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、数据库事务示例 与 包级索引。

登录后查看全文
DocAgent