# 🚀 SQLModelRepo - A simple CRUD util for SQLModel
`SQLModelRepo` is a simple and powerful repository pattern implementation for managing database interactions using the SQLAlchemy-backed SQLModel ORM. It abstracts common database tasks (CRUD - Create, Read, Update, Delete) 🛠️, making data manipulation and access easier, with support for filtering, pagination, and session management 🎯.
## 🎯 Features
- 🏷️ **Generic Repository**: Perform Create, Read (single or multiple), Update, and Delete (CRUD) operations effortlessly.
- 🔄 **Session Management**: Automate session reuse or creation, ensuring efficient transaction handling.
- 🔍 **Filtering & Pagination**: Easily filter and paginate results.
- ♻️ **Partial Updates**: Update records partially using SQL.
## 📦 Installation
```bash
pip install sqlmodel_repo
```
Ensure you have `sqlmodel` and other dependencies installed.
## 🚀 Usage
### Define your SQLModel Repository 🏗️
Create an SQLModel class representing your database table.
```python
...
from sqlmodel_repo import SQLModelRepo
class User(SQLModel, table=True):
id: int | None = Field(default=None, primary_key=True)
username: str
email: str
extra_metadata: dict = Field(sa_column=Column(JSON))
users_repo = SQLModelRepo(model=User, db_engine=engine)
```
### Basic Operations 🛠️
#### Create a Record ✍️
You can easily create a new record using `create`.
```python
new_user = users_repo.create(username="john_doe", email="john@example.com")
```
#### Retrieve by ID 🆔
Fetch a record by its ID using `get_by_id`.
```python
user = users_repo.get_by_id(new_user.id)
```
#### Update a Record 🔄
Modify a record and call `save` to persist your changes.
```python
user.email = "john_new@example.com"
users_repo.save(user)
```
Or, perform partial updates directly with `update(id, **kwargs)`:
```python
users_repo.update(user.id, email="updated_email@example.com")
```
#### Delete a Record 🗑️
Easily delete a record by passing the instance to the `delete` method.
```python
users_repo.delete(user)
```
#### Reuse session 🔄
```python
with Session(engine) as session:
assert users_repo(session).all()
```
### Advanced Querying 🔥
#### Filtering Records 🔎
Use the `filter` method to retrieve records meeting specific criteria.
```python
# Filter by username 'john_doe'
users = users_repo.filter(username="john_doe").all()
# Find usernames starting with 'jo'
users = users_repo.filter(User.username.startswith('jo')).all()
```
#### Querying Inside JSON Fields 🗂️
```python
from sqlalchemy import cast, String
users = users_repo.filter(cast(User.extra_metadata['some_num'], String) == '99').all()
```
#### Paginated Results 📄
Fetch paginated results using `paginate` or `paginate_with_total` to retrieve ordered subsets of data.
```python
# Paginate results, sorted by username in descending order
users_paginated, total_count = users_repo.filter().paginate_with_total(
offset=0, limit=4, order_by="username", desc=True
)
```
#### Async 🚅
sqlmodel_repo also has an async version:
```shell
pip install sqlmodel_repo[async]
```
```python
from sqlmodel_repo.async_repo import AsyncSQLModelRepo
```
## ⚖️ License
This project is licensed under the MIT License.
---
Enjoy coding and happy querying with `SQLModelRepo`! 🎉
Author is a lazy person, so this README.md was generated by AI.
Raw data
{
"_id": null,
"home_page": null,
"name": "sqlmodel-repo",
"maintainer": null,
"docs_url": null,
"requires_python": ">3.11.0",
"maintainer_email": null,
"keywords": "sqlmodel, sqlalchemy, orm, active record",
"author": null,
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/55/3f/7f0ea6db45ddc2f8525a9492e2cb04dc89c03850174ee0176e2f41a45ede/sqlmodel_repo-0.0.4.tar.gz",
"platform": null,
"description": "# \ud83d\ude80 SQLModelRepo - A simple CRUD util for SQLModel\n\n`SQLModelRepo` is a simple and powerful repository pattern implementation for managing database interactions using the SQLAlchemy-backed SQLModel ORM. It abstracts common database tasks (CRUD - Create, Read, Update, Delete) \ud83d\udee0\ufe0f, making data manipulation and access easier, with support for filtering, pagination, and session management \ud83c\udfaf.\n\n## \ud83c\udfaf Features\n\n- \ud83c\udff7\ufe0f **Generic Repository**: Perform Create, Read (single or multiple), Update, and Delete (CRUD) operations effortlessly.\n- \ud83d\udd04 **Session Management**: Automate session reuse or creation, ensuring efficient transaction handling.\n- \ud83d\udd0d **Filtering & Pagination**: Easily filter and paginate results.\n- \u267b\ufe0f **Partial Updates**: Update records partially using SQL.\n\n## \ud83d\udce6 Installation\n\n```bash\npip install sqlmodel_repo\n```\n\nEnsure you have `sqlmodel` and other dependencies installed.\n\n## \ud83d\ude80 Usage\n\n### Define your SQLModel Repository \ud83c\udfd7\ufe0f\n\nCreate an SQLModel class representing your database table.\n\n```python\n...\nfrom sqlmodel_repo import SQLModelRepo\n\nclass User(SQLModel, table=True):\n id: int | None = Field(default=None, primary_key=True)\n username: str\n email: str\n extra_metadata: dict = Field(sa_column=Column(JSON))\n \nusers_repo = SQLModelRepo(model=User, db_engine=engine)\n```\n\n### Basic Operations \ud83d\udee0\ufe0f\n\n#### Create a Record \u270d\ufe0f\n\nYou can easily create a new record using `create`.\n\n```python\nnew_user = users_repo.create(username=\"john_doe\", email=\"john@example.com\")\n```\n\n#### Retrieve by ID \ud83c\udd94\n\nFetch a record by its ID using `get_by_id`.\n\n```python\nuser = users_repo.get_by_id(new_user.id)\n```\n\n#### Update a Record \ud83d\udd04\n\nModify a record and call `save` to persist your changes.\n\n```python\nuser.email = \"john_new@example.com\"\nusers_repo.save(user)\n```\n\nOr, perform partial updates directly with `update(id, **kwargs)`:\n\n```python\nusers_repo.update(user.id, email=\"updated_email@example.com\")\n```\n\n#### Delete a Record \ud83d\uddd1\ufe0f\n\nEasily delete a record by passing the instance to the `delete` method.\n\n```python\nusers_repo.delete(user)\n```\n\n#### Reuse session \ud83d\udd04\n```python\nwith Session(engine) as session:\n assert users_repo(session).all()\n```\n\n### Advanced Querying \ud83d\udd25\n\n#### Filtering Records \ud83d\udd0e\n\nUse the `filter` method to retrieve records meeting specific criteria.\n\n```python\n# Filter by username 'john_doe'\nusers = users_repo.filter(username=\"john_doe\").all()\n\n# Find usernames starting with 'jo'\nusers = users_repo.filter(User.username.startswith('jo')).all()\n```\n\n#### Querying Inside JSON Fields \ud83d\uddc2\ufe0f\n\n```python\nfrom sqlalchemy import cast, String\n\nusers = users_repo.filter(cast(User.extra_metadata['some_num'], String) == '99').all()\n```\n\n#### Paginated Results \ud83d\udcc4\n\nFetch paginated results using `paginate` or `paginate_with_total` to retrieve ordered subsets of data.\n\n```python\n# Paginate results, sorted by username in descending order\nusers_paginated, total_count = users_repo.filter().paginate_with_total(\n offset=0, limit=4, order_by=\"username\", desc=True\n)\n```\n\n#### Async \ud83d\ude85\nsqlmodel_repo also has an async version:\n\n```shell\npip install sqlmodel_repo[async]\n```\n```python\nfrom sqlmodel_repo.async_repo import AsyncSQLModelRepo\n```\n\n## \u2696\ufe0f License\n\nThis project is licensed under the MIT License.\n\n---\n\nEnjoy coding and happy querying with `SQLModelRepo`! \ud83c\udf89\n\nAuthor is a lazy person, so this README.md was generated by AI.\n",
"bugtrack_url": null,
"license": null,
"summary": "Active record mixin for SQLModel",
"version": "0.0.4",
"project_urls": null,
"split_keywords": [
"sqlmodel",
" sqlalchemy",
" orm",
" active record"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e6d17950a32a909eff9ad503a62353dd6c4492d1b71e48c6ff2ac3207613bd2c",
"md5": "c20e0b2e348063dea7772cdbed8a0eae",
"sha256": "9a5f15cfa4294c0556371da13ee5ceac7c5781d7704dd7dc60b1b6d8caaa0df3"
},
"downloads": -1,
"filename": "sqlmodel_repo-0.0.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c20e0b2e348063dea7772cdbed8a0eae",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">3.11.0",
"size": 11340,
"upload_time": "2024-12-05T23:03:48",
"upload_time_iso_8601": "2024-12-05T23:03:48.139402Z",
"url": "https://files.pythonhosted.org/packages/e6/d1/7950a32a909eff9ad503a62353dd6c4492d1b71e48c6ff2ac3207613bd2c/sqlmodel_repo-0.0.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "553f7f0ea6db45ddc2f8525a9492e2cb04dc89c03850174ee0176e2f41a45ede",
"md5": "e221a4a49efbab3f6a9b4dacf98504a5",
"sha256": "f8a5bdf0b20e7b93ac453f10b520602d8c6b38a5c9d647b71dd2d60ce73c4913"
},
"downloads": -1,
"filename": "sqlmodel_repo-0.0.4.tar.gz",
"has_sig": false,
"md5_digest": "e221a4a49efbab3f6a9b4dacf98504a5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">3.11.0",
"size": 11216,
"upload_time": "2024-12-05T23:03:49",
"upload_time_iso_8601": "2024-12-05T23:03:49.006637Z",
"url": "https://files.pythonhosted.org/packages/55/3f/7f0ea6db45ddc2f8525a9492e2cb04dc89c03850174ee0176e2f41a45ede/sqlmodel_repo-0.0.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-05 23:03:49",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "sqlmodel-repo"
}
JSON