Metadata-Version: 2.4
Name: db_sdk
Version: 4.0.14
Summary: A simple database connection SDK
Author: Neha
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: pymongo>=4.0.0
Requires-Dist: mysql-connector-python>=8.0
Requires-Dist: psycopg2-binary>=2.9.0
Requires-Dist: redis>=4.0.0
Requires-Dist: pytest>=7.0.0
Requires-Dist: pytest-cov>=4.0.0
Requires-Dist: mongomock>=4.1.2
Dynamic: author
Dynamic: description
Dynamic: description-content-type
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# 🗄️ Universal DB SDK

A lightweight, plug-and-play Python SDK for connecting to multiple databases
(MySQL, PostgreSQL, MongoDB, Redis) through a single unified interface.

---

## 📦 Installation
```bash
pip install db-sdk
```

Install only the drivers you need:
```bash
pip install mysql-connector-python   # MySQL
pip install psycopg2-binary          # PostgreSQL
pip install pymongo                  # MongoDB
pip install redis                    # Redis
```

---

## ✨ Features

- **One interface** for MySQL, PostgreSQL, MongoDB, and Redis
- **No boilerplate** — one function call returns a live connection
- **Easy to extend** — add a new database in minutes
- **Clean error handling** — typed exceptions for every failure mode
- **Zero framework dependency** — works with FastAPI, Django, Flask, or plain Python

---

## 🚀 Quick Start
```python
from db_sdk.core.factory import ConnectionFactory

conn = ConnectionFactory.create_connection("mysql", {
    "host": "localhost",
    "user": "root",
    "password": "yourpassword",
    "database": "mydb",
    "port": 3306
})
```

That's it. `conn` is a live, ready-to-use connection object.

---

## 🔌 Supported Databases

| Database   | Type string  | Driver used                  |
|------------|--------------|------------------------------|
| MySQL      | `"mysql"`    | `mysql-connector-python`     |
| PostgreSQL | `"postgres"` | `psycopg2`                   |
| MongoDB    | `"mongodb"`  | `pymongo`                    |
| Redis      | `"redis"`    | `redis`                      |

---

## ⚙️ Configuration Reference

### MySQL
```python
conn = ConnectionFactory.create_connection("mysql", {
    "host":     "localhost",
    "user":     "root",
    "password": "yourpassword",
    "database": "mydb",
    "port":     3306          # optional, defaults to 3306
})
```

### PostgreSQL
```python
conn = ConnectionFactory.create_connection("postgres", {
    "host":     "localhost",
    "user":     "postgres",
    "password": "yourpassword",
    "database": "mydb",
    "port":     5432          # optional, defaults to 5432
})
```

### MongoDB
```python
conn = ConnectionFactory.create_connection("mongodb", {
    "uri": "mongodb://user:password@localhost:27017/mydb"
})
```

> MongoDB uses a URI string instead of separate fields.
> Format: `mongodb://user:password@host:port/database`

### Redis
```python
conn = ConnectionFactory.create_connection("redis", {
    "host": "localhost",
    "port": 6379             # optional, defaults to 6379
})
```

---

## 🏗️ Project Structure
```
db_sdk/
├── __init__.py
├── settings.py
├── core/
│   ├── base_connector.py    # Abstract base all connectors inherit from
│   ├── exceptions.py        # All SDK exception types
│   └── factory.py           # ConnectionFactory — the main entry point
└── connectors/
    ├── mysql.py             # MySQL connector
    ├── postgres.py          # PostgreSQL connector
    ├── mongodb.py           # MongoDB connector
    └── redis.py             # Redis connector
```

---

## ⚠️ Error Handling

The SDK raises typed exceptions so you can handle failures precisely:
```python
from db_sdk.core.factory import ConnectionFactory
from db_sdk.core.exceptions import (
    DatabaseConnectionError,
    UnsupportedDatabaseError,
    ConfigurationError,
)

try:
    conn = ConnectionFactory.create_connection("mysql", config)

except DatabaseConnectionError as e:
    # Connection failed — wrong password, DB offline, network issue
    print(f"Could not connect: {e}")

except UnsupportedDatabaseError as e:
    # db_type string not recognised
    print(f"Unknown database type: {e}")

except ConfigurationError as e:
    # Missing or invalid keys in the config dict
    print(f"Bad config: {e}")
```

### Exception Hierarchy
```
UniversalDBException          ← catch this for any SDK error
    ├── DatabaseConnectionError
    ├── UnsupportedDatabaseError
    └── ConfigurationError
```

