{"id":20525772,"url":"https://github.com/bw9ubwo/pydanql","last_synced_at":"2025-04-14T03:51:25.938Z","repository":{"id":191457361,"uuid":"684700163","full_name":"bw9ubwo/pydanql","owner":"bw9ubwo","description":"Simplified PostgreSQL interaction in Python using Pydantic data models.","archived":false,"fork":false,"pushed_at":"2023-09-05T09:10:16.000Z","size":54,"stargazers_count":7,"open_issues_count":4,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-24T07:54:04.392Z","etag":null,"topics":["crud","database","orm","postgresql","pydantic","python","rapid-prototyping"],"latest_commit_sha":null,"homepage":"http://blacktre.es","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/bw9ubwo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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}},"created_at":"2023-08-29T17:12:42.000Z","updated_at":"2025-01-26T22:21:14.000Z","dependencies_parsed_at":"2024-10-28T17:54:44.724Z","dependency_job_id":"b824d17d-4d5b-4a50-aee1-9161f5b398dd","html_url":"https://github.com/bw9ubwo/pydanql","commit_stats":null,"previous_names":["jdnumm/gamma","bw9ubwo/pydanql","jdnumm/pydanql"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bw9ubwo%2Fpydanql","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bw9ubwo%2Fpydanql/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bw9ubwo%2Fpydanql/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bw9ubwo%2Fpydanql/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bw9ubwo","download_url":"https://codeload.github.com/bw9ubwo/pydanql/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248819352,"owners_count":21166474,"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","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":["crud","database","orm","postgresql","pydantic","python","rapid-prototyping"],"created_at":"2024-11-15T23:09:23.138Z","updated_at":"2025-04-14T03:51:25.909Z","avatar_url":"https://github.com/bw9ubwo.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"Get support from [BLACKTREES](https://blacktre.es) or on [Github](https://github.com/jdnumm/pydanql)\n\n# Pydanql: A Pydantic PostgreSQL Library\n\n⚠️ **Early Version Warning**: This is an early version of the Pydanql library and is subject to changes. While we strive for stability, features and APIs may be altered as the library evolves. Your feedback is invaluable, so please feel free to provide it through [BLACKTREES](https://blacktre.es) or on [Github](https://github.com/jdnumm/pydanql).\n\n## Introduction\nPydanql offers a streamlined way to interact with PostgreSQL databases using Python. This library combines robust database connection management, data modeling, and CRUD (Create, Read, Update, Delete) functionalities. Additionally, built-in logging features make debugging and error handling more straightforward.\n\n## Quick Example\n\nThe following example demonstrates how to use the Pydanql library for database interactions. This assumes that the necessary classes—`Database`, `Table`, and `ObjectBaseModel`—are imported from Pydanql.\n\n```python\nfrom pydanql.base import Database\nfrom pydanql.table import Table\n# ObjectBaseModel is a Pydantic BaseModel equipped with default fields such as id, slug, date_created, and date_last_edit.\nfrom pydanql.model import ObjectBaseModel\n\n# Define the Book model using Pydantic\nclass Book(ObjectBaseModel):\n    name: str\n    author: str\n    year: int\n\n# Initialize the database connection\ndb = Database(database='test_db', user='username', password='password', host='localhost', port=5432)\n\n# Set up a table for books\ndb.books = Table(db, Book)\n\n# Add a new Book to the database\nnew_book = Book(name=\"The Lord of the Rings\", author=\"J. R. R. Tolkien\", year=1964)\ndb.books.add(new_book)\n\n# Retrieve and display Books from the database\nbooks = db.books.find_many()\nfor book in books:\n    print(book)\n\n# Close the database connection\ndb.close()\n```\n\n## Installation\n\nTo install the Pydanql library, run the following pip command:\n```bash\npip install pydanql\n```\n\n## Create a Database\n\nCreate a user and a database\n\n```BASH\npsql postgres # Connect to your database server\n```\n\n```SQL\nCREATE DATABASE testdb;\nCREATE USER testuser WITH PASSWORD 'testpass';\nGRANT ALL PRIVILEGES ON DATABASE testdb TO testuser;\n```\n\n## Components\n\n- `Database`: Manages the connection to a PostgreSQL database.\n- `ObjectBaseModel`: An enhanced Pydantic model with predefined fields.\n- `Table`: A utility class for CRUD operations on database tables.\n- `DatabaseError`: A specialized exception class for database-related issues.\n\n## Features \u0026 Examples\n\n- **Create a new record:**\n    ```python\n    new_car = Car(brand=\"Tesla\", model=\"Model S\", year=2020, color=\"Blue\", miles=1000.5)\n    db.cars_table.add(new_car)\n    ```\n\n- **Update an existing record:**\n    ```python\n    existing_car = db.cars_table.find_one(id=1)\n    existing_car.color = \"Green\"\n    db.cars_table.replace(existing_car)\n    ```\n\n- **Delete an existing record:**\n    ```python\n    existing_car = db.cars_table.find_one(id=1)\n    db.cars_table.delete(existing_car)\n    ```\n\n- **Find records with queries:**\n\n    Pydanql supports multiple types of queries to provide you with powerful search functionality. Below are some examples of how to use different query types.\n\n    - **Exact Match:**\n        ```python\n        blue_cars = db.cars_table.find_many(color='Blue')\n        ```\n    \n    - **Like Query:**\n        ```python\n        similar_colors = db.cars_table.find_many(color={'like': 'blu'})\n        ```\n    \n    - **Range Query:**\n        ```python\n        recent_cars = db.cars_table.find_many(year={'range': [2015, 2021]})\n        ```\n    \n    - **In Query:**\n        ```python\n        cars_by_models = db.cars_table.find_many(model={'in': ['Model S', 'Model X']})\n        ```\n    \n    - **Greater Than (gt):**\n        ```python\n        high_mileage_cars = db.cars_table.find_many(miles={'gt': 50000})\n        ```\n    \n    - **Less Than (lt):**\n        ```python\n        low_mileage_cars = db.cars_table.find_many(miles={'lt': 30000})\n        ```\n        \n    - **Sorting, Offset and Count:**\n        ```python\n        db.cars_table.find_many(sort='-year', offset=10, count=10)\n        ```\n        \n    - **Single Record:**\n        ```python\n        newest_car = db.cars_table.find_one(sort='-year')\n        ```\n        \nBy using these query types, you can execute more complex searches and filters on your records, making Pydanql a versatile tool for interacting with your PostgreSQL database.\n\n- **Count records:**\n    ```python\n    total_cars = db.cars_table.count()\n    ```\n\n- **Simple pagination:**\n    ```python\n    page_1_results = db.cars_table.page(page_number=1, page_size=5)\n    ```\n\n- **Model with more complex data types and a custom method:**\n    ```python\n    class Book(ObjectBaseModel):\n        name: str\n        author: str\n        year: int\n        available: bool\n        dimensions: Tuple = Field(default=(8,8), data_type=\"int[]\", constraints=[\"NOT NULL\"])\n        meta: Dict = Field(default={}, data_type=\"JSONB\", constraints=[\"NOT NULL\"])\n\n        def description(self):\n            return f\"Title: {self.name}, Author: {self.author}, Year: {self.year}\"\n    \n    new_book = Book(name=\"The Lord of the Rings\", author=\"J. R. R. Tolkien\", available=True, year=1964, dimensions=(16,23), meta={ 'language': 'en' })\n    db.books.add(new_book)\n\n    # Invoke the custom description method\n    print(new_book.description())\n    ```\n\n## License\n\nPydanql is licensed under the MIT license.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbw9ubwo%2Fpydanql","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbw9ubwo%2Fpydanql","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbw9ubwo%2Fpydanql/lists"}