# Ormax ORM
[](https://www.python.org/downloads/)
[](LICENSE)
[](https://docs.python.org/3/library/asyncio.html)
**Ormax** is a high-performance, secure, and advanced asynchronous ORM for Python supporting MariaDB, MySQL, PostgreSQL, and SQLite3.
## 🚀 Features
- **Multi-Database Support**: MariaDB, MySQL, PostgreSQL, SQLite3
- **Fully Async**: Built with asyncio for maximum performance
- **Security First**: SQL injection protection and input validation
- **Connection Pooling**: Optimized database connections
- **Transaction Support**: ACID compliant transactions
- **Advanced QuerySet**: Powerful query capabilities
- **Rich Field Types**: Comprehensive field validation
- **Easy Configuration**: Simple setup and usage
## 📦 Installation
```bash
pip install ormax
```
Or install from source:
```bash
git clone https://github.com/shayanheidari01/ormax.git
cd ormax
pip install -e .
```
## 🛠️ Dependencies
```bash
# For MySQL/MariaDB
pip install aiomysql
# For PostgreSQL
pip install asyncpg
# For SQLite
pip install aiosqlite
```
## 🚀 Quick Start
### 1. Define Models
```python
from ormax import Database, Model
from ormax.fields import *
class User(Model):
table_name = "users" # Simple table name setup
id = IntegerField(primary_key=True, auto_increment=True)
username = CharField(max_length=50, unique=True)
email = EmailField(unique=True)
is_active = BooleanField(default=True)
created_at = DateTimeField(auto_now_add=True)
class Post(Model):
_meta = {'table_name': 'posts'} # Alternative setup
id = IntegerField(primary_key=True, auto_increment=True)
title = CharField(max_length=200)
content = TextField()
author_id = IntegerField(foreign_key='users.id')
published = BooleanField(default=False)
```
### 2. Database Setup
```python
import asyncio
async def main():
# Initialize database
db = Database("sqlite:///example.db") # SQLite
# db = Database("mysql://user:password@localhost/dbname") # MySQL
# db = Database("postgresql://user:password@localhost/dbname") # PostgreSQL
# db = Database("mariadb://user:password@localhost/dbname") # MariaDB
await db.connect()
# Register models
db.register_model(User)
db.register_model(Post)
# Create tables
await db.create_tables()
```
### 3. CRUD Operations
#### Create
```python
# Create single instance
user = await User.create(
username="john_doe",
email="john@example.com"
)
# Or create and save manually
user = User(username="jane_smith", email="jane@example.com")
await user.save()
```
#### Read
```python
# Get all records
all_users = await User.objects().all()
# Filter records
active_users = await User.objects().filter(is_active=True)
# Get single record
user = await User.objects().get(username="john_doe")
# Complex queries
published_posts = await Post.objects().filter(published=True).order_by('-created_at').limit(10)
```
#### Update
```python
# Update single instance
user.email = "newemail@example.com"
await user.save()
# Bulk update
updated_count = await Post.objects().filter(published=False).update(published=True)
```
#### Delete
```python
# Delete single instance
await user.delete()
# Bulk delete
deleted_count = await Post.objects().filter(published=False).delete()
```
## 🔧 Advanced Features
### Transactions
```python
async with db.transaction():
user = await User.create(username="test", email="test@example.com")
post = await Post.create(title="Test Post", content="Content", author_id=user.id)
```
### Complex Queries
```python
# Chaining filters
users = await User.objects().filter(is_active=True).exclude(username="admin")
# Ordering
posts = await Post.objects().order_by('-created_at', 'title')
# Pagination
page_1_posts = await Post.objects().limit(10).offset(0)
```
### Field Types
```python
class Product(Model):
id = IntegerField(primary_key=True, auto_increment=True)
name = CharField(max_length=100)
description = TextField()
price = FloatField()
in_stock = BooleanField(default=True)
created_at = DateTimeField(auto_now_add=True)
updated_at = DateTimeField(auto_now=True)
category_id = IntegerField(foreign_key='categories.id')
tags = JSONField() # Store JSON data
website = URLField()
```
## 🏗️ Model Configuration
### Simple Table Name
```python
class User(Model):
table_name = "app_users" # Simple setup
# ... fields
```
### Meta Configuration
```python
class Post(Model):
_meta = {'table_name': 'blog_posts'} # Traditional setup
# ... fields
```
### Automatic Table Name
```python
class Category(Model):
# Table name automatically becomes 'category'
# ... fields
```
## 🔒 Security Features
- **SQL Injection Protection**: All queries use parameterized statements
- **Input Validation**: Built-in field validation
- **Data Sanitization**: Automatic data cleaning
- **Connection Security**: Secure connection handling
## ⚡ Performance Features
- **Connection Pooling**: Reuse database connections efficiently
- **Lazy Loading**: Queries execute only when needed
- **Batch Operations**: Efficient bulk operations
- **Memory Management**: Optimized memory usage
## 📊 Supported Databases
| Database | Connection String | Package Required |
|----------|-------------------|------------------|
| SQLite | `sqlite:///path/to/db.sqlite` | `aiosqlite` |
| MySQL | `mysql://user:pass@host:port/db` | `aiomysql` |
| PostgreSQL | `postgresql://user:pass@host:port/db` | `asyncpg` |
| MariaDB | `mariadb://user:pass@host:port/db` | `aiomysql` |
## 🧪 Example Usage
```python
import asyncio
from ormax import Database, Model
from ormax.fields import *
class User(Model):
table_name = "users"
id = IntegerField(primary_key=True, auto_increment=True)
username = CharField(max_length=50, unique=True)
email = EmailField(unique=True)
is_active = BooleanField(default=True)
async def example():
# Setup
db = Database("sqlite:///example.db")
await db.connect()
db.register_model(User)
await db.create_tables()
# Create users
user1 = await User.create(username="alice", email="alice@example.com")
user2 = await User.create(username="bob", email="bob@example.com")
# Query users
all_users = await User.objects().all()
active_users = await User.objects().filter(is_active=True)
# Update user
user1.email = "alice.new@example.com"
await user1.save()
# Close connection
await db.disconnect()
if __name__ == "__main__":
asyncio.run(example())
```
## 📚 API Reference
### Database Class
- `Database(connection_string)` - Initialize database
- `connect()` - Connect to database
- `disconnect()` - Disconnect from database
- `transaction()` - Context manager for transactions
- `register_model(model)` - Register model with database
- `create_tables()` - Create all registered tables
### Model Class
- `objects()` - Get QuerySet for model
- `create(**kwargs)` - Create and save instance
- `save()` - Save instance to database
- `delete()` - Delete instance from database
- `to_dict()` - Convert to dictionary
### QuerySet Class
- `filter(**kwargs)` - Filter records
- `exclude(**kwargs)` - Exclude records
- `order_by(*fields)` - Order records
- `limit(count)` - Limit results
- `offset(count)` - Offset results
- `all()` - Get all records
- `first()` - Get first record
- `get(**kwargs)` - Get single record
- `count()` - Count records
- `exists()` - Check if records exist
- `delete()` - Delete matching records
- `update(**kwargs)` - Update matching records
## 🛡️ Field Types
| Field | Description | Example |
|-------|-------------|---------|
| `CharField` | String with max length | `CharField(max_length=100)` |
| `TextField` | Long text | `TextField()` |
| `IntegerField` | Integer | `IntegerField()` |
| `BigIntegerField` | Big integer | `BigIntegerField()` |
| `FloatField` | Floating point | `FloatField()` |
| `BooleanField` | Boolean | `BooleanField()` |
| `DateTimeField` | DateTime | `DateTimeField(auto_now_add=True)` |
| `DateField` | Date | `DateField()` |
| `EmailField` | Validated email | `EmailField()` |
| `URLField` | Validated URL | `URLField()` |
| `JSONField` | JSON data | `JSONField()` |
## 🤝 Contributing
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- Built with ❤️ for the Python community
- Inspired by Django ORM and SQLAlchemy
- Thanks to all contributors and users
## 🆘 Support
For support, please open an issue on GitHub or contact the maintainers.
---
**Made with ❤️ using Python asyncio**
Raw data
{
"_id": null,
"home_page": "https://github.com/shayanheidari01/ormax",
"name": "ormax",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "orm, async, asyncio, database, sql, mysql, postgresql, sqlite, mariadb, database-orm",
"author": "Shayan Heidari",
"author_email": "shayanheidari01@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/c0/2b/2c4879d1a7bcc030f8e4be33a13a2c86c480e602161befec07984f3bc7a0/ormax-1.0.0.tar.gz",
"platform": null,
"description": "\r\n# Ormax ORM\r\n\r\n[](https://www.python.org/downloads/)\r\n[](LICENSE)\r\n[](https://docs.python.org/3/library/asyncio.html)\r\n\r\n**Ormax** is a high-performance, secure, and advanced asynchronous ORM for Python supporting MariaDB, MySQL, PostgreSQL, and SQLite3.\r\n\r\n## \ud83d\ude80 Features\r\n\r\n- **Multi-Database Support**: MariaDB, MySQL, PostgreSQL, SQLite3\r\n- **Fully Async**: Built with asyncio for maximum performance\r\n- **Security First**: SQL injection protection and input validation\r\n- **Connection Pooling**: Optimized database connections\r\n- **Transaction Support**: ACID compliant transactions\r\n- **Advanced QuerySet**: Powerful query capabilities\r\n- **Rich Field Types**: Comprehensive field validation\r\n- **Easy Configuration**: Simple setup and usage\r\n\r\n## \ud83d\udce6 Installation\r\n\r\n```bash\r\npip install ormax\r\n```\r\n\r\nOr install from source:\r\n```bash\r\ngit clone https://github.com/shayanheidari01/ormax.git\r\ncd ormax\r\npip install -e .\r\n```\r\n\r\n## \ud83d\udee0\ufe0f Dependencies\r\n\r\n```bash\r\n# For MySQL/MariaDB\r\npip install aiomysql\r\n\r\n# For PostgreSQL \r\npip install asyncpg\r\n\r\n# For SQLite\r\npip install aiosqlite\r\n```\r\n\r\n## \ud83d\ude80 Quick Start\r\n\r\n### 1. Define Models\r\n\r\n```python\r\nfrom ormax import Database, Model\r\nfrom ormax.fields import *\r\n\r\nclass User(Model):\r\n table_name = \"users\" # Simple table name setup\r\n \r\n id = IntegerField(primary_key=True, auto_increment=True)\r\n username = CharField(max_length=50, unique=True)\r\n email = EmailField(unique=True)\r\n is_active = BooleanField(default=True)\r\n created_at = DateTimeField(auto_now_add=True)\r\n\r\nclass Post(Model):\r\n _meta = {'table_name': 'posts'} # Alternative setup\r\n \r\n id = IntegerField(primary_key=True, auto_increment=True)\r\n title = CharField(max_length=200)\r\n content = TextField()\r\n author_id = IntegerField(foreign_key='users.id')\r\n published = BooleanField(default=False)\r\n```\r\n\r\n### 2. Database Setup\r\n\r\n```python\r\nimport asyncio\r\n\r\nasync def main():\r\n # Initialize database\r\n db = Database(\"sqlite:///example.db\") # SQLite\r\n # db = Database(\"mysql://user:password@localhost/dbname\") # MySQL\r\n # db = Database(\"postgresql://user:password@localhost/dbname\") # PostgreSQL\r\n # db = Database(\"mariadb://user:password@localhost/dbname\") # MariaDB\r\n \r\n await db.connect()\r\n \r\n # Register models\r\n db.register_model(User)\r\n db.register_model(Post)\r\n \r\n # Create tables\r\n await db.create_tables()\r\n```\r\n\r\n### 3. CRUD Operations\r\n\r\n#### Create\r\n```python\r\n# Create single instance\r\nuser = await User.create(\r\n username=\"john_doe\",\r\n email=\"john@example.com\"\r\n)\r\n\r\n# Or create and save manually\r\nuser = User(username=\"jane_smith\", email=\"jane@example.com\")\r\nawait user.save()\r\n```\r\n\r\n#### Read\r\n```python\r\n# Get all records\r\nall_users = await User.objects().all()\r\n\r\n# Filter records\r\nactive_users = await User.objects().filter(is_active=True)\r\n\r\n# Get single record\r\nuser = await User.objects().get(username=\"john_doe\")\r\n\r\n# Complex queries\r\npublished_posts = await Post.objects().filter(published=True).order_by('-created_at').limit(10)\r\n```\r\n\r\n#### Update\r\n```python\r\n# Update single instance\r\nuser.email = \"newemail@example.com\"\r\nawait user.save()\r\n\r\n# Bulk update\r\nupdated_count = await Post.objects().filter(published=False).update(published=True)\r\n```\r\n\r\n#### Delete\r\n```python\r\n# Delete single instance\r\nawait user.delete()\r\n\r\n# Bulk delete\r\ndeleted_count = await Post.objects().filter(published=False).delete()\r\n```\r\n\r\n## \ud83d\udd27 Advanced Features\r\n\r\n### Transactions\r\n```python\r\nasync with db.transaction():\r\n user = await User.create(username=\"test\", email=\"test@example.com\")\r\n post = await Post.create(title=\"Test Post\", content=\"Content\", author_id=user.id)\r\n```\r\n\r\n### Complex Queries\r\n```python\r\n# Chaining filters\r\nusers = await User.objects().filter(is_active=True).exclude(username=\"admin\")\r\n\r\n# Ordering\r\nposts = await Post.objects().order_by('-created_at', 'title')\r\n\r\n# Pagination\r\npage_1_posts = await Post.objects().limit(10).offset(0)\r\n```\r\n\r\n### Field Types\r\n```python\r\nclass Product(Model):\r\n id = IntegerField(primary_key=True, auto_increment=True)\r\n name = CharField(max_length=100)\r\n description = TextField()\r\n price = FloatField()\r\n in_stock = BooleanField(default=True)\r\n created_at = DateTimeField(auto_now_add=True)\r\n updated_at = DateTimeField(auto_now=True)\r\n category_id = IntegerField(foreign_key='categories.id')\r\n tags = JSONField() # Store JSON data\r\n website = URLField()\r\n```\r\n\r\n## \ud83c\udfd7\ufe0f Model Configuration\r\n\r\n### Simple Table Name\r\n```python\r\nclass User(Model):\r\n table_name = \"app_users\" # Simple setup\r\n # ... fields\r\n```\r\n\r\n### Meta Configuration\r\n```python\r\nclass Post(Model):\r\n _meta = {'table_name': 'blog_posts'} # Traditional setup\r\n # ... fields\r\n```\r\n\r\n### Automatic Table Name\r\n```python\r\nclass Category(Model):\r\n # Table name automatically becomes 'category'\r\n # ... fields\r\n```\r\n\r\n## \ud83d\udd12 Security Features\r\n\r\n- **SQL Injection Protection**: All queries use parameterized statements\r\n- **Input Validation**: Built-in field validation\r\n- **Data Sanitization**: Automatic data cleaning\r\n- **Connection Security**: Secure connection handling\r\n\r\n## \u26a1 Performance Features\r\n\r\n- **Connection Pooling**: Reuse database connections efficiently\r\n- **Lazy Loading**: Queries execute only when needed\r\n- **Batch Operations**: Efficient bulk operations\r\n- **Memory Management**: Optimized memory usage\r\n\r\n## \ud83d\udcca Supported Databases\r\n\r\n| Database | Connection String | Package Required |\r\n|----------|-------------------|------------------|\r\n| SQLite | `sqlite:///path/to/db.sqlite` | `aiosqlite` |\r\n| MySQL | `mysql://user:pass@host:port/db` | `aiomysql` |\r\n| PostgreSQL | `postgresql://user:pass@host:port/db` | `asyncpg` |\r\n| MariaDB | `mariadb://user:pass@host:port/db` | `aiomysql` |\r\n\r\n## \ud83e\uddea Example Usage\r\n\r\n```python\r\nimport asyncio\r\nfrom ormax import Database, Model\r\nfrom ormax.fields import *\r\n\r\nclass User(Model):\r\n table_name = \"users\"\r\n id = IntegerField(primary_key=True, auto_increment=True)\r\n username = CharField(max_length=50, unique=True)\r\n email = EmailField(unique=True)\r\n is_active = BooleanField(default=True)\r\n\r\nasync def example():\r\n # Setup\r\n db = Database(\"sqlite:///example.db\")\r\n await db.connect()\r\n db.register_model(User)\r\n await db.create_tables()\r\n \r\n # Create users\r\n user1 = await User.create(username=\"alice\", email=\"alice@example.com\")\r\n user2 = await User.create(username=\"bob\", email=\"bob@example.com\")\r\n \r\n # Query users\r\n all_users = await User.objects().all()\r\n active_users = await User.objects().filter(is_active=True)\r\n \r\n # Update user\r\n user1.email = \"alice.new@example.com\"\r\n await user1.save()\r\n \r\n # Close connection\r\n await db.disconnect()\r\n\r\nif __name__ == \"__main__\":\r\n asyncio.run(example())\r\n```\r\n\r\n## \ud83d\udcda API Reference\r\n\r\n### Database Class\r\n- `Database(connection_string)` - Initialize database\r\n- `connect()` - Connect to database\r\n- `disconnect()` - Disconnect from database\r\n- `transaction()` - Context manager for transactions\r\n- `register_model(model)` - Register model with database\r\n- `create_tables()` - Create all registered tables\r\n\r\n### Model Class\r\n- `objects()` - Get QuerySet for model\r\n- `create(**kwargs)` - Create and save instance\r\n- `save()` - Save instance to database\r\n- `delete()` - Delete instance from database\r\n- `to_dict()` - Convert to dictionary\r\n\r\n### QuerySet Class\r\n- `filter(**kwargs)` - Filter records\r\n- `exclude(**kwargs)` - Exclude records\r\n- `order_by(*fields)` - Order records\r\n- `limit(count)` - Limit results\r\n- `offset(count)` - Offset results\r\n- `all()` - Get all records\r\n- `first()` - Get first record\r\n- `get(**kwargs)` - Get single record\r\n- `count()` - Count records\r\n- `exists()` - Check if records exist\r\n- `delete()` - Delete matching records\r\n- `update(**kwargs)` - Update matching records\r\n\r\n## \ud83d\udee1\ufe0f Field Types\r\n\r\n| Field | Description | Example |\r\n|-------|-------------|---------|\r\n| `CharField` | String with max length | `CharField(max_length=100)` |\r\n| `TextField` | Long text | `TextField()` |\r\n| `IntegerField` | Integer | `IntegerField()` |\r\n| `BigIntegerField` | Big integer | `BigIntegerField()` |\r\n| `FloatField` | Floating point | `FloatField()` |\r\n| `BooleanField` | Boolean | `BooleanField()` |\r\n| `DateTimeField` | DateTime | `DateTimeField(auto_now_add=True)` |\r\n| `DateField` | Date | `DateField()` |\r\n| `EmailField` | Validated email | `EmailField()` |\r\n| `URLField` | Validated URL | `URLField()` |\r\n| `JSONField` | JSON data | `JSONField()` |\r\n\r\n## \ud83e\udd1d Contributing\r\n\r\n1. Fork the repository\r\n2. Create your feature branch (`git checkout -b feature/AmazingFeature`)\r\n3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)\r\n4. Push to the branch (`git push origin feature/AmazingFeature`)\r\n5. Open a Pull Request\r\n\r\n## \ud83d\udcc4 License\r\n\r\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\r\n\r\n## \ud83d\ude4f Acknowledgments\r\n\r\n- Built with \u2764\ufe0f for the Python community\r\n- Inspired by Django ORM and SQLAlchemy\r\n- Thanks to all contributors and users\r\n\r\n## \ud83c\udd98 Support\r\n\r\nFor support, please open an issue on GitHub or contact the maintainers.\r\n\r\n---\r\n\r\n**Made with \u2764\ufe0f using Python asyncio**\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "High-performance async ORM for MariaDB, MySQL, PostgreSQL, and SQLite3",
"version": "1.0.0",
"project_urls": {
"Bug Tracker": "https://github.com/shayanheidari01/ormax/issues",
"Documentation": "https://github.com/shayanheidari01/ormax#readme",
"Homepage": "https://github.com/shayanheidari01/ormax",
"Source Code": "https://github.com/shayanheidari01/ormax"
},
"split_keywords": [
"orm",
" async",
" asyncio",
" database",
" sql",
" mysql",
" postgresql",
" sqlite",
" mariadb",
" database-orm"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "38aea0f2ea94bed5ff104b86ac9c948ebba4671cd9ffa2441a5d804dfeb612bc",
"md5": "c265fb646938e68584ec4cf95d2a6d7b",
"sha256": "1c5859dff082ab46605a0ca928c792f3a376c83034774d1cd74217489d947b9b"
},
"downloads": -1,
"filename": "ormax-1.0.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "c265fb646938e68584ec4cf95d2a6d7b",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.7",
"size": 14629,
"upload_time": "2025-07-27T23:48:31",
"upload_time_iso_8601": "2025-07-27T23:48:31.584471Z",
"url": "https://files.pythonhosted.org/packages/38/ae/a0f2ea94bed5ff104b86ac9c948ebba4671cd9ffa2441a5d804dfeb612bc/ormax-1.0.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c02b2c4879d1a7bcc030f8e4be33a13a2c86c480e602161befec07984f3bc7a0",
"md5": "5fd2ddd05285c90b885aa89791168f6d",
"sha256": "167cd0e7b31af871e67b9ca8c879d2e95fa6c3d3a16198a02d92497cff6eeded"
},
"downloads": -1,
"filename": "ormax-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "5fd2ddd05285c90b885aa89791168f6d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 17606,
"upload_time": "2025-07-27T23:48:33",
"upload_time_iso_8601": "2025-07-27T23:48:33.356166Z",
"url": "https://files.pythonhosted.org/packages/c0/2b/2c4879d1a7bcc030f8e4be33a13a2c86c480e602161befec07984f3bc7a0/ormax-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-27 23:48:33",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "shayanheidari01",
"github_project": "ormax",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "ormax"
}
JSON
