TigerBeetle Ruby gem 迁移指南从第三方 0.0.x 到官方客户端的 API 升级全解析【免费下载链接】tigerbeetleThe financial transactions database designed for mission critical safety and performance.项目地址: https://gitcode.com/GitHub_Trending/ti/tigerbeetleTigerBeetle 的 Ruby 客户端gem在从 0.0.x 演进到 0.x.y 的过程中所有权由第三方开发者 Anthony D 移交给了 TigerBeetle 官方团队API 也随之发生了系统性调整。本文基于仓库内 migration.md 官方迁移文档逐项拆解连接方式、回调 API、参数传递、标志位处理、时间戳类型、返回值对象、异常体系等全部破坏性变更并结合 client.rb、bindings.rb、completion_dispatcher.rb 等源码佐证底层实现帮助你完成一次无痛升级直接上手官方 gem 的推荐用法。迁移背景一次所有权交接带来的 API 收敛TigerBeetle Ruby gem 在 0.0.x 时代由第三方开发者 Anthony D 维护整体 API 与官方其他语言客户端存在差异。在 0.x.y 版本中gem 正式转为 TigerBeetle 官方维护团队在保持整体 API 相似的前提下对若干细节做了收敛处理使其与官方提供的 C、Go、Java、Node、Python、Rust 等客户端体验保持一致。官方在 README.md 的开头也明确提示如果你正在从 0.0.x 版本升级务必参照本迁移指南完成必要的代码改动。以下是本次迁移涉及的全部变更点速览变更领域0.0.x旧0.x.y新连接方式TigerBeetle.connect含默认参数TigerBeetle::Client.new(cluster_id:, replica_addresses:)推荐Client.open块式管理异步 API基于回调callback移除回调改为 fiber-scheduler 感知天然兼容asyncgem参数传递支持 splat 可变参数一律要求显式数组标志位符号数组如[:DEBITS, :CREDITS]数值常量按位或如A \| B时间戳Time对象Integer单位纳秒自 UNIX 纪元起返回值FFI::Struct/Struct风格支持[]取字段普通 Ruby 类用方法访问字段create 返回值二元数组[index, status]结果对象result.timestamp/result.status异常体系TigerBeetle::Error→TigerBeetle::ClientErrorTigerBeetle::InitError/ClientClosedError/PacketError日志client.logger移除日志交由应用层处理顶层别名无可选启用TB别名许可证Apache 2.0无变化仍为 Apache 2.0连接方式从connect到显式构造与块式生命周期TigerBeetle.connect已被移除旧版本通过TigerBeetle.connect即可使用默认配置cluster_id为 0、默认地址127.0.0.1:3000快速连接新版本中该方法被移除且TigerBeetle::Client.new不再提供默认参数两个必填关键字参数必须显式给出# Before0.0.x client TigerBeetle.connect # 使用默认 cluster_id (0) 和地址 (127.0.0.1:3000) # After0.x.y client TigerBeetle::Client.new(cluster_id: 0, replica_addresses: 127.0.0.1:3000)首选Client.open管理生命周期推荐的生命周期管理方式是TigerBeetle::Client.open它在块结束时自动关闭连接避免手动关闭遗漏导致资源泄漏replica_addresses ENV.fetch(TB_ADDRESS, 3000) TigerBeetle::Client.open(cluster_id: 0, replica_addresses:) do |client| # 使用 client。 end如果需要手动管理生命周期旧的client.deinit被client.close取代。从源码实现看client.rb 中open的本质是newensure client.close而close会先校验是否已关闭已关闭则抛出ClientClosedError再调用原生层关闭def self.open(cluster_id:, replica_addresses:) client new(cluster_id: cluster_id, replica_addresses: replica_addresses) yield client ensure client.close end关于连接地址的合法写法官方 README.md 给出了三种形式3000—— 解释为127.0.0.1:3000127.0.0.1:3000—— 解释为127.0.0.1:3000127.0.0.1—— 解释为127.0.0.1:30013001是默认端口客户端是线程安全的官方建议在多个并发任务之间共享同一个实例以便利用 自动批量请求batching 机制提升吞吐仅在需要连接多个 TigerBeetle 集群时才创建多个客户端。回调 API改为 fiber-scheduler 感知的同步接口旧版本的异步接口基于回调# Before client.lookup_accounts(100) do |result| result # [#struct TigerBeetle::Account id100, ... ] end新版本中回调式异步 API 被彻底移除。TigerBeetle::Client现在对 fiber scheduler 感知可以直接与asyncgem 配合使用而无需额外改造# After require async require async/semaphore require tigerbeetle semaphore Async::Semaphore.new(16) account_batches [...] # 构造账户批次 TigerBeetle::Client.open(cluster_id: 0, replica_addresses: 3000) do |client| Async do account_batches .map { |batch| semaphore.async { client.create_accounts(batch) } } .each(:wait) end end这套“并发时让出调度器”的语义在源码中有清晰体现。CompletionDispatcher见 completion_dispatcher.rb内部使用IO.pipe与原生层通信原生扩展在请求完成时向 pipe 写入完成 ID调度线程从read_io读取后通过MutexConditionVariable唤醒等待方。Client的公开请求方法create_accounts、lookup_accounts等在 client.rb 中均收敛到私有方法native_submitdef native_submit(operation, payload) raise ClientClosedError if closed? req COMPLETION_DISPATCHER.submit_and_wait_for(native, operation, payload) status, result req.result raise ClientClosedError if status PACKET_CLIENT_SHUTDOWN raise PacketError, status unless status PACKET_OK result end即每个请求方法都是同步返回结果但当 fiber scheduler 活跃时等待响应期间会 yield 给调度器从而让同一线程内的其他 fiber 得以推进。参数传递splat 参数统一改为显式数组所有此前接受 splat 可变参数的方法现在一律要求显式传入数组# Before account_1, account_2 client.lookup_accounts(100, 101) # After account_1, account_2 client.lookup_accounts([100, 101])这一改动与 Ruby 官方客户端的批量语义一致——lookup 本身是批量操作传数组能让“一次调用携带尽可能多的 ID”这一最佳实践变得直白默认最大批量为 8189见 README.md。在 client.rb 中lookup_accounts(ids)/lookup_transfers(ids)接收的即是数组而过滤器类方法get_account_transfers(filter)等则在内部包一层[filter]后提交。标志位处理从符号数组到数值常量按位或所有 flags 字段从符号数组改为显式数值常量通过|组合。这是与官方其他语言客户端位掩码语义对齐的关键改动# Before filter TigerBeetle::AccountFilter.new( account_id: 100, limit: 10, flags: [:DEBITS, :CREDITS] ) transfers client.get_account_transfers(filter) # After filter TigerBeetle::AccountFilter.new( account_id: 100, limit: 10, flags: TigerBeetle::AccountFilterFlags::DEBITS | TigerBeetle::AccountFilterFlags::CREDITS ) transfers client.get_account_transfers(filter)从自动生成的 bindings.rb 可以看到这些常量就是1 n形式的整型位module AccountFlags NONE 0 LINKED 1 0 DEBITS_MUST_NOT_EXCEED_CREDITS 1 1 CREDITS_MUST_NOT_EXCEED_DEBITS 1 2 HISTORY 1 3 IMPORTED 1 4 CLOSED 1 5 end module TransferFlags NONE 0 LINKED 1 0 PENDING 1 1 POST_PENDING_TRANSFER 1 2 VOID_PENDING_TRANSFER 1 3 BALANCING_DEBIT 1 4 BALANCING_CREDIT 1 5 CLOSING_DEBIT 1 6 CLOSING_CREDIT 1 7 IMPORTED 1 8 end此外还有AccountFilterFlagsNONE/DEBITS/CREDITS/REVERSED与QueryFilterFlagsNONE/REVERSED。这些绑定文件并非手写而是由 ruby_bindings.zig 自动生成文件头也标注了“Do not manually modify”迁移时只需按新常量名改代码无需关心底层数值。时间戳属性从Time变为纳秒级Integer所有时间戳属性的类型从Time改为Integer表示自 UNIX 纪元以来的纳秒数# Before account.timestamp # 2026-06-22 11:49:05 1382929/2097152 0100 # After account.timestamp # 1782125345659431936受影响属性清单如下迁移时需要逐一检查TigerBeetle::Account#timestamp TigerBeetle::AccountBalance#timestamp TigerBeetle::AccountFilter#timestamp_min TigerBeetle::AccountFilter#timestamp_max TigerBeetle::QueryFilter#timestamp_min TigerBeetle::QueryFilter#timestamp_max TigerBeetle::Transfer#timestamp这一改动与 TigerBeetle 全局的时间模型一致参见 时间与时钟文档纳秒整数便于直接比较、存储和跨语言传递也避免Time对象在 Ruby 内部表示上的精度损失。值得留意的是TigerBeetle 的 ID 生成同样基于高精度时钟TigerBeetle.id见 id.rb生成 128 位、基于时间且单调递增的 ID——高 48 位是毫秒时间戳低 80 位是随机单调递增计数。返回值对象从 FFI::Struct 到普通 Ruby 类旧版本返回的账户/转账对象是FFI::Struct/Struct风格可以用[]下标访问字段新版本改为普通 Ruby 类必须使用方法访问# Before account[:debits_posted] # After account.debits_posted创建类操作create_accounts/create_transfers的返回类型也从“二元数组”改为结果对象# Before index, status result # After result.timestamp result.status在 bindings.rb 中可以看到CreateAccountResult/CreateTransferResult是带timestamp、status、status_name三个只读属性的普通类并通过to_s输出形如#TigerBeetle::CreateAccountResult timestamp... status_name...的可读字符串。而Account/Transfer/AccountFilter/QueryFilter等结构体类均提供带默认值的initialize如id: 0、ledger: 0、code: 0因此迁移后构造对象的代码通常只变标志位写法、不变字段名。异常体系更细粒度的三层错误类异常类的层次结构发生了调整# Before StandardError TigerBeetle::Error TigerBeetle::ClientError # After StandardError TigerBeetle::InitError TigerBeetle::ClientClosedError TigerBeetle::PacketError新体系把三种失败场景区分开TigerBeetle::InitError原生客户端初始化失败时抛出client.rb 中initialize的文档注释明确标注raise [TigerBeetle::InitError]。TigerBeetle::ClientClosedError对已关闭客户端发起请求、或请求因客户端关闭shutdown而中断时抛出。TigerBeetle::PacketError整个请求批次失败如网络层错误时抛出批次内单个事件的成功/失败则由结果对象的status字段表达。错误类的定义在 tigerbeetle.rbsRBS 类型签名中有对应声明三者均直接继承StandardError与旧版TigerBeetle::Error → TigerBeetle::ClientError的层级不再兼容。迁移时需要把rescue TigerBeetle::ClientError改为按新语义分别处理。日志client.logger已移除旧的client.loggerAPI 已被移除。任何日志记录都应在应用层代码中完成gem 本身不再承担日志配置职责。迁移时只需删除对client.logger的调用并如有需要在应用侧自行接入Logger等设施。TB顶层别名可选的简洁写法新 gem 提供了顶层TB别名但它是 opt-in 的——普通的require tigerbeetle不会定义它需要显式引入require tigerbeetle/tb account TB::Account.new(id: TB.id, ledger: 1, code: 1)从 tb.rb 源码看该文件只有两行本质就是把TB绑定到TigerBeetle模块require tigerbeetle TB TigerBeetle官方 README.md 同样强调别名是可选功能不会通过require tigerbeetle隐式生效。如果你的应用不想全局占用TB常量名完全可以不 require 这个文件。许可证无变化本次迁移不涉及许可证变更gem 仍保持 Apache License, Version 2.0 发布。迁移后实践一个完整的官方客户端示例迁移完成后可以用官方 basic 示例 作为验证基线。它展示了新 API 的完整闭环创建两个账户 → 创建一笔转账 → 批量查询并校验余额require tigerbeetle replica_addresses ENV.fetch(TB_ADDRESS, 3000) TigerBeetle::Client.open(cluster_id: 0, replica_addresses:) do |client| account_results client.create_accounts( [ TigerBeetle::Account.new(id: 1, ledger: 1, code: 1), TigerBeetle::Account.new(id: 2, ledger: 1, code: 1) ] ) transfer_results client.create_transfers( [ TigerBeetle::Transfer.new( id: 1, debit_account_id: 1, credit_account_id: 2, amount: 10, ledger: 1, code: 1 ) ] ) accounts client.lookup_accounts([1, 2]) accounts.each do |account| # account.debits_posted / account.credits_posted 校验… end end对照本指南的变更点可以看到这段新代码的全部特征Client.open块式生命周期、显式数组参数、方法式字段访问account.debits_posted、create_*返回结果对象account_results[0].status TigerBeetle::CreateAccountStatus::CREATED。运行前请先按 仓库 README 启动 TigerBeetle 服务端若服务不在localhost:3000通过环境变量TB_ADDRESS指定完整地址即可详见 basic 示例说明。迁移检查清单最后把官方迁移文档浓缩为一张可直接对照执行的清单将所有TigerBeetle.connect改为TigerBeetle::Client.new(cluster_id:..., replica_addresses:...)并优先改用Client.open块式写法手动场景用close替代deinit。删除所有回调式异步调用改用 fiber-scheduler 感知的同步方法 async/Async::Semaphore并发模式。把所有 splat 调用如lookup_accounts(100, 101)改为显式数组lookup_accounts([100, 101])。把所有符号数组 flags如[:DEBITS, :CREDITS]替换为TigerBeetle::*Flags数值常量按位或。将Time类型的timestamp/timestamp_min/timestamp_max属性按纳秒整数处理。将account[:field]改为account.field将 create 返回的二元数组解构改为访问result.timestamp/result.status。将rescue TigerBeetle::ClientError调整为InitError/ClientClosedError/PacketError三者的对应处理。移除client.logger配置日志改由应用层负责。如需简短命名require tigerbeetle/tb启用TB顶层别名。按此清单逐项核对即可平稳完成从第三方 0.0.x 到官方 gem 的迁移并享受与 TigerBeetle 其他官方语言客户端一致的 API 体验。【免费下载链接】tigerbeetleThe financial transactions database designed for mission critical safety and performance.项目地址: https://gitcode.com/GitHub_Trending/ti/tigerbeetle创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 TigerBeetle Ruby gem 迁移指南：从第三方 0.0.x 到官方客户端的 API 升级全解析
TigerBeetle Ruby gem 迁移指南从第三方 0.0.x 到官方客户端的 API 升级全解析【免费下载链接】tigerbeetleThe financial transactions database designed for mission critical safety and performance.项目地址: https://gitcode.com/GitHub_Trending/ti/tigerbeetleTigerBeetle 的 Ruby 客户端gem在从 0.0.x 演进到 0.x.y 的过程中所有权由第三方开发者 Anthony D 移交给了 TigerBeetle 官方团队API 也随之发生了系统性调整。本文基于仓库内 migration.md 官方迁移文档逐项拆解连接方式、回调 API、参数传递、标志位处理、时间戳类型、返回值对象、异常体系等全部破坏性变更并结合 client.rb、bindings.rb、completion_dispatcher.rb 等源码佐证底层实现帮助你完成一次无痛升级直接上手官方 gem 的推荐用法。迁移背景一次所有权交接带来的 API 收敛TigerBeetle Ruby gem 在 0.0.x 时代由第三方开发者 Anthony D 维护整体 API 与官方其他语言客户端存在差异。在 0.x.y 版本中gem 正式转为 TigerBeetle 官方维护团队在保持整体 API 相似的前提下对若干细节做了收敛处理使其与官方提供的 C、Go、Java、Node、Python、Rust 等客户端体验保持一致。官方在 README.md 的开头也明确提示如果你正在从 0.0.x 版本升级务必参照本迁移指南完成必要的代码改动。以下是本次迁移涉及的全部变更点速览变更领域0.0.x旧0.x.y新连接方式TigerBeetle.connect含默认参数TigerBeetle::Client.new(cluster_id:, replica_addresses:)推荐Client.open块式管理异步 API基于回调callback移除回调改为 fiber-scheduler 感知天然兼容asyncgem参数传递支持 splat 可变参数一律要求显式数组标志位符号数组如[:DEBITS, :CREDITS]数值常量按位或如A \| B时间戳Time对象Integer单位纳秒自 UNIX 纪元起返回值FFI::Struct/Struct风格支持[]取字段普通 Ruby 类用方法访问字段create 返回值二元数组[index, status]结果对象result.timestamp/result.status异常体系TigerBeetle::Error→TigerBeetle::ClientErrorTigerBeetle::InitError/ClientClosedError/PacketError日志client.logger移除日志交由应用层处理顶层别名无可选启用TB别名许可证Apache 2.0无变化仍为 Apache 2.0连接方式从connect到显式构造与块式生命周期TigerBeetle.connect已被移除旧版本通过TigerBeetle.connect即可使用默认配置cluster_id为 0、默认地址127.0.0.1:3000快速连接新版本中该方法被移除且TigerBeetle::Client.new不再提供默认参数两个必填关键字参数必须显式给出# Before0.0.x client TigerBeetle.connect # 使用默认 cluster_id (0) 和地址 (127.0.0.1:3000) # After0.x.y client TigerBeetle::Client.new(cluster_id: 0, replica_addresses: 127.0.0.1:3000)首选Client.open管理生命周期推荐的生命周期管理方式是TigerBeetle::Client.open它在块结束时自动关闭连接避免手动关闭遗漏导致资源泄漏replica_addresses ENV.fetch(TB_ADDRESS, 3000) TigerBeetle::Client.open(cluster_id: 0, replica_addresses:) do |client| # 使用 client。 end如果需要手动管理生命周期旧的client.deinit被client.close取代。从源码实现看client.rb 中open的本质是newensure client.close而close会先校验是否已关闭已关闭则抛出ClientClosedError再调用原生层关闭def self.open(cluster_id:, replica_addresses:) client new(cluster_id: cluster_id, replica_addresses: replica_addresses) yield client ensure client.close end关于连接地址的合法写法官方 README.md 给出了三种形式3000—— 解释为127.0.0.1:3000127.0.0.1:3000—— 解释为127.0.0.1:3000127.0.0.1—— 解释为127.0.0.1:30013001是默认端口客户端是线程安全的官方建议在多个并发任务之间共享同一个实例以便利用 自动批量请求batching 机制提升吞吐仅在需要连接多个 TigerBeetle 集群时才创建多个客户端。回调 API改为 fiber-scheduler 感知的同步接口旧版本的异步接口基于回调# Before client.lookup_accounts(100) do |result| result # [#struct TigerBeetle::Account id100, ... ] end新版本中回调式异步 API 被彻底移除。TigerBeetle::Client现在对 fiber scheduler 感知可以直接与asyncgem 配合使用而无需额外改造# After require async require async/semaphore require tigerbeetle semaphore Async::Semaphore.new(16) account_batches [...] # 构造账户批次 TigerBeetle::Client.open(cluster_id: 0, replica_addresses: 3000) do |client| Async do account_batches .map { |batch| semaphore.async { client.create_accounts(batch) } } .each(:wait) end end这套“并发时让出调度器”的语义在源码中有清晰体现。CompletionDispatcher见 completion_dispatcher.rb内部使用IO.pipe与原生层通信原生扩展在请求完成时向 pipe 写入完成 ID调度线程从read_io读取后通过MutexConditionVariable唤醒等待方。Client的公开请求方法create_accounts、lookup_accounts等在 client.rb 中均收敛到私有方法native_submitdef native_submit(operation, payload) raise ClientClosedError if closed? req COMPLETION_DISPATCHER.submit_and_wait_for(native, operation, payload) status, result req.result raise ClientClosedError if status PACKET_CLIENT_SHUTDOWN raise PacketError, status unless status PACKET_OK result end即每个请求方法都是同步返回结果但当 fiber scheduler 活跃时等待响应期间会 yield 给调度器从而让同一线程内的其他 fiber 得以推进。参数传递splat 参数统一改为显式数组所有此前接受 splat 可变参数的方法现在一律要求显式传入数组# Before account_1, account_2 client.lookup_accounts(100, 101) # After account_1, account_2 client.lookup_accounts([100, 101])这一改动与 Ruby 官方客户端的批量语义一致——lookup 本身是批量操作传数组能让“一次调用携带尽可能多的 ID”这一最佳实践变得直白默认最大批量为 8189见 README.md。在 client.rb 中lookup_accounts(ids)/lookup_transfers(ids)接收的即是数组而过滤器类方法get_account_transfers(filter)等则在内部包一层[filter]后提交。标志位处理从符号数组到数值常量按位或所有 flags 字段从符号数组改为显式数值常量通过|组合。这是与官方其他语言客户端位掩码语义对齐的关键改动# Before filter TigerBeetle::AccountFilter.new( account_id: 100, limit: 10, flags: [:DEBITS, :CREDITS] ) transfers client.get_account_transfers(filter) # After filter TigerBeetle::AccountFilter.new( account_id: 100, limit: 10, flags: TigerBeetle::AccountFilterFlags::DEBITS | TigerBeetle::AccountFilterFlags::CREDITS ) transfers client.get_account_transfers(filter)从自动生成的 bindings.rb 可以看到这些常量就是1 n形式的整型位module AccountFlags NONE 0 LINKED 1 0 DEBITS_MUST_NOT_EXCEED_CREDITS 1 1 CREDITS_MUST_NOT_EXCEED_DEBITS 1 2 HISTORY 1 3 IMPORTED 1 4 CLOSED 1 5 end module TransferFlags NONE 0 LINKED 1 0 PENDING 1 1 POST_PENDING_TRANSFER 1 2 VOID_PENDING_TRANSFER 1 3 BALANCING_DEBIT 1 4 BALANCING_CREDIT 1 5 CLOSING_DEBIT 1 6 CLOSING_CREDIT 1 7 IMPORTED 1 8 end此外还有AccountFilterFlagsNONE/DEBITS/CREDITS/REVERSED与QueryFilterFlagsNONE/REVERSED。这些绑定文件并非手写而是由 ruby_bindings.zig 自动生成文件头也标注了“Do not manually modify”迁移时只需按新常量名改代码无需关心底层数值。时间戳属性从Time变为纳秒级Integer所有时间戳属性的类型从Time改为Integer表示自 UNIX 纪元以来的纳秒数# Before account.timestamp # 2026-06-22 11:49:05 1382929/2097152 0100 # After account.timestamp # 1782125345659431936受影响属性清单如下迁移时需要逐一检查TigerBeetle::Account#timestamp TigerBeetle::AccountBalance#timestamp TigerBeetle::AccountFilter#timestamp_min TigerBeetle::AccountFilter#timestamp_max TigerBeetle::QueryFilter#timestamp_min TigerBeetle::QueryFilter#timestamp_max TigerBeetle::Transfer#timestamp这一改动与 TigerBeetle 全局的时间模型一致参见 时间与时钟文档纳秒整数便于直接比较、存储和跨语言传递也避免Time对象在 Ruby 内部表示上的精度损失。值得留意的是TigerBeetle 的 ID 生成同样基于高精度时钟TigerBeetle.id见 id.rb生成 128 位、基于时间且单调递增的 ID——高 48 位是毫秒时间戳低 80 位是随机单调递增计数。返回值对象从 FFI::Struct 到普通 Ruby 类旧版本返回的账户/转账对象是FFI::Struct/Struct风格可以用[]下标访问字段新版本改为普通 Ruby 类必须使用方法访问# Before account[:debits_posted] # After account.debits_posted创建类操作create_accounts/create_transfers的返回类型也从“二元数组”改为结果对象# Before index, status result # After result.timestamp result.status在 bindings.rb 中可以看到CreateAccountResult/CreateTransferResult是带timestamp、status、status_name三个只读属性的普通类并通过to_s输出形如#TigerBeetle::CreateAccountResult timestamp... status_name...的可读字符串。而Account/Transfer/AccountFilter/QueryFilter等结构体类均提供带默认值的initialize如id: 0、ledger: 0、code: 0因此迁移后构造对象的代码通常只变标志位写法、不变字段名。异常体系更细粒度的三层错误类异常类的层次结构发生了调整# Before StandardError TigerBeetle::Error TigerBeetle::ClientError # After StandardError TigerBeetle::InitError TigerBeetle::ClientClosedError TigerBeetle::PacketError新体系把三种失败场景区分开TigerBeetle::InitError原生客户端初始化失败时抛出client.rb 中initialize的文档注释明确标注raise [TigerBeetle::InitError]。TigerBeetle::ClientClosedError对已关闭客户端发起请求、或请求因客户端关闭shutdown而中断时抛出。TigerBeetle::PacketError整个请求批次失败如网络层错误时抛出批次内单个事件的成功/失败则由结果对象的status字段表达。错误类的定义在 tigerbeetle.rbsRBS 类型签名中有对应声明三者均直接继承StandardError与旧版TigerBeetle::Error → TigerBeetle::ClientError的层级不再兼容。迁移时需要把rescue TigerBeetle::ClientError改为按新语义分别处理。日志client.logger已移除旧的client.loggerAPI 已被移除。任何日志记录都应在应用层代码中完成gem 本身不再承担日志配置职责。迁移时只需删除对client.logger的调用并如有需要在应用侧自行接入Logger等设施。TB顶层别名可选的简洁写法新 gem 提供了顶层TB别名但它是 opt-in 的——普通的require tigerbeetle不会定义它需要显式引入require tigerbeetle/tb account TB::Account.new(id: TB.id, ledger: 1, code: 1)从 tb.rb 源码看该文件只有两行本质就是把TB绑定到TigerBeetle模块require tigerbeetle TB TigerBeetle官方 README.md 同样强调别名是可选功能不会通过require tigerbeetle隐式生效。如果你的应用不想全局占用TB常量名完全可以不 require 这个文件。许可证无变化本次迁移不涉及许可证变更gem 仍保持 Apache License, Version 2.0 发布。迁移后实践一个完整的官方客户端示例迁移完成后可以用官方 basic 示例 作为验证基线。它展示了新 API 的完整闭环创建两个账户 → 创建一笔转账 → 批量查询并校验余额require tigerbeetle replica_addresses ENV.fetch(TB_ADDRESS, 3000) TigerBeetle::Client.open(cluster_id: 0, replica_addresses:) do |client| account_results client.create_accounts( [ TigerBeetle::Account.new(id: 1, ledger: 1, code: 1), TigerBeetle::Account.new(id: 2, ledger: 1, code: 1) ] ) transfer_results client.create_transfers( [ TigerBeetle::Transfer.new( id: 1, debit_account_id: 1, credit_account_id: 2, amount: 10, ledger: 1, code: 1 ) ] ) accounts client.lookup_accounts([1, 2]) accounts.each do |account| # account.debits_posted / account.credits_posted 校验… end end对照本指南的变更点可以看到这段新代码的全部特征Client.open块式生命周期、显式数组参数、方法式字段访问account.debits_posted、create_*返回结果对象account_results[0].status TigerBeetle::CreateAccountStatus::CREATED。运行前请先按 仓库 README 启动 TigerBeetle 服务端若服务不在localhost:3000通过环境变量TB_ADDRESS指定完整地址即可详见 basic 示例说明。迁移检查清单最后把官方迁移文档浓缩为一张可直接对照执行的清单将所有TigerBeetle.connect改为TigerBeetle::Client.new(cluster_id:..., replica_addresses:...)并优先改用Client.open块式写法手动场景用close替代deinit。删除所有回调式异步调用改用 fiber-scheduler 感知的同步方法 async/Async::Semaphore并发模式。把所有 splat 调用如lookup_accounts(100, 101)改为显式数组lookup_accounts([100, 101])。把所有符号数组 flags如[:DEBITS, :CREDITS]替换为TigerBeetle::*Flags数值常量按位或。将Time类型的timestamp/timestamp_min/timestamp_max属性按纳秒整数处理。将account[:field]改为account.field将 create 返回的二元数组解构改为访问result.timestamp/result.status。将rescue TigerBeetle::ClientError调整为InitError/ClientClosedError/PacketError三者的对应处理。移除client.logger配置日志改由应用层负责。如需简短命名require tigerbeetle/tb启用TB顶层别名。按此清单逐项核对即可平稳完成从第三方 0.0.x 到官方 gem 的迁移并享受与 TigerBeetle 其他官方语言客户端一致的 API 体验。【免费下载链接】tigerbeetleThe financial transactions database designed for mission critical safety and performance.项目地址: https://gitcode.com/GitHub_Trending/ti/tigerbeetle创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考