Metadata-Version: 2.1
Name: django-admin-cursor-paginator
Version: 0.1.6
Summary: Drop-in replacement for django admin default pagination that works fast with huge tables.
Home-page: https://github.com/a1tus/django-admin-cursor-paginator
Download-URL: https://pypi.org/project/django-admin-cursor-paginator/
Author: Ilya Melnitskiy
Author-email: mortas.11@gmail.com
License: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 2.0
Classifier: Framework :: Django :: 2.1
Classifier: Framework :: Django :: 2.2
Classifier: Framework :: Django :: 3.0
Classifier: Framework :: Django :: 3.1
Classifier: Framework :: Django :: 3.2
Classifier: Framework :: Django :: 4.0
Classifier: Framework :: Django :: 4.1
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.0
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.4
Description-Content-Type: text/markdown
License-File: LICENSE

# django-admin-cursor-paginator

Drop-in replacement for django admin default pagination that works fast with huge tables.


## Prerequisites

- You are using django (>2.0) admin
- Some of your models/tables contains so much data that list page lags
- You don't want to make separate CRM page for them and just need fast and simple solution
- You're ok that you won't see total objects or pages count and will navigate only by +-1 page
- Index must be created for the ordering field, otherwise you won't get any significant speedup
  (default integer pks work perfectly out-of-box)
- Ordering field type can be almost anything that can be "encoded" via `str()`
  and then be used in `queryset.filter()`

> **NOTE**  
> If ordering field is not unique then pagination can mess a bit in edge cases.
> But for the most often case with datetime fields with milliseconds like `created_at` it won't be a problem.
> It can be solved in future by adding support for multiple ordering fields.


## Installation

All you need is to install it via `pip` like that:

```shell
pip install django-admin-cursor-paginator
```

...and extend `INSTALLED_APPS` (it is needed only for templates):

```python
INSTALLED_APPS = [
    'django.contrib.admin',
    # ...
    'admin_cursor_paginator',
    # ...
]
```

> **NOTE**  
> This app overrides `{% block pagination %}` in default `change_list.html`
> to insert custom pagination template tag, so if you use patched `change_list.html` too,
> don't forget to copy pagination block or (seems better) to inherit this app tpl like
> `{% extends 'admin_cursor_paginator/change_list.html' %}`.
>
> Also, there's a known [issue with grapelli](https://github.com/a1tus/django-admin-cursor-paginator/issues/4) that is fixed the same way. 


## Usage example

So this app will certainly help you if you're using admin to see some (usually) last inserted entries
and may be also want to search for particular objects.

But anyways it's just a regular django admin page.

```python
from admin_cursor_paginator import CursorPaginatorAdmin

class YourModelAdmin(CursorPaginatorAdmin):
    cursor_ordering_field = '-created_at'  # default is '-pk'

class AnotherModelAdmin(CursorPaginatorAdmin):
    cursor_ordering_field = 'parent__sort'  # joins are supported as well
```


## The problem

Default django admin list view makes several queries to show data.
The first one is something like `select count(*) from app_model` to calculate pages range
and `select * from app_model limit 10 offset 1000` to fetch current page data.
Both of them start to produce performance problems as your table grows.

For example, with >1M entries in postgresql table `count(*)` took a few seconds (in our case) because of seq scan. 
Limit+offset also performs badly on far pages.


## The solution

The solution is to use cursor pagination instead of default one (you can find many standalone packages for it).
It doesn't need `count(*)` query at all and performs fast by using filter instead of limit+offset.

Some useful links:
- https://cra.mr/2011/03/08/building-cursors-for-the-disqus-api/
- https://www.django-rest-framework.org/api-guide/pagination/#cursorpagination
- https://hakibenita.com/optimizing-the-django-admin-paginator


## Test project

In `testproject` folder you can (surprisingly) find test project that uses this app
for one model so that you can see live example and check how it works if you want.

All you need is to install requirements from `requirements.txt` in some env,
run `./manage.py runserver`, login as admin:admin to django admin and open `Product` list.

Project includes sqlite3 file with some test data and preinstalled `debug_toolbar`
to observe db queries.

You can play with ordering field or data amount or may be test it in your target db.

Example of how pagination will look like:

![](assets/testproject-example.png)
