dbforge-framework 0.1.0

Unified database client for PostgreSQL, MySQL, MariaDB, MongoDB, and Redis

DBForge Framework (Python)

A unified database client for Python that provides a consistent API across PostgreSQL, MySQL, MariaDB, MongoDB, and Redis.

Features

• 🔄 Unified API - Same interface for all database types
• 🎯 Type-safe - Full type hints support
• 🚀 Simple - Minimal boilerplate, maximum productivity
• 🔌 Flexible - Direct connections or API token proxy
• 🛠️ Helper Methods - Common CRUD operations built-in

Installation

Install the base package:

pip install dbforge-framework

Install with specific database support:

# MySQL/MariaDB
pip install dbforge-framework[mysql]

# PostgreSQL
pip install dbforge-framework[postgresql]

# MongoDB
pip install dbforge-framework[mongodb]

# Redis
pip install dbforge-framework[redis]

# All databases
pip install dbforge-framework[all]

Quick Start

PostgreSQL Example

from dbforge_framework import DbForgeClient

# Option 1: Create client from credentials
client = DbForgeClient.from_credentials(
    db_type="postgresql",
    host="localhost",
    port=5432,
    username="myuser",
    password="mypass",
    database="mydb"
)

# Option 2: Create from connection string
client = DbForgeClient.from_connection_string(
    "postgresql://myuser:mypass@localhost:5432/mydb"
)

# Use context manager for automatic connection handling
with client:
    # Method 1: Direct CRUD methods
    users = client.select("users", where={"age": 25})
    client.insert("users", {"name": "Alice", "age": 25})
    client.update("users", {"age": 26}, {"name": "Alice"})
    client.delete("users", {"name": "Alice"})
    
    # Method 2: Raw SQL query
    users = client.query("SELECT * FROM users WHERE age > %s", (18,))
    
    # Method 3: Using helpers
    users = client.helpers.find_all("users", {"active": True})
    client.helpers.insert("users", {"name": "Alice", "age": 25})
    client.helpers.update("users", {"age": 26}, {"name": "Alice"})

MySQL/MariaDB Example

client = DbForgeClient.from_credentials(
    db_type="mysql",
    host="localhost",
    port=3306,
    username="root",
    password="password",
    database="testdb"
)

with client:
    # Execute queries
    result = client.query("INSERT INTO products (name, price) VALUES (%s, %s)", ("Widget", 19.99))
    
    # Use helpers
    products = client.helpers.find_all("products")
    product = client.helpers.find_one("products", {"id": 1})

MongoDB Example

client = DbForgeClient.from_credentials(
    db_type="mongodb",
    host="localhost",
    port=27017,
    username="admin",
    password="password",
    database="mydb"
)

with client:
    # Get collection
    collection = client.get_collection("users")
    
    # Use helpers
    users = client.helpers.find_all("users", {"age": {"$gt": 18}})
    user_id = client.helpers.insert("users", {"name": "Bob", "email": "[e-mail]"})
    client.helpers.update("users", {"name": "Bob"}, {"$set": {"age": 30}})

Redis Example

client = DbForgeClient.from_credentials(
    db_type="redis",
    host="localhost",
    port=6379,
    password="password",
    database="0"
)

with client:
    # Use helpers
    client.helpers.set("key", "value", ex=3600)
    value = client.helpers.get("key")
    
    # Hash operations
    client.helpers.hset("user:1001", "name", "Charlie")
    user_data = client.helpers.hgetall("user:1001")
    
    # List operations
    client.helpers.lpush("tasks", "task1", "task2")
    tasks = client.helpers.lrange("tasks", 0, -1)

API Token Mode

Instead of direct credentials, you can use DBForge API tokens:

client = DbForgeClient.from_api_token(
    api_token="your-api-token",
    instance_id="db-instance-id"
)

API Methods

Connection Methods

# From explicit credentials
client = DbForgeClient.from_credentials(
    db_type="postgresql",  # postgresql, mysql, mariadb, mongodb, redis
    host="localhost",
    port=5432,
    username="user",
    password="pass",
    database="db"
)

# From connection string
client = DbForgeClient.from_connection_string(
    "postgresql://user:pass@host:5432/db"
)

# From API token
client = DbForgeClient.from_api_token(
    api_token="token",
    instance_id="instance-id"
)

Direct CRUD Methods

with client:
    # SELECT
    rows = client.select("table", 
                        columns=["id", "name"],  # Optional
                        where={"status": "active"},  # Optional
                        limit=10,  # Optional
                        order_by="created_at DESC")  # Optional
    
    # INSERT
    row_count = client.insert("table", {"name": "Alice", "age": 25})
    
    # UPDATE
    affected = client.update("table", 
                            {"status": "inactive"}, 
                            {"id": 123})
    
    # DELETE
    deleted = client.delete("table", {"id": 123})

Helper Methods

SQL Databases (MySQL, PostgreSQL)

• find_all(table, where=None) - Select rows
• find_one(table, where) - Select single row
• insert(table, data) - Insert row
• update(table, data, where) - Update rows
• delete(table, where) - Delete rows

MongoDB

• find_all(collection, query=None) - Find documents
• find_one(collection, query) - Find single document
• insert(collection, document) - Insert document
• update(collection, query, update) - Update documents
• delete(collection, query) - Delete documents

Redis

• get(key) / set(key, value, ex=None) - String operations
• hget(name, key) / hset(name, key, value) / hgetall(name) - Hash operations
• lpush(name, *values) / rpush(name, *values) / lrange(name, start, end) - List operations
• delete(*keys) / exists(key) - Key operations

Connection Options

All database types support additional connection options:

client = DbForgeClient.from_credentials(
    db_type="postgresql",
    host="localhost",
    port=5432,
    username="user",
    password="pass",
    database="db",
    # Extra options
    connect_timeout=10,
    application_name="MyApp"
)

Manual Connection Management

If you don't want to use context managers:

client = DbForgeClient.from_credentials(...)
client.connect()

try:
    result = client.query("SELECT * FROM users")
finally:
    client.disconnect()

Requirements

• Python 3.8+
• Database drivers (installed automatically with extras):
  • MySQL/MariaDB: pymysql
  • PostgreSQL: psycopg2-binary
  • MongoDB: pymongo
  • Redis: redis

Examples

Check out the examples directory for complete working applications:

• FastAPI + PostgreSQL
• Flask + MySQL
• Django + MongoDB
• Redis + FastAPI

License

MIT License - see LICENSE file for details.

Links

• 🏠 Homepage: https://dbforge.dev
• 📚 Documentation: https://dbforge.dev/docs
• 🐙 GitHub: https://github.com/BRMilev22/DBForge
• 📦 PyPI: https://pypi.org/project/dbforge-framework/