Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/bw9ubwo/pydanql
Simplified PostgreSQL interaction in Python using Pydantic data models.
https://github.com/bw9ubwo/pydanql
crud database orm postgresql pydantic python rapid-prototyping
Last synced: about 1 month ago
JSON representation
Simplified PostgreSQL interaction in Python using Pydantic data models.
- Host: GitHub
- URL: https://github.com/bw9ubwo/pydanql
- Owner: bw9ubwo
- License: mit
- Created: 2023-08-29T17:12:42.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2023-09-05T09:10:16.000Z (over 1 year ago)
- Last Synced: 2024-10-28T17:54:39.560Z (about 2 months ago)
- Topics: crud, database, orm, postgresql, pydantic, python, rapid-prototyping
- Language: Python
- Homepage: http://blacktre.es
- Size: 52.7 KB
- Stars: 6
- Watchers: 1
- Forks: 0
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
Get support from [BLACKTREES](https://blacktre.es) or on [Github](https://github.com/jdnumm/pydanql)
# Pydanql: A Pydantic PostgreSQL Library
⚠️ **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).
## Introduction
Pydanql 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.
## Quick Example
The 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.
```python
from pydanql.base import Database
from pydanql.table import Table
# ObjectBaseModel is a Pydantic BaseModel equipped with default fields such as id, slug, date_created, and date_last_edit.
from pydanql.model import ObjectBaseModel
# Define the Book model using Pydantic
class Book(ObjectBaseModel):
name: str
author: str
year: int
# Initialize the database connection
db = Database(database='test_db', user='username', password='password', host='localhost', port=5432)
# Set up a table for books
db.books = Table(db, Book)
# Add a new Book to the database
new_book = Book(name="The Lord of the Rings", author="J. R. R. Tolkien", year=1964)
db.books.add(new_book)
# Retrieve and display Books from the database
books = db.books.find_many()
for book in books:
print(book)
# Close the database connection
db.close()
```
## Installation
To install the Pydanql library, run the following pip command:
```bash
pip install pydanql
```
## Create a Database
Create a user and a database
```BASH
psql postgres # Connect to your database server
```
```SQL
CREATE DATABASE testdb;
CREATE USER testuser WITH PASSWORD 'testpass';
GRANT ALL PRIVILEGES ON DATABASE testdb TO testuser;
```
## Components
- `Database`: Manages the connection to a PostgreSQL database.
- `ObjectBaseModel`: An enhanced Pydantic model with predefined fields.
- `Table`: A utility class for CRUD operations on database tables.
- `DatabaseError`: A specialized exception class for database-related issues.
## Features & Examples
- **Create a new record:**
```python
new_car = Car(brand="Tesla", model="Model S", year=2020, color="Blue", miles=1000.5)
db.cars_table.add(new_car)
```
- **Update an existing record:**
```python
existing_car = db.cars_table.find_one(id=1)
existing_car.color = "Green"
db.cars_table.replace(existing_car)
```
- **Delete an existing record:**
```python
existing_car = db.cars_table.find_one(id=1)
db.cars_table.delete(existing_car)
```
- **Find records with queries:**
Pydanql supports multiple types of queries to provide you with powerful search functionality. Below are some examples of how to use different query types.
- **Exact Match:**
```python
blue_cars = db.cars_table.find_many(color='Blue')
```
- **Like Query:**
```python
similar_colors = db.cars_table.find_many(color={'like': 'blu'})
```
- **Range Query:**
```python
recent_cars = db.cars_table.find_many(year={'range': [2015, 2021]})
```
- **In Query:**
```python
cars_by_models = db.cars_table.find_many(model={'in': ['Model S', 'Model X']})
```
- **Greater Than (gt):**
```python
high_mileage_cars = db.cars_table.find_many(miles={'gt': 50000})
```
- **Less Than (lt):**
```python
low_mileage_cars = db.cars_table.find_many(miles={'lt': 30000})
```
- **Sorting, Offset and Count:**
```python
db.cars_table.find_many(sort='-year', offset=10, count=10)
```
- **Single Record:**
```python
newest_car = db.cars_table.find_one(sort='-year')
```
By 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.
- **Count records:**
```python
total_cars = db.cars_table.count()
```
- **Simple pagination:**
```python
page_1_results = db.cars_table.page(page_number=1, page_size=5)
```
- **Model with more complex data types and a custom method:**
```python
class Book(ObjectBaseModel):
name: str
author: str
year: int
available: bool
dimensions: Tuple = Field(default=(8,8), data_type="int[]", constraints=["NOT NULL"])
meta: Dict = Field(default={}, data_type="JSONB", constraints=["NOT NULL"])
def description(self):
return f"Title: {self.name}, Author: {self.author}, Year: {self.year}"
new_book = Book(name="The Lord of the Rings", author="J. R. R. Tolkien", available=True, year=1964, dimensions=(16,23), meta={ 'language': 'en' })
db.books.add(new_book)
# Invoke the custom description method
print(new_book.description())
```
## License
Pydanql is licensed under the MIT license.