仓颉 std.database.sql 事务接口 Transaction 完全指南：核心行为、隔离级别与保存点实战

人工智能AI 技能文档开发工具【免费下载链接】DocAgent项目地址https://gitcode.com/Cangjie-SIG/DocAgent点击查看免费下载Transaction是仓颉标准库std.database.sql中定义数据库事务核心行为的接口它规定了事务从开始、提交、回滚到保存点管理的完整生命周期并暴露事务访问模式、延迟模式与隔离级别三项可配置属性。本文以该接口文档为主体结合 database_sql 包接口定义、事务相关枚举定义 以及 事务控制示例系统讲解Transaction的每个成员函数、三个关键配置属性的取值语义与底层映射并给出可直接运行的事务与保存点实战代码帮助读者在仓颉项目中正确落地数据库事务编程。Transaction 在 database.sql 包中的定位std.database.sql包为仓颉提供访问数据库的 SQL/CLI 通用接口配合数据库驱动Driver完成对数据库的各项操作参见 包功能总览。在包的完整调用链中Transaction处于承上启下的位置通过DriverManager.getDriver()获取驱动Driver.open()打开数据源Datasource通过Datasource.connect()取得连接Connection通过 Connection.createTransaction() 创建事务对象Transaction该函数在已经处于事务状态且不支持并行事务时会抛出 SqlException通过 Statement 在事务内执行 SQL最后用Transaction的commit()或rollback()结束事务。Transaction接口声明如下完整定义见 database_sql_package_interfaces.mdpublic 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 }接口的全部成员可划分为三组三项事务属性访问模式、延迟模式、隔离级别、三个事务控制方法begin/commit/rollback、三个保存点方法save/rollback(savePointName)/release。继承该接口的 class、interface、struct 均需遵守成员函数的入参与返回值定义。事务生命周期begin、commit 与 rollbackbegin()开始数据库事务func begin(): Unitbegin()用于开始数据库事务。调用后事务进入活动状态后续通过该连接执行的 SQL 将被纳入事务管理范围。根据接口文档当提交事务时服务器端发生错误或事务已提交、已回滚、连接已断开时会抛出SqlException。commit()提交数据库事务func commit(): Unitcommit()将事务中所有未提交的修改持久化到数据库。调用成功后事务结束。与begin()相同若提交时服务器端发生错误或事务已提交/回滚、连接已断开会抛出SqlException。rollback()从挂起状态回滚事务func rollback(): Unitrollback()用于从挂起状态回滚事务即撤销当前事务中尚未提交的全部修改使数据库恢复到事务开始前的状态。这是事务异常处理中的兜底手段当业务逻辑抛出异常时通常需要调用rollback()放弃整个事务避免留下半成品数据。接口成员一览begin、commit、rollback()与rollback(savePointName)的签名与说明也收录于接口索引页 Transaction_interface.md。保存点机制save、rollback(savePointName) 与 release保存点Savepoint允许在事务内部设置多个检查点从而在出错时只回滚到某个检查点之后的修改而不是放弃整个事务。save(savePointName)创建保存点func save(savePointName: String): Unit在事务中创建一个指定名称的保存点可用于回滚此保存点之后的事务。参数savePointName为保存点名称类型为String。保存点名称需要在整个事务中保持唯一以便后续精确回滚。rollback(savePointName)回滚至指定保存点func rollback(savePointName: String): Unit回滚事务至指定保存点名称。调用后该保存点之后执行的所有修改被撤销而保存点之前的修改仍然保留事务继续处于活动状态可以继续执行后续 SQL 或再次提交。release(savePointName)销毁保存点func release(savePointName: String): Unit销毁先前在当前事务中定义的保存点这允许系统在事务结束之前回收一些资源。当一个保存点不再需要时应及时release避免保存点过多占用服务器端资源。保存点使用原则从接口设计看保存点遵循先save、后按需rollback或release的使用模式需要部分回滚时用rollback(savePointName)回退到指定保存点保留更早的修改保存点使命完成后用release(savePointName)释放其资源无论是否使用保存点事务最终仍以commit()或rollback()收尾。需要注意的是保存点是否可用取决于具体数据库驱动的实现使用前应确认驱动与数据库服务器支持保存点特性示例文档 db_transactions.md 亦注明如果数据库事务支持保存点这一前提。三项事务属性与对应枚举详解Transaction通过三个mut prop暴露事务的配置属性读取时获取当前事务的配置写入时设置事务的配置。三者分别对应三个枚举类型下面逐一展开。accessMode事务访问模式mut prop accessMode: TransactionAccessMode访问模式决定事务是只读还是可读写。TransactionAccessMode 枚举定义如下public enum TransactionAccessMode : ToString Hashable EquatableTransactionAccessMode { | ReadOnly | ReadWrite | Unspecified }枚举值字符串表示语义ReadOnlyRead Only只读模式事务内不允许执行写操作ReadWriteRead Write读 写模式事务可读写数据UnspecifiedUnspecified未指定访问模式行为取决于具体的数据库服务器Unspecified的意义在于将具体语义决策下放给数据库服务器便于驱动在不同数据库间保持接口统一。deferrableMode事务延迟模式mut prop deferrableMode: TransactionDeferrableMode延迟模式与事务约束检查的时机相关。TransactionDeferrableMode 枚举定义如下public enum TransactionDeferrableMode : ToString Hashable EquatableTransactionDeferrableMode { | Deferrable | NotDeferrable | Unspecified }枚举值字符串表示语义DeferrableDeferrable可延迟延迟事务是指在前滚阶段结束时未提交、且遇到了阻止其回滚错误的事务因无法回滚而被延迟NotDeferrableNot Deferrable不可延迟约束检查在语句执行时立即进行UnspecifiedUnspecified未指定延迟模式行为取决于具体的数据库服务器理解Deferrable的关键在于延迟约束检查可延迟事务允许将部分完整性约束的检查推迟到事务提交时统一进行从而让事务在过程中临时处于约束未满足状态只要提交前满足即可。isoLevel事务隔离级别mut prop isoLevel: TransactionIsoLevel隔离级别定义了数据库系统中一个事务中操作的结果在何时以何种方式对其他并发事务操作可见是并发控制的核心参数。TransactionIsoLevel 枚举提供了 8 个取值public enum TransactionIsoLevel : ToString Hashable EquatableTransactionIsoLevel { | Chaos | Linearizable | ReadCommitted | ReadUncommitted | RepeatableRead | Serializable | Snapshot | Unspecified }枚举值字符串表示语义ChaosChaos无法覆盖来自隔离级别更高的事务的挂起更改LinearizableLinearizable事务线性化区别于串行化线性化强调单个对象db 行或 nosql 记录上的一组单个操作严格按真实时间顺序执行查看单个对象上的操作子集时线性化相关ReadCommittedRead Committed事务等待直到其他事务写锁定的行被解锁防止读取任何脏数据ReadUncommittedRead Uncommitted事务之间不隔离允许脏读RepeatableReadRepeatable Read可重复读对同一字段的多次读取结果一致除非数据被当前事务自身修改SerializableSerializable可串行化所有事务顺序执行脏读、不可重复读、幻读都不会出现SnapshotSnapshot快照隔离通过行版本控制避免大多数锁定和阻塞UnspecifiedUnspecified未指定隔离级别行为取决于具体的数据库服务器选择建议基于枚举文档语义对一致性要求最高的金融类场景可选Serializable对读多写少、要求并发吞吐的场景可选Snapshot或ReadCommittedReadUncommitted允许脏读仅在可容忍不一致数据的场景使用Unspecified则交由数据库服务器决定适合依赖数据库默认行为的场景。三个枚举均实现了ToString、Hashable、Equatable自身及/!运算符可参与哈希、比较与字符串输出toString()的映射关系即上文表格中的字符串表示列。实战完整事务控制示例以下示例来自 数据库事务示例文档演示了Transaction接口在真实仓颉程序中的完整用法包含连接建立、参数化插入、提交与回滚。普通数据库事务commit 与 rollbackimport 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.setString(0, mkyong) psInsert.setArrayByte(1, ArrayByte(1, repeat: 10)) psInsert.setDateTime(2, DateTime.now()) psInsert.update() // 插入第二条数据 psInsert.setString(0, kungfu) psInsert.setArrayByte(1, ArrayByte(1, repeat: 20)) psInsert.setDateTime(2, DateTime.now()) psInsert.update() // 如果连接到数据库测试回滚 SQLException未为参数3指定值。 psInsert.setString(0, mkyong) psInsert.setArrayByte(1, ArrayByte(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() } }要点拆解通过DriverManager.getDriver(opengauss)获取驱动若未注册返回Nonedrv.open()打开数据源db.connect()建立连接相关驱动管理能力见 DriverManager_class.mdcn.createTransaction()创建事务对象随后所有psInsert.update()均在事务作用域内执行第三条插入语句缺少参数 3 的取值会触发SqlException此时tx.commit()不会执行控制流转入catch分支调用tx.rollback()撤销前两条插入——这正是要么全部成功、要么全部撤销的事务原子性体现内层catch再次捕获SqlException是因为rollback()本身也可能因连接断开等场景失败需要单独处理事务相关的 SQL 均通过 Statement 接口 的setT/update完成参数绑定与执行。事务保存点部分回滚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 { // 创建保存点 1 tx.save(save1) psInsert.setString(0, mkyong) psInsert.setArrayByte(1, ArrayByte(1, repeat: 10)) psInsert.setDateTime(2, DateTime.now()) psInsert.update() // 创建保存点 2 tx.save(save2) psInsert.setString(0, kungfu) psInsert.setArrayByte(1, ArrayByte(1, repeat: 20)) psInsert.setDateTime(2, DateTime.now()) psInsert.update() // 创建保存点 3 tx.save(save3) psInsert.setString(0, mkyong) psInsert.setArrayByte(1, ArrayByte(5, {i UInt8(i 1)})) psInsert.update() // 回滚到保存点 2 tx.rollback(save2) // 提交事务 tx.commit() } catch (e1: SqlException) { e1.printStackTrace() try { // 发生异常回滚所有事务 tx.rollback() } catch (e2: SqlException) { e2.printStackTrace() } } } catch (e: SqlException) { e.printStackTrace() } }要点拆解依次创建save1、save2、save3三个保存点每插入一条数据前先建一个保存点形成分段提交的结构tx.rollback(save2)撤销save2之后即第三条插入的修改而save2之前的两条插入保留最终tx.commit()提交此时数据库只包含保留的两条记录——保存点让部分成功成为可能避免因单条失败而丢弃全部工作若中途抛出SqlException外层catch仍以tx.rollback()全量回滚兜底。异常处理SqlExceptionTransaction的全部方法在失败时统一抛出 SqlException。该类继承自Exception提供三种构造函数与三项诊断属性public open class SqlException : Exception { public init() public init(message: String) public init(message: String, sqlState: String, errorCode: Int64) }属性类型含义messageString异常信息字符串sqlStateString长度为五个字符的字符串是数据库系统返回的最后执行的 sql 语句状态errorCodeInt64数据库供应商返回的整数错误代码在事务编程中SqlException可能出现的典型时机包括begin()/commit()/rollback()时服务器端发生错误、事务已提交或回滚、连接已断开以及createTransaction()时已处于事务状态且驱动不支持并行事务。建议按示例中的分层捕获方式处理外层捕获连接与事务异常内层捕获rollback()自身失败并利用sqlState与errorCode辅助定位数据库端错误。小结Transaction接口为仓颉数据库编程提供了统一且完备的事务抽象生命周期控制begin()开始、commit()提交、rollback()回滚构成事务的完整闭环保存点精细化控制save()创建检查点、rollback(savePointName)部分回滚、release()释放资源实现事务内局部撤销三项可配置属性accessMode读写模式、deferrableMode延迟模式、isoLevel隔离级别分别由TransactionAccessMode、TransactionDeferrableMode、TransactionIsoLevel三个枚举提供取值且均支持toString()字符串输出与相等性比较统一的异常模型所有方法失败时抛出SqlException携带sqlState与errorCode便于诊断。配合 database_sql 包 readme 中的完整 API 索引与 事务示例开发者可以快速在仓颉项目中搭建具备事务能力的数据访问层。使用时请以实际数据库驱动支持的特性为准尤其是保存点与延迟模式是否可用。赞分享人工智能AI 技能文档开发工具【免费下载链接】DocAgent项目地址https://gitcode.com/Cangjie-SIG/DocAgent点击查看免费下载相关推荐仓颉 std.database.sql 事务控制实战Transaction 接口、保存点与回滚机制详解仓颉 std.database.sql 事务控制实战Transaction 接口、保存点与回滚机制详解 在仓颉程序里操作数据库时多步写入要么全部生效、要么文档知识库教程OpenHarmony仓颉 std.database.sql 事务隔离级别枚举 TransactionIsoLevel 全解析仓颉 std.database.sql 事务隔离级别枚举 TransactionIsoLevel 全解析 TransactionIsoLevel 是仓颉标准库人工智能AI 技能文档开发工具仓颉 std.database.sql 事务控制实战commit、rollback 与保存点Savepoint深度解析仓颉 std.database.sql 事务控制实战commit、rollback 与保存点Savepoint深度解析 本文以仓颉标准库 std.data编程语言语言运行时标准库垃圾回收并发编程上一篇抖音视频下载终极指南从零开始掌握无水印批量下载技巧下一篇如何快速部署抖音无水印下载器面向新手的完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考