5分钟上手postgresql_cursorRails项目安装与快速使用完整指南【免费下载链接】postgresql_cursorActiveRecord PostgreSQL Adapter extension for using a cursor to return a large result set项目地址: https://gitcode.com/gh_mirrors/po/postgresql_cursorpostgresql_cursor 是一款专为 Rails / ActiveRecord 打造的 PostgreSQL 游标扩展 gem它利用数据库原生游标机制分批拉取查询结果让你在处理百万行级大结果集时不再担心内存爆掉。本文带你用 5 分钟完成安装、配置与快速使用轻松解决 Rails 项目中的大数据量处理难题。 postgresql_cursor 解决什么问题在 Rails 项目中一句简单的Product.all会把所有匹配行一次性加载进内存。数据量小的时候没问题但后台任务、离线批处理动辄处理几十万、上百万行时内存会持续膨胀轻则拖慢服务重则进程崩溃。方案能否指定排序主键要求复杂查询内存表现Product.all✅无✅❌ 全量加载find_each/find_in_batches❌ 只能按主键必须是数字每批重新执行查询✅ 分批postgresql_cursor✅ 任意 order无✅ 只执行一次✅ 分批postgresql_cursor 的核心思路在数据库端声明一个游标cursor先执行查询、保留结果集位置应用端每次只FETCH一小批默认 1000 行处理完再继续取直到结果集耗尽。整个查询只跑一次内存占用始终可控。⚡ Rails 项目安装 postgresql_cursor 三步走第一步修改 Gemfile打开项目根目录的Gemfile添加一行依赖gemspec 要求 ActiveRecord 6.0gem postgresql_cursor第二步执行 bundle installbundle install第三步确认自动加载gem 的入口文件 lib/postgresql_cursor.rb 通过ActiveSupport.on_load钩子自动扩展ActiveRecord::Relation和 PostgreSQL 连接适配器无需手动初始化——安装完成即可直接使用each_row等方法。 如果想通读源码或跑演示应用可以克隆仓库查看git clone https://gitcode.com/gh_mirrors/po/postgresql_cursor演示脚本位于test-app/app.rb运行脚本为test-app/run.sh。 快速上手记住 3 个游标方法1️⃣ 逐行处理大数据each_row 与 each_instance这是最核心的两个方法分别返回哈希快适合纯数据处理和模型实例带类型转换适合调用模型方法。二者都支持挂在任意where/order查询条件之后# 返回 Hash性能更好 Product.where(id0).order(name).each_row { |row| Process.run(row) } # 返回 ActiveRecord 实例 Product.where(id0).each_instance { |product| product.process! }2️⃣ 控制批次大小block_size 选项所有方法都接受选项参数block_size决定每次从数据库取多少行默认 1000Product.each_instance(block_size: 100_000) { |p| p.process }3️⃣ 直接执行原始 SQL不经过模型时可用_by_sql系列方法对任意 SQL 建立游标Product.each_row_by_sql(select * from products) { |row| Process.run(row) } 游标进阶技巧让处理更高效加锁批量更新FOR UPDATE配合 ActiveRecord 的lock方法游标每次取回的批次会被FOR UPDATE锁定适合边扫描边更新的场景处理完一批才释放锁兼顾并发安全Product.lock.each_instance(block_size: 100) do |p| p.update!(price: p.price * 1.05) end⚠️ 对繁忙的大表block_size建议 ≤ 100批次太大可能导致锁等待甚至死锁。手动 fetch 必须在事务中游标需要保持在事务内使用。若不传块、手动控制取行节奏记得包一层transactionProduct.transaction do cursor Product.all.each_row cursor.fetch # {id1} cursor.close end支持 Enumerable 链式调用不传块时返回游标对象本身天然支持map、reduce等 Enumerable 操作还能链式lazy保持低内存Product.each_row.map { |r| r[id].to_i }需要类型转换选 each_instanceeach_row返回字符串值如2024-01-01追求极致速度时手动转换即可若依赖Time、数值等 Ruby 类型用each_instance按需惰性转换更省心。官方基准显示返回实例比返回哈希慢约 4 倍可按需取舍。❓ 常见问题FAQQ1小数据量也要用游标吗不建议。游标在数据库端有额外开销日常网页请求几十行直接用 ActiveRecord 即可。游标专为大结果集设计。Q2和 find_each 相比为什么选游标find_each只能按主键顺序、要求数字主键且每批都重新执行查询游标支持任意排序、任意复杂查询且查询只执行一次。Q3支持哪些 Rails 版本当前版本0.6.11要求 ActiveRecord 6.0项目通过Appraisals与gemfiles/目录维护了 Rails 4 / 5 / 6 各版本的兼容性测试。 核心源码文件索引想深入原理可以从这几个文件入手入口与自动加载逻辑lib/postgresql_cursor.rb游标核心实现open / fetch / closelib/postgresql_cursor/cursor.rbRelation 扩展each_row、each_instance 等方法定义lib/postgresql_cursor/active_record/relation/cursor_iterators.rb裸 SQL 游标支持lib/postgresql_cursor/active_record/sql_cursor.rbPostgreSQL 类型映射lib/postgresql_cursor/active_record/connection_adapters/postgresql_type_map.rb完整用法与参数说明README.md功能测试用例test/test_postgresql_cursor.rb✅ 小结postgresql_cursor 用三行安装、一行调用就为 Rails 项目补上了大结果集高效处理这块拼图查询只执行一次、排序完全自由、内存恒定可控。后台任务、数据迁移、批量更新场景都能直接受益5 分钟即可跑通值得每个 Rails PostgreSQL 项目收藏备用。【免费下载链接】postgresql_cursorActiveRecord PostgreSQL Adapter extension for using a cursor to return a large result set项目地址: https://gitcode.com/gh_mirrors/po/postgresql_cursor创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考