Activerecord::CursorPaginator

This library is an implementation of cursor pagination for ActiveRecord relations based on "https://github.com/xing/rails_cursor_pagination.

Additional features are:

• receives a relation with orders, and it is unnecessary to specify orders to this library separately
• supports bidirectional pagination.

• ActiveRecord
• mysql or Postgresql

Add the following line to your Gemfile and execute bundle install

gem 'active_record-cursor_paginator'

relation = Post.order(...)
page = ActiveRecord::CursorPaginator.new(relation, direction: :forward, cursor: '...', per_page: 10)

This library supports column aliases as below, and extracts aliases from select values automatically.

relation = Post.select('posts.*, authors.name author_name').joins(:author).order(author_name: :desc)
page = ActiveRecord::CursorPaginator.new(relation, direction: :forward, cursor: '...', per_page: 10)

Supported aliases are strings in the format below

• some expression [as|AS] *alias*

Other aliases such as symbols or arel functions are ignored.

• cursor: String - cursor to paginate
• per_page: Integer - record count per page (default to 10)
• direction: Symbol - direction to paginate. :forward (default) or :backward

• page.records: Array - records splitted per page (Notice: not ActiveRecord::Relation but Array)
• page.start_cursor: String - cursor of the first record. used for the backward paginate call.
• page.end_cursor: String - cursor of the last record. used for the forward paginate call.
• page.total: Integer - total count of relation
• page.next_page?: Boolean - whether having the next page forward or not
• page.previous_page?: Boolean - whether having the next page backward or not

You need to specify ActiveSupport::JSON::Encoding.time_precision to use time columns as order keys. It must be equals to the maximum precision of your order keys. Default precision of time columns in Rails is 6. So, please specify as follows in your initializers:

ActiveSupport::JSON::Encoding.time_precision = 6

This library does not support the following order expressions

Post.order(Arel::Nodes::NamedFunction.new('abs', [Post.arel_table[:display_index]])) # order by arel function
Post.order('abs(display_index)') # order by funtion
Post.order('abs(display_index) asc') # order by function and direction

Use aliases.

ADAPTER=mysql bundle exec rspec
ADAPTER=postgresql bundle exec rspec

This library automatically appends id column to sorting and filtering columns, if it is not the last one. This feature may cause unnecessary performance deterioration. So, we plan this feature can be off.

Bug reports and pull requests are welcome on GitHub at https://github.com/ssugiyama/active_record-cursor_paginator. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

The gem is available as open source under the terms of the MIT License.

Everyone interacting in the Activerecord::CursorPagination project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.