服务对象与地域限制
PuppyIP 仅面向海外合规企业及其授权人员提供服务，不面向中国大陆地区开放或提供代理服务。本服务仅限用于中国大陆境外的合法业务活动，严禁在中国大陆境内使用本服务。
代理 IP 或服务器位于境外，不改变上述限制。不得通过中转、转接、共享或转售向中国大陆境内的最终使用者提供本服务。使用前请阅读用户服务协议。
本文要点
- AWS于2026年10月5日宣布Ruby Driver Wrapper GA；适用RDS/Aurora的PostgreSQL与MySQL兼容数据库，仍依赖pg或mysql2驱动。
- Rails通过aws_postgresql或aws_mysql2接入。未设置wrapper_plugins时启用failover和initial_connection；显式填写会替换默认列表。
- FailoverSuccessError和TransactionStateUnknownError在ActiveRecord中原样抛出；只有FailoverFailedError转成ActiveRecord::ConnectionFailed。
- 成功切换后的连接通常可以复用，但事务结果、非幂等重试和自定义会话状态仍需应用处理；不能据此保证零中断或固定恢复速度。
先分清连接恢复与事务恢复
AWS在2026年10月5日宣布Advanced Ruby Driver Wrapper正式可用，面向Amazon RDS和Aurora的PostgreSQL与MySQL兼容数据库。它在pg或mysql2上增加集群能力，不替代底层驱动，也不是所有Ruby数据库的通用适配层。
故障切换是主实例不可用后连接到新实例。包装器可以替换内部物理连接，同时保留应用持有的连接对象；这不代表上一条语句已经重放，更不能证明进行中的事务已提交或已回滚。
当前概览要求Ruby 3.3或更高；列出的测试范围是ActiveRecord 7.2、8.0、8.1，pg 1.6.3及以上、mysql2 0.5.7及以上。先核对自己的组合，测试范围不能扩成所有版本均兼容。
接入Rails时，保留驱动并检查默认插件
Gemfile加入gem 'aws_advanced_ruby_driver_wrapper'，并按数据库保留gem 'pg'或gem 'mysql2'；再在自己的受控环境执行bundle install。当前概览说明Bundler会加载包装器，普通Ruby脚本可require 'aws_advanced_ruby_driver_wrapper'。
在config/database.yml将postgresql改为aws_postgresql，或将mysql2改为aws_mysql2，并把host指向对应集群端点。适配器接入可以保留已有ActiveRecord调用与连接池，但异常处理和事务重试仍要单独检查。
wrapper_plugins未设置时加载failover和initial_connection。显式填写该字段会替换默认列表，不是追加；只写iam会遗漏原默认插件。若希望保留它们，应明确列出failover,initial_connection,iam。
插件不是越多越好。iam与secrets_manager不能同时启用；同一连接也不能同时启用failover和gdb_failover。这两类冲突都会在连接初始化时抛出PluginConflictError，应先按认证方式和数据库拓扑选择组合。
按3类错误决定连接与重试动作
FailoverSuccessError表示事务之外的切换已成功，连接有效且可复用。先恢复应用需要的会话状态，再考虑重放被中断的语句；看到这个错误不能直接丢弃已经恢复的连接。
TransactionStateUnknownError表示切换发生时事务仍打开，包装器无法判断原事务是否完成。连接可以复用，但结果要视为未知；涉及扣款、写订单等非幂等操作时，先确认结果，再决定如何重启事务及重放语句。
FailoverFailedError表示本次切换没有连到可用实例，原连接无效。应等待服务器可用再重新连接，而不是把它当作已经恢复；在ActiveRecord路径中，它会被转换为ActiveRecord::ConnectionFailed。
另外两类成功重连错误不会转换成通用ActiveRecord异常，应用实际收到的是AwsAdvancedRubyDriverWrapper::Errors下的原错误类。只处理ActiveRecord::ConnectionFailed会漏掉成功重连和事务结果未知这两条路径。
让连接池继续工作，并恢复必要会话状态
成功切换后，ActiveRecord适配器会重新运行configure_connection，并原位复用池中的连接。此时不要额外调用disconnect!或主动丢弃该对象。切换失败时适配器会标记连接损坏，由连接池在下次取用时处理。
通过适配器variables:声明的会话变量会随configure_connection重新应用，预编译语句缓存也会清理并在下次使用时重新准备。临时表、advisory locks等自定义状态仍需应用重建，不能假定所有会话内容都会转移。
假设一项订单写入在事务中遇到TransactionStateUnknownError，这是未执行的说明场景。应用先查询业务记录确认原写入结果，再按自己的幂等规则决定是否重新提交；连接已恢复本身不能作为再次写入的依据。
自定义端点与多个集群要补足拓扑配置
通过IP、CNAME或自定义域名连接时，包装器可能无法从host推导各实例端点。应设置cluster_instance_host_pattern，用?作为实例标识占位；CNAME或自定义域名还需要设置集群标识。
一项应用使用多个集群时，应为它们设置不同的cluster_id。同一标识会共享拓扑监控器与缓存，不能让不同集群误用同一个身份；标准可识别的RDS端点也不能替代这个多集群检查。
failover_timeout_sec默认300.0秒，是故障切换开始后允许重连的最大时间，不是数据库会在300秒内恢复的保证。监控器会查询拓扑并寻找合适实例，实际恢复仍取决于数据库状态和连接条件。
上线前把支持范围与应用责任分开核对
公告也提到RDS Blue/Green和Aurora Global Database切换能力，但应使用对应插件并核对各自文档。仓库明确Blue/Green需要特定元数据表及受支持的引擎版本，不能仅凭GA公告把所有部署方式都视为可用。
包装器以Apache 2.0开源发布，不等于相关AWS服务免费。上述公告与本文使用的概览、故障切换页没有给出统一地区清单、额外服务费用或恢复时限承诺，实际服务资格与账单仍按所用AWS产品确认。
接入检查可以分四步：核对Ruby、ActiveRecord及底层驱动；确认适配器、端点与插件列表；让应用区分3类错误；明确事务确认、重试及会话恢复责任。能替换适配器不等于可以省掉最后两项。
资料来源
常见问题
不用ActiveRecord，也能使用这个包装器吗？
可以。当前概览提供WrapperPgConnection和WrapperMysql2Client，分别对应pg与mysql2的连接接口。仍需要相应底层驱动，并自行处理包装器错误、事务结果与会话恢复；不能照搬ActiveRecord连接池会代为处理的行为。
Puma预加载或fork型任务进程，需要另外启动拓扑监控吗？
官方故障切换文档说明监控线程不会随fork保留，子进程会在首次使用时启动自己的监控器，并保留父进程的监控连接。文档称此类fork工作进程无需额外配置；这不代替核对应用自身的连接管理。
标准适配器与包装适配器混用，自定义类型会隔离吗？
不会按包装器名称单独隔离。概览说明aws_postgresql与aws_mysql2把类型信息登记在底层postgresql和mysql2键下；同一应用混用标准与包装连接时，为其中一个注册的自定义类型会共享到另一个。