{"id":25084725,"url":"https://github.com/sopherapps/nqlstore","last_synced_at":"2026-03-08T11:31:31.329Z","repository":{"id":275679978,"uuid":"921934260","full_name":"sopherapps/nqlstore","owner":"sopherapps","description":"NQLStore, a simple CRUD store python library for `any query launguage` (or in short `nql`)","archived":false,"fork":false,"pushed_at":"2025-06-07T10:57:25.000Z","size":267,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-20T00:33:38.476Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sopherapps.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-01-24T22:38:20.000Z","updated_at":"2025-06-07T10:55:17.000Z","dependencies_parsed_at":null,"dependency_job_id":"89ba40c8-7730-4f66-a148-92f44678ea0c","html_url":"https://github.com/sopherapps/nqlstore","commit_stats":null,"previous_names":["sopherapps/nqlstore"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/sopherapps/nqlstore","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sopherapps%2Fnqlstore","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sopherapps%2Fnqlstore/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sopherapps%2Fnqlstore/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sopherapps%2Fnqlstore/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sopherapps","download_url":"https://codeload.github.com/sopherapps/nqlstore/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sopherapps%2Fnqlstore/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278667417,"owners_count":26025226,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-06T02:00:05.630Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-02-07T07:18:31.890Z","updated_at":"2025-10-06T19:28:19.645Z","avatar_url":"https://github.com/sopherapps.png","language":"Python","readme":"# NQLStore\n\n[![PyPI version](https://badge.fury.io/py/nqlstore.svg)](https://badge.fury.io/py/nqlstore) ![CI](https://github.com/sopherapps/nqlstore/actions/workflows/ci.yml/badge.svg)\n\nNQLStore, a simple CRUD store python library for `any query launguage` (or in short `nql`)\n\n---\n\nNQLStore provides an oversimplified API for the mundane things of _creating_, _reading_,\n_updating_, and _deleting_ data models that are persisted to any `SQL-` or `NoSQL-` database. \n\nIn total, all we need are four methods and that is it.\n\nSupported databases include:\n\n- Relational databases like:\n\n  - SQLite\n  - PostgreSQL\n  - MySQL\n\n- NoSQL databases like:\n\n  - Redis\n  - MongoDB\n\nIf you like our simple API, you can even easily extend it to \nsupport your favourite database technology.\n\n## Dependencies\n\n- [Python +3.10](https://www.python.org/downloads/)\n- [Pydantic +2.0](https://docs.pydantic.dev/latest/)\n- [SQLModel _(_optional_)](https://sqlmodel.tiangolo.com/) - only required for relational databases\n- [RedisOM (_optional_)](https://redis.io/docs/latest/integrate/redisom-for-python/) - only required for [redis](https://redis.io/)\n- [Beanie (_optional_)](https://beanie-odm.dev/) - only required for [MongoDB](https://www.mongodb.com/)\n\n## Examples\n\nSee the [`examples`](/examples) folder for some example applications.  \nHopefully more examples will be added with time. Currently, we have the following:\n\n- [todos](./examples/todos)\n\n## Quick Start\n\n### Install NQLStore from Pypi \n\nInstall NQLStore from pypi, with any of the options: `sql`, `mongo`, `redis`, `all`.\n\n```shell\npip install \"nqlstore[all]\"\n```\n\n### Create Schemas\n\nCreate the basic structure of the data that will be saved in the store.  \nThese schemas will later be used to create models that are specific to the underlying database\ntechnology.\n\n```python\n# schemas.py\n\nfrom nqlstore import Field, Relationship\nfrom pydantic import BaseModel\n\n\nclass Library(BaseModel):\n    address: str = Field(index=True, full_text_search=True)\n    name: str = Field(index=True, full_text_search=True)\n    books: list[\"Book\"] = Relationship(back_populates=\"library\")\n\n    class Settings:\n        # this Settings class is optional. It is only used by Mongo models\n        # See https://beanie-odm.dev/tutorial/defining-a-document/\n        name = \"libraries\"\n\n\nclass Book(BaseModel):\n    title: str = Field(index=True)\n    library_id: int | None = Field(default=None, foreign_key=\"sqllibrary.id\", disable_on_redis=True, disable_on_mongo=True)\n    library: Library | None = Relationship(back_populates=\"books\", disable_on_redis=True, disable_on_mongo=True)\n```\n\n### Initialize your store and its models\n\nInitialize the store and its models that is to host your models.\n\n#### SQL\n\n_Migrations are outside the scope of this package_\n\n```python\n# main.py\n\nfrom nqlstore import SQLStore, SQLModel\nfrom .schemas import Book, Library\n\n\n# Define models specific to SQL.\nSqlLibrary = SQLModel(\n        \"SqlLibrary\", Library, relationships={\"books\": list[\"SqlBook\"]}\n    )\nSqlBook = SQLModel(\"SqlBook\", Book, relationships={\"library\": SqlLibrary | None})\n\n\n\nasync def main():\n  sql_store = SQLStore(uri=\"sqlite+aiosqlite:///database.db\")\n  await sql_store.register([\n    SqlLibrary,\n    SqlBook,\n  ])\n```\n\n#### Redis\n\n**Take note that JsonModel, EmbeddedJsonModel require RedisJSON, while queries require RedisSearch to be loaded**\n**You need to install [redis-stack](https://redis.io/docs/latest/operate/oss_and_stack/install/install-stack/) or load the modules manually**\n\n```python\n# main.py\n\nfrom nqlstore import RedisStore, EmbeddedJsonModel, JsonModel\nfrom .schemas import Book, Library\n\n# Define models specific to redis.\nRedisBook = EmbeddedJsonModel(\"RedisBook\", Book)\nRedisLibrary = JsonModel(\"RedisLibrary\", Library, embedded_models={\"books\": list[RedisBook]})\n\nasync def main():\n  redis_store = RedisStore(uri=\"rediss://username:password@localhost:6379/0\")\n  await redis_store.register([\n    RedisLibrary,\n    RedisBook,\n  ])\n```\n\n#### Mongo\n\n```python\n# main.py\n\nfrom nqlstore import MongoStore, MongoModel, EmbeddedMongoModel\nfrom .schemas import Library, Book\n\n# Define models specific to MongoDB.\nMongoBook = EmbeddedMongoModel(\"MongoBook\", Book)\nMongoLibrary = MongoModel(\"MongoLibrary\", Library, embedded_models={\"books\": list[MongoBook]})\n\n\nasync def main():\n  mongo_store = MongoStore(uri=\"mongodb://localhost:27017\", database=\"testing\")\n  await mongo_store.register([\n    MongoLibrary,\n    MongoBook,\n  ])\n\n```\n\n### Use your models in your application\n\nIn the rest of your application use the four CRUD methods on the store to do CRUD operations.  \nFiltering follows the [MongoDb-style](https://www.mongodb.com/docs/manual/reference/method/db.collection.find/#find-documents-that-match-query-criteria)\n\n\u003e **Note**: For more complex queries, one can also pass in querying styles native to the type of the database,  \n\u003e alongside the MongoBD-style querying. The two queries would be merged as `AND` queries.  \n\u003e\n\u003e Or one can simply ignore the MongoDB-style querying and stick to the native querying.  \n\u003e \n\u003e The available querying formats include:\n\u003e \n\u003e - SQL - [SQLModel-style](https://sqlmodel.tiangolo.com/tutorial/where/#where-and-expressions-instead-of-keyword-arguments)\n\u003e - Redis - [RedisOM-style](https://redis.io/docs/latest/integrate/redisom-for-python/#create-read-update-and-delete-data)\n\u003e - MongoDb - [MongoDB-style](https://www.mongodb.com/docs/manual/reference/method/db.collection.find/#find-documents-that-match-query-criteria)\n\n#### Insert\n\nInserting new items in a store, call `store.insert()` method.\n\n```python\nnew_libraries = await sql_store.insert(SqlLibrary, [{}, {}])\nnew_libraries = await mongo_store.insert(MongoLibrary, [{}, {}])\nnew_libraries = await redis_store.insert(RedisLibrary, [{}, {}])\n```\n\n#### Find\n\nFinding items in a store, call the `store.find()` method.\n\nThe key-word arguments include:\n\n- `skip (int)` - number of records to ignore at the top of the returned results; default is 0.\n- `limit (int | None)` - maximum number of records to return; default is None.\n\nThe querying format is as described [above](#use-your-models-in-your-application)\n\n```python\n# MongoDB-style: works with any underlying database technology\nlibraries = await sql_store.find(\n    SqlLibrary, query={\"name\": {\"$eq\": \"Hairora\"}, \"address\" : {\"$ne\": \"Buhimba\"}}\n)\n\n\n# Native SQL-style: works only if underlying database is SQL database\nlibraries = await sql_store.find(\n    SqlLibrary, SqlLibrary.name == \"Hairora\", SqlLibrary.address != \"Buhimba\"\n)\n\n\n# Hybrid SQL-Mongo-style: works only if underlying database is SQL database\nlibraries = await sql_store.find(\n    SqlLibrary, SqlLibrary.name == \"Hairora\", query={\"address\" : {\"$ne\": \"Buhimba\"}}\n)\n\n\n# Native Redis-style: works only if underlying database is redis database\nlibraries = await redis_store.find(\n    RedisLibrary, (RedisLibrary.name == \"Hairora\") \u0026 (RedisLibrary.address != \"Buhimba\")\n)\n\n\n# Hybrid redis-mongo-style: works only if underlying database is redis database\nlibraries = await redis_store.find(\n    RedisLibrary, (RedisLibrary.name == \"Hairora\"), query={\"address\" : {\"$ne\": \"Buhimba\"}}\n)\n```\n\n#### Update\n\nUpdating items in a store, call the `store.update()` method.\n\nThe method returns the newly updated records.  \nThe `filters` follow the same style as that used when querying as shown [above](#read). \n\nThe `updates` objects are simply dictionaries of the new field values.\n\n```python\n# Mongo-style of filtering: works with any underlying database technology\nlibraries = await redis_store.update(\n    RedisLibrary, \n    query={\"name\": {\"$eq\": \"Hairora\"}, \"address\" : {\"$ne\": \"Buhimba\"}},\n    updates={\"name\": \"Foo\"},\n)\n\n\n# Native SQL-style filtering: works only if the underlying database is SQL\nlibraries = await sql_store.update(\n    SqlLibrary, \n    SqlLibrary.name == \"Hairora\", SqlLibrary.address != \"Buhimba\", \n    updates={\"name\": \"Foo\"},\n)\n\n\n# Hybrid SQL-mongo-style filtering: works only if the underlying database is SQL\nlibraries = await sql_store.update(\n    SqlLibrary, \n    SqlLibrary.name == \"Hairora\", query={\"address\" : {\"$ne\": \"Buhimba\"}},\n    updates={\"name\": \"Foo\"},\n)\n\n\n# Native redisOM-style filtering: works only if the underlying database is redis\nlibraries = await redis_store.update(\n    RedisLibrary, \n    (RedisLibrary.name == \"Hairora\") \u0026 (RedisLibrary.address != \"Buhimba\"), \n    updates={\"name\": \"Foo\"},\n)\n\n\n# Hybrid redis-mongo-style filtering: works only if the underlying database is redis\nlibraries = await redis_store.update(\n    RedisLibrary, \n    (RedisLibrary.name == \"Hairora\"), \n    query={\"address\" : {\"$ne\": \"Buhimba\"}},\n    updates={\"name\": \"Foo\"},\n)\n\n\n# MongoDB is special. It can also accept `updates` of the MongoDB-style update dicts\n# See \u003chttps://www.mongodb.com/docs/manual/reference/operator/update/\u003e.\n# However, this has the disadvantage of making it difficult to swap out MongoDb \n# with another underlying technology.\n#\n# It is thus recommended to stick to using `updates` that are simply \n# dictionaries of the new field values.\n# \n# The MongoDB-style update dicts work only if the underlying database is mongodb\nlibraries = await mongo_store.update(\n    MongoLibrary,\n    {\"name\": \"Hairora\", \"address\": {\"$ne\": \"Buhimba\"}},\n    updates={\"$set\": {\"name\": \"Foo\"}}, # \"$inc\", \"$addToSet\" etc. can be accepted, but use with care\n)\n\n```\n\n\n#### Delete\n\nDeleting items in a store, call the `store.delete()` method.\n\nThe `filters` follow the same style as that used when reading as shown [above](#read).\n\n```python\n# Mongo-style of filtering: works with any underlying database technology\nlibraries = await mongo_store.delete(\n    MongoLibrary, query={\"name\": {\"$eq\": \"Hairora\"}, \"address\" : {\"$ne\": \"Buhimba\"}}\n)\n\n\n# Native SQL-style filtering: works only if the underlying database is SQL\nlibraries = await sql_store.delete(\n    SqlLibrary, SqlLibrary.name == \"Hairora\", SqlLibrary.address != \"Buhimba\"\n)\n\n\n# Hybrid SQL-mongo-style filtering: works only if the underlying database is SQL\nlibraries = await sql_store.delete(\n    SqlLibrary, SqlLibrary.name == \"Hairora\", query={\"address\" : {\"$ne\": \"Buhimba\"}}\n)\n\n\n# Native redisOM-style filtering: works only if the underlying database is redis\nlibraries = await redis_store.delete(\n    RedisLibrary, (RedisLibrary.name == \"Hairora\") \u0026 (RedisLibrary.address != \"Buhimba\")\n)\n\n\n# Hybrid redis-mongo-style filtering: works only if the underlying database is redis\nlibraries = await redis_store.delete(\n    RedisLibrary, (RedisLibrary.name == \"Hairora\"), query={\"address\" : {\"$ne\": \"Buhimba\"}}\n)\n```\n\n## TODO\n\n- [ ] Add documentation site\n\n## Limitations\n\nThis library is limited in some specific cases.\nRead through the [`LIMITATIONS.md`](./LIMITATIONS.md) file for more.\n\n## Contributions\n\nContributions are welcome. The docs have to maintained, the code has to be made cleaner, more idiomatic and faster,\nand there might be need for someone else to take over this repo in case I move on to other things. It happens!\n\nWhen you are ready, look at the [CONTRIBUTIONS GUIDELINES](./CONTRIBUTING.md)\n\n## License\n\nCopyright (c) 2025 [Martin Ahindura](https://github.com/Tinitto)   \nLicensed under the [MIT License](./LICENSE)\n\n## Gratitude\n\nThanks goes to the people in the [CREDITS.md](./CREDITS.md), for the efforts\nthey have put into this project.  \n\nBut above all, glory be to God.\n\n\u003e \"In that day you will ask in My name. I am not saying that I will ask the Father on your behalf.\n\u003e No, the Father himself loves you because you have loved Me and have believed that I came from God.\"\n\u003e\n\u003e -- John 16: 26-27\n\n\u003ca href=\"https://www.buymeacoffee.com/martinahinJ\" target=\"_blank\"\u003e\u003cimg src=\"https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png\" alt=\"Buy Me A Coffee\" style=\"height: 60px !important;width: 217px !important;\" \u003e\u003c/a\u003e\n","funding_links":["https://www.buymeacoffee.com/martinahinJ"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsopherapps%2Fnqlstore","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsopherapps%2Fnqlstore","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsopherapps%2Fnqlstore/lists"}