https://github.com/glef1x/sqla-pagination
Opinionated and powerful pagination tool for sqlalchemy
https://github.com/glef1x/sqla-pagination
asyncio keyset keyset-pagination keyset-paging keysets pagination pagination-component pagination-components pagination-generator pagination-library sqlalchemy sqlalchemy-orm sqlalchemy-python
Last synced: 17 days ago
JSON representation
Opinionated and powerful pagination tool for sqlalchemy
- Host: GitHub
- URL: https://github.com/glef1x/sqla-pagination
- Owner: GLEF1X
- Created: 2022-03-10T18:32:36.000Z (about 3 years ago)
- Default Branch: master
- Last Pushed: 2024-04-25T06:17:41.000Z (about 1 year ago)
- Last Synced: 2025-05-07T17:14:59.821Z (17 days ago)
- Topics: asyncio, keyset, keyset-pagination, keyset-paging, keysets, pagination, pagination-component, pagination-components, pagination-generator, pagination-library, sqlalchemy, sqlalchemy-orm, sqlalchemy-python
- Language: Python
- Homepage:
- Size: 123 KB
- Stars: 1
- Watchers: 2
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
pagination for humans
## Features
* Support both async and sync sqlalchemy approaches without corrupting and duplicating API
* Include variety of different pagination strategies such as `keyset(infinite scrolling)`, `limit-offset` and others
* Support PEP 484 (typehints) and consequentially static type checking using `mypy`, `pyright` or other tool
* Transparent page abstraction
### Getting started
```python
from sqlalchemy import select, create_engine
from sqlalchemy.orm import sessionmaker
from sqlapagination import LimitOffsetPaginator
engine = create_engine("connection url")
pool = sessionmaker(engine)
paginator = LimitOffsetPaginator(select(Book).order_by(Book.id, Book.title))
with pool.begin() as session:
stmt = paginator.get_modified_sql_statement()
result = session.execute(stmt).all()
page = paginator.parse_result(result)
with paginator.bookmarked(page.next):
stmt = paginator.get_modified_sql_statement()
result = session.execute(stmt).all()
new_page = paginator.parse_result(result)
```
### What do bookmarks look like?
Bookmark is a plain dict, but for different pagination strategies
a dict's payload differ from each other
#### Keyset:
```python
{
"keyset_pairs": {
"id": (1,)
},
"direction": "forward",
}
```
#### Limit-offset:
```python
{
"offset": 10000,
}
```
#### Limitations:
* _Golden Rule_: Always ensure your keysets are unique per row. If you violate this condition you risk skipped rows and other nasty problems. The simplest way to do this is to always include your primary key column(s) at the end of your ordering columns.
* Any rows containing null values in their keysets will be omitted from the results, so your ordering columns should be NOT NULL. (This is a consequence of the fact that comparisons against NULL are always false in SQL.) This may change in the future if we work out an alternative implementation; but for now we recommend using coalesce as a workaround if you need to sort by nullable columns: