Skip to content

Commit

Permalink
Add explanation to README.md about ordering by arbitrary SQL
Browse files Browse the repository at this point in the history
The gem in its current version does not allow ordering by any arbitrary
SQL statements. Only SQL columns can be used.

This is on one side due to performance reasons, but on the other side
also due to the added high complexity of supporting arbitrary SQL
queries. We would have to ensure that it doesn't open the door for SQL
injection attacks. We would also have to return the value of this query
so that it can be properly encoded into the cursor.

For now, this is out of scope for this gem.
  • Loading branch information
nicolas-fricke committed Apr 19, 2021
1 parent f790973 commit 7c7dbaf
Show file tree
Hide file tree
Showing 2 changed files with 27 additions and 1 deletion.
5 changes: 4 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,14 +21,17 @@ These are the latest changes on the project's `master` branch that have not yet
### Fixed
- Only trigger one SQL query to load the records from the database and use it to determine if there was a previous / is a next page

### Added
- Description about `order_by` on arbitrary SQL to README.md

## [0.1.3] - 2021-03-17

### Changed
- Make the gem publicly available via github.com/xing/rails_cursor_pagination and release it to Rubygems.org
- Reference changelog file in the gemspec instead of the general releases Github tab

### Removed
- Remove bulk from release: The previous gem releases contained files like the content of the `bin` folder or the Gemfile used for testing. Since this is not useful for gem users, adjust the gemspec file accordingly.
- Remove bulk from release: The previous gem releases contained files like the content of the `bin` folder or the Gemfile used for testing. Since this is not useful for gem users, adjust the gemspec file accordingly.

## [0.1.2] - 2021-02-04

Expand Down
23 changes: 23 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -178,6 +178,29 @@ end
```

Please take a look at the _"How does it work?"_ to find out more why this is necessary.

#### Order by more complex logic

Sometimes you might not only want to oder by a column ascending or descending, but need more complex logic.
Imagine you would also store the post's `category` on the `posts` table (as a plain string for simplicity's sake).
And the category could be `pinned`, `announcement`, or `general`.
Then you might want to show all `pinned` posts first, followed by the `announcement` ones and lastly show the `general` posts.

In MySQL you could e.g. use a `FIELD(category, 'pinned', 'announcement', 'general')` query in the `ORDER BY` clause to achieve this.
However, you cannot add an index to such a statement.
And therefore, the performance of this is – especially when using cursor pagination where we not only have an `ORDER BY` clause but also need it twice in the `WHERE` clauses – is pretty dismal.

For this reason, the gem currently only supports ordering by natural columns of the relation.
You **cannot** pass a generic SQL query to the `order_by` parameter.

Implementing support for arbitrary SQL queries would also be fairly complex to handle in this gem.
We would have to ensure that SQL injection attacks aren't possible by passing malicious code to the `oder_by` parameter.
And we would need to return the data produced by the statement so that it can be encoded in the cursor.
This is, for now, out of scope of the functionality of this gem.

What is recommended if you _do_ need to order by more complex logic is to have a separate column that you only use for ordering.
You can use `ActiveRecord` hooks to automatically update this column whenever you change your data.
Or, for example in MySQL, you can also use a [generated column](https://dev.mysql.com/doc/refman/5.7/en/create-table-generated-columns.html) that is automatically being updated by the database based on some stored logic.

### Configuration options

Expand Down

0 comments on commit 7c7dbaf

Please sign in to comment.