<h1 align="center">🚀 DBFlux: Lightweight Database Management Library</h1>
<p align="center">
<a href="https://pypi.org/project/dbflux/"><img src="https://img.shields.io/pypi/v/dbflux?style=plastic" alt="PyPI - Version"></a>
<a href="https://github.com/abbas-bachari/dbflux"><img src="https://img.shields.io/badge/Python%20-3.8+-green?style=plastic&logo=Python" alt="Python"></a>
<a href="https://pypi.org/project/dbflux/"><img src="https://img.shields.io/pypi/l/dbflux?style=plastic" alt="License"></a>
<a href="https://pepy.tech/project/dbflux"><img src="https://pepy.tech/badge/dbflux?style=flat-plastic" alt="Downloads"></a>
</p>
## 🛠️ Version 1.0.2
## 🌟 **Introduction**
#### **DBFlux** is a lightweight, easy-to-use library built on top of **SQLAlchemy** to simplify database operations in Python.
#### It provides a streamlined interface for **connecting to databases**, **managing sessions**, and **performing CRUD operations** with minimal effort.
---
## ✨ **Features**
* 🔁 Automatic Transaction Management
* 🛠️ Session Handling
* 🔗 Flexibility – Supports multiple database engines via SQLAlchemy
* ⚡ Lightweight & Efficient
* 🔍 Advanced Filtering
* 📥 Data Insertion
* ✏️ Data Modification
* 📄 Easy Pagination
* 🛡️ Safe Deletion
* 📦 Consistent Output Handling
---
## 📚 **Requirements**
* **Python 3.8+**
* **SQLAlchemy >= 2.0**
---
## 🔧 **Installation**
Install **dbflux** via **pip**:
```bash
pip install dbflux
```
Or install from source:
```bash
git clone https://github.com/abbas-bachari/dbflux.git
cd dbflux
pip install .
```
---
## 💡 **Quick Start**
```python
from dbflux import Sqlite,DBModel
from sqlalchemy import Column, Integer, String, Float
from sqlalchemy.orm import declarative_base
from time import time
Base=declarative_base()
db = Sqlite(db_name="example.db")
class User(Base):
__tablename__ = "users"
id = Column(Integer, primary_key=True)
name = Column(String(50))
email = Column(String(100))
age = Column(Integer)
def __repr__(self):
return f"User(id={self.id}, name={self.name}, email={self.email}, age={self.age})"
class Order(Base):
__tablename__ = "orders"
order_id = Column(Integer, primary_key=True)
product = Column(String, nullable=False)
price = Column(Float, nullable=False)
time = Column(Integer, nullable=False)
def to_dict(self):
return {
"order_id": self.order_id,
"product": self.product,
"price": self.price,
"time": self.time
}
def __str__(self):
return json.dumps(self.to_dict(), indent=4,ensure_ascii=False)
def __repr__(self):
return f"Order(order_id={self.order_id}, product={self.product}, price={self.price}, time={self.time})"
db.create_tables(Base)
users=DBModel(User,db)
orders=DBModel(Order,db)
users_data=[
{"id": 1, "name": "Alice", "email": "alice@test.com","age":22},
{"id": 2, "name": "Bob", "email": "bob@test.com","age":21},
{"id": 3, "name": "Carol", "email": "carol@test.com","age":18}
]
orders_data=[
{"order_id": 1, "product": "Product A", "price": 100, "time": time()},
{"order_id": 2, "product": "Product B", "price": 200, "time": time()},
{"order_id": 3, "product": "Product C", "price": 300, "time": time()}
]
users.insert(users_data)
orders.insert(orders_data)
```
---
## 💡 **Examples Usage DBFactory**
```python
Base = declarative_base()
class Order(Base):
__tablename__ = "orders"
order_id = Column(Integer, primary_key=True)
product = Column(String, nullable=False)
price = Column(Float, nullable=False)
time = Column(Integer, nullable=False)
def to_dict(self):
return {
"order_id": self.order_id,
"product": self.product,
"price": self.price,
"time": self.time
}
def __str__(self):
return json.dumps(self.to_dict(), indent=4,ensure_ascii=False)
def __repr__(self):
return f"Order(order_id={self.order_id}, product={self.product}, price={self.price}, time={self.time})"
factory = DBFactory(db_name="data.db")
db = factory.create("sqlite")
db.create_tables(Base)
orders_db = DBModel(Order ,db)
order = Order(order_id=1, product="Product A", price=100, time=time())
orders_db.insert( order)
orders:list[Order] = orders_db.get(limit=1)
print(orders)
>>> [Order(order_id=1, product=Product A, price=100.0, time=1755924289.1132557)]
print(orders[0])
>>> {
"order_id": 1,
"product": "Product A",
"price": 100.0,
"time": 1755924289.1132557
}
```
---
## 🔹 Supported Database Types
| Type | Aliases |
| ---------- | -------------------- |
| SQLite | sqlite |
| MySQL | mysql |
| PostgreSQL | postgres, postgresql |
| MariaDB | mariadb |
| Oracle | oracle |
| DB2 | db2, ibmdb2 |
| Firebird | firebird |
| MSSQL | mssql, sqlserver |
---
## 🔹 Examples for Different Databases
```python
from dbflux.databases import Sqlite, MySQL, PostgreSQL
# Example 1: SQLite
sqlite_db = Sqlite(db_name="data.db")
sqlite_db.create_tables(Base)
sqlite_db.insert(model_class= Order ,data=Order(order_id=10, product="SQLite Product", price=50, time=time()))
# Example 2: MySQL
mysql_db = MySQL(db_name="test_db",username="root", password="password", host="localhost", )
mysql_db.create_tables(Base)
mysql_db.insert(model_class= Order ,data=Order(order_id=11, product="MySQL Product", price=60, time=time()))
# Example 3: PostgreSQL
postgres_db = PostgreSQL(db_name="test_db",username="postgres", password="secret", host="localhost")
postgres_db.create_tables(Base)
postgres_db.insert(model_class= Order ,data=Order(order_id=12, product="PostgreSQL Product", price=70, time=time()))
```
---
### 🎯 Summary of Features
#### ✅ CRUD Operations
#### ✅ Bulk Insert & Bulk Update
#### ✅ Advanced Filtering (OR/AND/Range)
#### ✅ Pagination
#### ✅ JSON Output
#### ✅ Transaction Safety
#### ✅ Direct SQLAlchemy Access via BaseDB
---
## 📖 **Documentation**
For more details, visit the [official SQLAlchemy documentation](https://docs.sqlalchemy.org/).
---
## 📜 **License**
This project is licensed under the **[MIT License](LICENSE)**.
---
## 👤 **Publisher / ناشر**
**[Abbas Bachari / عباس بچاری](https://github.com/abbas-bachari)**
---
## 💖 **Sponsor**
Support development by sponsoring on **[Github Sponsors](https://github.com/sponsors/abbas-bachari)**.
Raw data
{
"_id": null,
"home_page": null,
"name": "dbflux",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "database, SQLAlchemy, ORM, Python",
"author": null,
"author_email": "Abbas Bachari <abbas-bachari@hotmail.com>",
"download_url": "https://files.pythonhosted.org/packages/b5/1f/11b2f5ea890515e54e29b4a83ed2379007073594ee1ededd4f7cac52475b/dbflux-1.0.2.tar.gz",
"platform": null,
"description": "<h1 align=\"center\">\ud83d\ude80 DBFlux: Lightweight Database Management Library</h1>\r\n\r\n<p align=\"center\">\r\n<a href=\"https://pypi.org/project/dbflux/\"><img src=\"https://img.shields.io/pypi/v/dbflux?style=plastic\" alt=\"PyPI - Version\"></a>\r\n<a href=\"https://github.com/abbas-bachari/dbflux\"><img src=\"https://img.shields.io/badge/Python%20-3.8+-green?style=plastic&logo=Python\" alt=\"Python\"></a>\r\n <a href=\"https://pypi.org/project/dbflux/\"><img src=\"https://img.shields.io/pypi/l/dbflux?style=plastic\" alt=\"License\"></a>\r\n <a href=\"https://pepy.tech/project/dbflux\"><img src=\"https://pepy.tech/badge/dbflux?style=flat-plastic\" alt=\"Downloads\"></a>\r\n</p>\r\n\r\n## \ud83d\udee0\ufe0f Version 1.0.2\r\n\r\n## \ud83c\udf1f **Introduction**\r\n\r\n#### **DBFlux** is a lightweight, easy-to-use library built on top of **SQLAlchemy** to simplify database operations in Python. \r\n\r\n#### It provides a streamlined interface for **connecting to databases**, **managing sessions**, and **performing CRUD operations** with minimal effort.\r\n\r\n---\r\n\r\n## \u2728 **Features**\r\n\r\n* \ud83d\udd01 Automatic Transaction Management\r\n* \ud83d\udee0\ufe0f Session Handling\r\n* \ud83d\udd17 Flexibility \u2013 Supports multiple database engines via SQLAlchemy\r\n* \u26a1 Lightweight & Efficient\r\n* \ud83d\udd0d Advanced Filtering\r\n* \ud83d\udce5 Data Insertion\r\n* \u270f\ufe0f Data Modification\r\n* \ud83d\udcc4 Easy Pagination\r\n* \ud83d\udee1\ufe0f Safe Deletion\r\n* \ud83d\udce6 Consistent Output Handling\r\n\r\n---\r\n\r\n## \ud83d\udcda **Requirements**\r\n\r\n* **Python 3.8+**\r\n* **SQLAlchemy >= 2.0**\r\n\r\n---\r\n\r\n## \ud83d\udd27 **Installation**\r\n\r\nInstall **dbflux** via **pip**:\r\n\r\n```bash\r\npip install dbflux\r\n```\r\n\r\nOr install from source:\r\n\r\n```bash\r\ngit clone https://github.com/abbas-bachari/dbflux.git\r\ncd dbflux\r\npip install .\r\n```\r\n\r\n---\r\n\r\n\r\n## \ud83d\udca1 **Quick Start**\r\n\r\n```python\r\n\r\nfrom dbflux import Sqlite,DBModel\r\nfrom sqlalchemy import Column, Integer, String, Float\r\nfrom sqlalchemy.orm import declarative_base\r\nfrom time import time\r\n\r\nBase=declarative_base()\r\ndb = Sqlite(db_name=\"example.db\")\r\n\r\n\r\nclass User(Base):\r\n __tablename__ = \"users\"\r\n id = Column(Integer, primary_key=True)\r\n name = Column(String(50))\r\n email = Column(String(100))\r\n age = Column(Integer)\r\n def __repr__(self):\r\n return f\"User(id={self.id}, name={self.name}, email={self.email}, age={self.age})\"\r\n\r\nclass Order(Base):\r\n __tablename__ = \"orders\"\r\n order_id = Column(Integer, primary_key=True)\r\n product = Column(String, nullable=False)\r\n price = Column(Float, nullable=False)\r\n time = Column(Integer, nullable=False)\r\n \r\n def to_dict(self):\r\n return {\r\n \"order_id\": self.order_id,\r\n \"product\": self.product,\r\n \"price\": self.price,\r\n \"time\": self.time\r\n }\r\n \r\n def __str__(self):\r\n return json.dumps(self.to_dict(), indent=4,ensure_ascii=False)\r\n\r\n def __repr__(self):\r\n return f\"Order(order_id={self.order_id}, product={self.product}, price={self.price}, time={self.time})\"\r\n\r\n\r\ndb.create_tables(Base)\r\n\r\n\r\nusers=DBModel(User,db)\r\norders=DBModel(Order,db)\r\n\r\n\r\nusers_data=[\r\n {\"id\": 1, \"name\": \"Alice\", \"email\": \"alice@test.com\",\"age\":22},\r\n {\"id\": 2, \"name\": \"Bob\", \"email\": \"bob@test.com\",\"age\":21},\r\n {\"id\": 3, \"name\": \"Carol\", \"email\": \"carol@test.com\",\"age\":18}\r\n]\r\n\r\norders_data=[\r\n {\"order_id\": 1, \"product\": \"Product A\", \"price\": 100, \"time\": time()},\r\n {\"order_id\": 2, \"product\": \"Product B\", \"price\": 200, \"time\": time()},\r\n {\"order_id\": 3, \"product\": \"Product C\", \"price\": 300, \"time\": time()}\r\n]\r\n\r\nusers.insert(users_data)\r\norders.insert(orders_data)\r\n\r\n```\r\n\r\n---\r\n\r\n## \ud83d\udca1 **Examples Usage DBFactory**\r\n\r\n```python\r\nBase = declarative_base()\r\n\r\nclass Order(Base):\r\n __tablename__ = \"orders\"\r\n\r\n order_id = Column(Integer, primary_key=True)\r\n product = Column(String, nullable=False)\r\n price = Column(Float, nullable=False)\r\n time = Column(Integer, nullable=False)\r\n \r\n def to_dict(self):\r\n return {\r\n \"order_id\": self.order_id,\r\n \"product\": self.product,\r\n \"price\": self.price,\r\n \"time\": self.time\r\n }\r\n \r\n def __str__(self):\r\n return json.dumps(self.to_dict(), indent=4,ensure_ascii=False)\r\n\r\n def __repr__(self):\r\n return f\"Order(order_id={self.order_id}, product={self.product}, price={self.price}, time={self.time})\"\r\n \r\n\r\n\r\nfactory = DBFactory(db_name=\"data.db\")\r\n\r\ndb = factory.create(\"sqlite\")\r\n\r\ndb.create_tables(Base)\r\n\r\norders_db = DBModel(Order ,db)\r\n\r\n\r\norder = Order(order_id=1, product=\"Product A\", price=100, time=time())\r\n\r\norders_db.insert( order)\r\n\r\norders:list[Order] = orders_db.get(limit=1)\r\n\r\nprint(orders)\r\n\r\n>>> [Order(order_id=1, product=Product A, price=100.0, time=1755924289.1132557)]\r\n\r\nprint(orders[0])\r\n\r\n>>> {\r\n \"order_id\": 1,\r\n \"product\": \"Product A\",\r\n \"price\": 100.0,\r\n \"time\": 1755924289.1132557\r\n }\r\n\r\n```\r\n\r\n---\r\n\r\n\r\n## \ud83d\udd39 Supported Database Types\r\n\r\n| Type | Aliases |\r\n| ---------- | -------------------- |\r\n| SQLite | sqlite |\r\n| MySQL | mysql |\r\n| PostgreSQL | postgres, postgresql |\r\n| MariaDB | mariadb |\r\n| Oracle | oracle |\r\n| DB2 | db2, ibmdb2 |\r\n| Firebird | firebird |\r\n| MSSQL | mssql, sqlserver |\r\n\r\n---\r\n\r\n## \ud83d\udd39 Examples for Different Databases\r\n\r\n```python\r\nfrom dbflux.databases import Sqlite, MySQL, PostgreSQL\r\n\r\n# Example 1: SQLite\r\nsqlite_db = Sqlite(db_name=\"data.db\")\r\nsqlite_db.create_tables(Base)\r\nsqlite_db.insert(model_class= Order ,data=Order(order_id=10, product=\"SQLite Product\", price=50, time=time()))\r\n\r\n# Example 2: MySQL\r\nmysql_db = MySQL(db_name=\"test_db\",username=\"root\", password=\"password\", host=\"localhost\", )\r\nmysql_db.create_tables(Base)\r\nmysql_db.insert(model_class= Order ,data=Order(order_id=11, product=\"MySQL Product\", price=60, time=time()))\r\n\r\n# Example 3: PostgreSQL\r\npostgres_db = PostgreSQL(db_name=\"test_db\",username=\"postgres\", password=\"secret\", host=\"localhost\")\r\npostgres_db.create_tables(Base)\r\npostgres_db.insert(model_class= Order ,data=Order(order_id=12, product=\"PostgreSQL Product\", price=70, time=time()))\r\n```\r\n\r\n---\r\n\r\n### \ud83c\udfaf Summary of Features\r\n\r\n#### \u2705 CRUD Operations \r\n\r\n#### \u2705 Bulk Insert & Bulk Update \r\n\r\n#### \u2705 Advanced Filtering (OR/AND/Range) \r\n\r\n#### \u2705 Pagination \r\n\r\n#### \u2705 JSON Output \r\n\r\n#### \u2705 Transaction Safety \r\n\r\n#### \u2705 Direct SQLAlchemy Access via BaseDB \r\n\r\n---\r\n\r\n## \ud83d\udcd6 **Documentation**\r\n\r\nFor more details, visit the [official SQLAlchemy documentation](https://docs.sqlalchemy.org/).\r\n\r\n---\r\n\r\n## \ud83d\udcdc **License**\r\n\r\nThis project is licensed under the **[MIT License](LICENSE)**.\r\n\r\n---\r\n\r\n## \ud83d\udc64 **Publisher / \u0646\u0627\u0634\u0631**\r\n\r\n**[Abbas Bachari / \u0639\u0628\u0627\u0633 \u0628\u0686\u0627\u0631\u06cc](https://github.com/abbas-bachari)**\r\n\r\n---\r\n\r\n## \ud83d\udc96 **Sponsor**\r\n\r\nSupport development by sponsoring on **[Github Sponsors](https://github.com/sponsors/abbas-bachari)**.\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A simple database management abstraction layer built on SQLAlchemy",
"version": "1.0.2",
"project_urls": {
"bug-tracker": "https://github.com/abbas-bachari/dbflux/issues",
"documentation": "https://github.com/abbas-bachari/dbflux#readme",
"homepage": "https://github.com/abbas-bachari/dbflux"
},
"split_keywords": [
"database",
" sqlalchemy",
" orm",
" python"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c7528ce0d62a80344fb202d0346ef42047db3e48b2d881b8860f220d796cac47",
"md5": "c97b4545a61f0293f6677aca96fe2411",
"sha256": "9edda4ea4e7e489d301bd8512896ece5e4b698401d900b2f2ff426f279b52858"
},
"downloads": -1,
"filename": "dbflux-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c97b4545a61f0293f6677aca96fe2411",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 13679,
"upload_time": "2025-08-23T05:21:11",
"upload_time_iso_8601": "2025-08-23T05:21:11.318792Z",
"url": "https://files.pythonhosted.org/packages/c7/52/8ce0d62a80344fb202d0346ef42047db3e48b2d881b8860f220d796cac47/dbflux-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b51f11b2f5ea890515e54e29b4a83ed2379007073594ee1ededd4f7cac52475b",
"md5": "5a0fde3d60342c35e4cd94df636c5614",
"sha256": "332684da6c46758328e73a5543b544a28c52a1759df72aaf399c8b4987242b66"
},
"downloads": -1,
"filename": "dbflux-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "5a0fde3d60342c35e4cd94df636c5614",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 13216,
"upload_time": "2025-08-23T05:21:13",
"upload_time_iso_8601": "2025-08-23T05:21:13.812503Z",
"url": "https://files.pythonhosted.org/packages/b5/1f/11b2f5ea890515e54e29b4a83ed2379007073594ee1ededd4f7cac52475b/dbflux-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-23 05:21:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "abbas-bachari",
"github_project": "dbflux",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "SQLAlchemy",
"specs": [
[
">=",
"2.0.0"
]
]
}
],
"lcname": "dbflux"
}
JSON
