nexora-db 0.1.0__tar.gz

nexora_db-0.1.0/PKG-INFO

@@ -0,0 +1,238 @@
+Metadata-Version: 2.4
+Name: nexora_db
+Version: 0.1.0
+Summary: Shared database layer for Nexora monitoring platform
+Author: Derradji
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: SQLAlchemy==2.0.43
+Requires-Dist: psycopg2-binary==2.9.11
+Requires-Dist: python-dotenv==1.1.1
+Requires-Dist: pydantic==2.11.7
+Requires-Dist: pydantic-settings==2.10.1
+
+# nexora_db
+
+**Shared database layer for the Nexora monitoring platform.**
+
+`nexora_db` is an installable Python package that provides a unified, reusable database interface for all Nexora services. It encapsulates SQLAlchemy models, database configuration, and CRUD operations for users, devices, and alerts — keeping your database logic in one place and out of your application code.
+
+---
+
+## Table of Contents
+
+- [Features](#features)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Configuration](#configuration)
+- [Project Structure](#project-structure)
+- [Usage](#usage)
+  - [Initialize the Database](#1-initialize-the-database)
+  - [Session Usage](#2-session-usage)
+  - [Users](#3-users)
+  - [Pydantic Schemas](#4-pydantic-schemas)
+- [Development](#development)
+---
+
+## Features
+
+- 🗄️ **Centralized database layer** — one package, shared across all Nexora microservices
+- 🔌 **PostgreSQL support** via `psycopg2-binary` and SQLAlchemy 2.0
+- 🧱 **SQLAlchemy ORM models** for Users, Devices, and Alerts
+- ⚙️ **Pydantic-based configuration** with `.env` file support
+- 📦 **Installable as a package** via `pip` or `pyproject.toml`
+
+---
+
+## Requirements
+
+- Python >= 3.9
+- PostgreSQL database instance
+
+---
+
+## Installation
+
+Install directly from source:
+
+```bash
+pip install .
+```
+
+Or install in editable/development mode:
+
+```bash
+pip install -e .
+```
+
+### Dependencies
+
+| Package | Version |
+|---|---|
+| SQLAlchemy | 2.0.43 |
+| psycopg2-binary | 2.9.11 |
+| python-dotenv | 1.1.1 |
+| pydantic | 2.11.7 |
+| pydantic-settings | 2.10.1 |
+
+---
+
+## Configuration
+
+`nexora_db` uses `pydantic-settings` to load configuration from environment variables or a `.env` file.
+
+Create a `.env` file in your project root:
+
+```env
+DATABASE_URL=postgresql://user:password@localhost:5432/nexora_db
+```
+
+> The `DATABASE_URL` environment variable must be set before importing any models or operations.
+
+---
+
+## Project Structure
+
+```
+nexora_db/
+├── __init__.py
+│
+├── configs/
+│   ├── __init__.py
+│   └── database.py          # Engine, session factory, Base declarative
+│
+├── models/
+│   ├── __init__.py
+│   ├── user.py              # User ORM model
+│   ├── devices_model.py     # Device ORM model
+│   └── alerts_model.py      # Alert ORM model
+│
+└── operations/
+    ├── __init__.py
+    ├── users_service.py     # User CRUD operations
+    ├── devices_ops.py       # Device CRUD operations
+    └── alerts_ops.py        # Alert CRUD operations
+```
+
+---
+
+## Usage
+
+### 1. Initialize the Database
+
+Before using any models or operations, call `init_database()` once at application startup with your PostgreSQL connection URL, then call `init_db_tables()` to create all tables.
+
+```python
+from nexora_db.configs.database import init_database, init_db_tables
+
+init_database("postgresql://user:password@localhost:5432/nexora_db")
+init_db_tables()
+```
+
+> `get_db()` and all operations will raise a `RuntimeError` if called before `init_database()`.
+
+---
+
+### 2. Session Usage
+
+`get_db()` is a generator — use it with `next()` or inside a dependency injection framework (e.g. FastAPI):
+
+```python
+from nexora_db.configs.database import get_db
+
+# Manual usage
+db = next(get_db())
+try:
+    # ... perform operations ...
+finally:
+    db.close()
+```
+
+```python
+# FastAPI dependency injection
+from fastapi import Depends
+from nexora_db.configs.database import get_db
+
+@app.get("/example")
+def example_route(db=Depends(get_db)):
+    ...
+```
+
+---
+
+### 3. Users
+
+`UserOperations` wraps all user-related database logic. Instantiate it after `init_database()` has been called.
+
+```python
+from nexora_db.operations.users_service import UserOperations, UserUtils
+from nexora_db.schema.validator import UserCreate
+
+user_ops = UserOperations()
+
+# Create a new user
+user = user_ops.create_user(
+    email="alice@example.com",
+    hashed_password="hashed_secret"
+)
+
+# Fetch by email
+user = user_ops.get_user_by_email("alice@example.com")
+
+# Fetch all users
+users = user_ops.get_all_users()
+
+# Update a user
+updated = user_ops.update_user(user_id=1, data=UserCreate(email="new@example.com", password="new_hash"))
+
+# Delete a user
+deleted = user_ops.delete_user(user_id=1)
+
+# Extract username from email
+username = UserUtils.get_username_from_email("alice@example.com")  # → "alice"
+```
+
+---
+
+### 4. Pydantic Schemas
+
+`nexora_db` ships with Pydantic v2 schemas for input validation and API serialization.
+
+```python
+from nexora_db.schema.validator import UserCreate, UserOut, DeviceCreateForm, DeviceUpdateForm
+
+# Validate user input
+payload = UserCreate(email="alice@example.com", password="secret123")
+
+# Validate device registration
+device_form = DeviceCreateForm(
+    hostname="router-01",
+    device_type="router",
+    ip_address="192.168.1.1",
+    mac_address="AA:BB:CC:DD:EE:FF"
+)
+
+# Partial device update
+update_form = DeviceUpdateForm(ip_address="10.0.0.5")
+```
+
+**Available schemas:**
+
+| Schema | Purpose |
+|---|---|
+| `UserCreate` | Email + password for creating/updating a user |
+| `UserOut` | Serialized user response (id, email, role) |
+| `DeviceCreateForm` | Full device registration payload |
+| `DeviceUpdateForm` | Partial device update (all fields optional) |
+
+---
+
+## Development
+
+Clone the repository and install in editable mode:
+
+```bash
+git clone https://github.com/your-org/nexora_db.git
+cd nexora_db
+pip install -e .
+```

nexora_db-0.1.0/README.md

@@ -0,0 +1,225 @@
+# nexora_db
+
+**Shared database layer for the Nexora monitoring platform.**
+
+`nexora_db` is an installable Python package that provides a unified, reusable database interface for all Nexora services. It encapsulates SQLAlchemy models, database configuration, and CRUD operations for users, devices, and alerts — keeping your database logic in one place and out of your application code.
+
+---
+
+## Table of Contents
+
+- [Features](#features)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Configuration](#configuration)
+- [Project Structure](#project-structure)
+- [Usage](#usage)
+  - [Initialize the Database](#1-initialize-the-database)
+  - [Session Usage](#2-session-usage)
+  - [Users](#3-users)
+  - [Pydantic Schemas](#4-pydantic-schemas)
+- [Development](#development)
+---
+
+## Features
+
+- 🗄️ **Centralized database layer** — one package, shared across all Nexora microservices
+- 🔌 **PostgreSQL support** via `psycopg2-binary` and SQLAlchemy 2.0
+- 🧱 **SQLAlchemy ORM models** for Users, Devices, and Alerts
+- ⚙️ **Pydantic-based configuration** with `.env` file support
+- 📦 **Installable as a package** via `pip` or `pyproject.toml`
+
+---
+
+## Requirements
+
+- Python >= 3.9
+- PostgreSQL database instance
+
+---
+
+## Installation
+
+Install directly from source:
+
+```bash
+pip install .
+```
+
+Or install in editable/development mode:
+
+```bash
+pip install -e .
+```
+
+### Dependencies
+
+| Package | Version |
+|---|---|
+| SQLAlchemy | 2.0.43 |
+| psycopg2-binary | 2.9.11 |
+| python-dotenv | 1.1.1 |
+| pydantic | 2.11.7 |
+| pydantic-settings | 2.10.1 |
+
+---
+
+## Configuration
+
+`nexora_db` uses `pydantic-settings` to load configuration from environment variables or a `.env` file.
+
+Create a `.env` file in your project root:
+
+```env
+DATABASE_URL=postgresql://user:password@localhost:5432/nexora_db
+```
+
+> The `DATABASE_URL` environment variable must be set before importing any models or operations.
+
+---
+
+## Project Structure
+
+```
+nexora_db/
+├── __init__.py
+│
+├── configs/
+│   ├── __init__.py
+│   └── database.py          # Engine, session factory, Base declarative
+│
+├── models/
+│   ├── __init__.py
+│   ├── user.py              # User ORM model
+│   ├── devices_model.py     # Device ORM model
+│   └── alerts_model.py      # Alert ORM model
+│
+└── operations/
+    ├── __init__.py
+    ├── users_service.py     # User CRUD operations
+    ├── devices_ops.py       # Device CRUD operations
+    └── alerts_ops.py        # Alert CRUD operations
+```
+
+---
+
+## Usage
+
+### 1. Initialize the Database
+
+Before using any models or operations, call `init_database()` once at application startup with your PostgreSQL connection URL, then call `init_db_tables()` to create all tables.
+
+```python
+from nexora_db.configs.database import init_database, init_db_tables
+
+init_database("postgresql://user:password@localhost:5432/nexora_db")
+init_db_tables()
+```
+
+> `get_db()` and all operations will raise a `RuntimeError` if called before `init_database()`.
+
+---
+
+### 2. Session Usage
+
+`get_db()` is a generator — use it with `next()` or inside a dependency injection framework (e.g. FastAPI):
+
+```python
+from nexora_db.configs.database import get_db
+
+# Manual usage
+db = next(get_db())
+try:
+    # ... perform operations ...
+finally:
+    db.close()
+```
+
+```python
+# FastAPI dependency injection
+from fastapi import Depends
+from nexora_db.configs.database import get_db
+
+@app.get("/example")
+def example_route(db=Depends(get_db)):
+    ...
+```
+
+---
+
+### 3. Users
+
+`UserOperations` wraps all user-related database logic. Instantiate it after `init_database()` has been called.
+
+```python
+from nexora_db.operations.users_service import UserOperations, UserUtils
+from nexora_db.schema.validator import UserCreate
+
+user_ops = UserOperations()
+
+# Create a new user
+user = user_ops.create_user(
+    email="alice@example.com",
+    hashed_password="hashed_secret"
+)
+
+# Fetch by email
+user = user_ops.get_user_by_email("alice@example.com")
+
+# Fetch all users
+users = user_ops.get_all_users()
+
+# Update a user
+updated = user_ops.update_user(user_id=1, data=UserCreate(email="new@example.com", password="new_hash"))
+
+# Delete a user
+deleted = user_ops.delete_user(user_id=1)
+
+# Extract username from email
+username = UserUtils.get_username_from_email("alice@example.com")  # → "alice"
+```
+
+---
+
+### 4. Pydantic Schemas
+
+`nexora_db` ships with Pydantic v2 schemas for input validation and API serialization.
+
+```python
+from nexora_db.schema.validator import UserCreate, UserOut, DeviceCreateForm, DeviceUpdateForm
+
+# Validate user input
+payload = UserCreate(email="alice@example.com", password="secret123")
+
+# Validate device registration
+device_form = DeviceCreateForm(
+    hostname="router-01",
+    device_type="router",
+    ip_address="192.168.1.1",
+    mac_address="AA:BB:CC:DD:EE:FF"
+)
+
+# Partial device update
+update_form = DeviceUpdateForm(ip_address="10.0.0.5")
+```
+
+**Available schemas:**
+
+| Schema | Purpose |
+|---|---|
+| `UserCreate` | Email + password for creating/updating a user |
+| `UserOut` | Serialized user response (id, email, role) |
+| `DeviceCreateForm` | Full device registration payload |
+| `DeviceUpdateForm` | Partial device update (all fields optional) |
+
+---
+
+## Development
+
+Clone the repository and install in editable mode:
+
+```bash
+git clone https://github.com/your-org/nexora_db.git
+cd nexora_db
+pip install -e .
+```

nexora_db-0.1.0/nexora_db/configs/database.py

@@ -0,0 +1,34 @@
+from sqlalchemy import create_engine
+from sqlalchemy.orm import sessionmaker, declarative_base
+
+base = declarative_base()
+
+engine = None
+SessionLocal = None
+
+
+def init_database(database_url: str):
+    global engine, SessionLocal
+
+    engine = create_engine(database_url)
+    SessionLocal = sessionmaker(
+        autocommit=False,
+        autoflush=False,
+        bind=engine
+    )
+
+
+def get_db():
+    if SessionLocal is None:
+        raise RuntimeError("Database not initialized. Call init_database() first.")
+    db = SessionLocal()
+    try:
+        yield db
+    finally:
+        db.close()
+
+
+def init_db_tables():
+    if engine is None:
+        raise RuntimeError("Database not initialized.")
+    base.metadata.create_all(bind=engine)

nexora_db-0.1.0/nexora_db/models/alerts_model.py

@@ -0,0 +1,16 @@
+from sqlalchemy import Column, Integer, String, ForeignKey, DateTime
+from sqlalchemy.orm import relationship
+from nexora_db.configs.database import base
+from datetime import datetime
+
+
+class Alerts(base):
+    __tablename__ = "alerts"
+
+    id = Column(Integer, primary_key=True, index=True)
+    alert_message = Column(String(100), nullable=False)
+    alert_level = Column(String(10), nullable=False)
+    alert_time = Column(DateTime, default=datetime.utcnow())
+
+    device_id = Column(Integer, ForeignKey("device.id"), nullable=True)
+    device = relationship("Device", back_populates="alerts_device")

nexora_db-0.1.0/nexora_db/models/devices_model.py

@@ -0,0 +1,26 @@
+from sqlalchemy import Column, Integer, String, DateTime
+from sqlalchemy.orm import relationship
+from nexora_db.configs.database import base
+from datetime import datetime
+from sqlalchemy.orm import validates
+
+
+class Device(base):
+    __tablename__ = "device"
+
+    id = Column(Integer, primary_key=True, index=True)
+    hostname = Column(String(20), nullable=False)
+    device_type = Column(String(10))
+    ip_address = Column(String(15), unique=True, nullable=False)
+    mac_address = Column(String(30) , unique=True, nullable=False)
+    status = Column(String(10))
+    interval = Column(Integer, default=5)
+    last_seen = Column(DateTime, default=datetime.utcnow())
+
+    alerts_device = relationship("Alerts", back_populates="device", cascade="all, delete-orphan")
+
+    @validates("mac_address")
+    def validate_mac(self, key, value):
+        if self.mac_address is not None:
+            raise ValueError("mac_address cannot be changed once set")
+        return value

nexora_db-0.1.0/nexora_db/models/user.py

@@ -0,0 +1,14 @@
+from sqlalchemy import Column, Integer, String, DateTime
+from nexora_db.configs.database import base
+from datetime import datetime
+
+
+class User(base):
+    __tablename__ = "users"
+
+    id = Column(Integer, primary_key=True, index=True)
+    email = Column(String, unique=True, index=True, nullable=False)
+    hashed_password = Column(String, nullable=False)
+    role = Column(String, default="viewer")
+    last_seen = Column(DateTime, default=datetime.utcnow())
+

nexora_db-0.1.0/nexora_db/operations/alerts_ops.py

@@ -0,0 +1,66 @@
+from nexora_db.models.alerts_model import Alerts
+from sqlalchemy.exc import SQLAlchemyError
+from nexora_db.operations.devices_ops import DeviceOperations
+from nexora_db.configs.database import get_db
+
+
+class AlertOperations:
+
+    def __init__(self):
+        self.session = next(get_db())
+        self.device_ops = DeviceOperations()
+
+
+    def create_alert(self, alert_message, alert_level, device_id):
+        try:
+            alert = Alerts(
+                alert_message=alert_message,
+                alert_level=alert_level,
+                device_id=device_id,
+            )
+            self.session.add(alert)
+            self.session.commit()
+        except SQLAlchemyError as e:
+            self.session.rollback()
+            print(f"[AlertOPS] DB ERROR: {e}")
+
+
+    def get_all_alerts(self):
+        length_of_alerts = len(self.session.query(Alerts).all())
+        if not length_of_alerts:
+            return False
+        return length_of_alerts
+
+
+    def get_all_alerts_by_type(self, alert_level):
+        alerts_by_type = self.session.query(Alerts).filter(Alerts.alert_level == alert_level).all()
+        if not alerts_by_type:
+            return False
+        return alerts_by_type
+
+
+    def get_alerts_by_device_hostname(self, hostname: int):
+        alerts = self.device_ops.get_device_by_hostname(hostname).alerts_device
+        if not alerts:
+            return False
+        return alerts
+
+
+    def delete_alert(self, alert_id: int):
+        alert = self.session.query(Alerts).filter(Alerts.id == alert_id).first()
+        if not alert:
+            return False
+        self.session.delete(alert)
+        self.session.commit()
+        return True
+
+    def get_all_alerts(self):
+        return self.session.query(Alerts).all()
+
+    def delete_alerts_by_device_hostname(self, hostname: str):
+        device = self.device_ops.get_device_by_hostname(hostname)
+        if not device:
+            return False
+        self.session.query(Alerts).filter(Alerts.device_id == device.id).delete()
+        self.session.commit()
+        return True

nexora_db-0.1.0/nexora_db/operations/devices_ops.py

@@ -0,0 +1,131 @@
+from nexora_db.models.devices_model import Device
+from datetime import datetime
+from nexora_db.configs.database import get_db
+
+class DeviceOperations:
+    def __init__(self):
+        self.session = next(get_db())
+
+    def create_device(self, hostname, device_type, ip_address, mac_address, status="START", interval=None):
+
+        try:
+            device = self.session.query(Device).filter_by(mac_address=mac_address).first()
+
+            if device:
+                if device.status != status:
+                    print(f"[STATUS CHANGE] {device.hostname}: {device.status} -> {status}")
+                    device.status = status
+                    device.last_seen = datetime.utcnow()
+                    self.session.commit()
+                    self.session.refresh(device)
+                    return device
+
+            else:
+                device = Device(
+                    hostname=hostname,
+                    device_type=device_type,
+                    ip_address=ip_address,
+                    mac_address=mac_address,
+                    status=status,
+                    interval=interval,
+                    last_seen=datetime.utcnow()
+                )
+
+                self.session.add(device)
+                self.session.commit()
+                self.session.refresh(device)
+
+            return device
+
+        except Exception as e:
+            self.session.rollback()
+            print("DEVICE OPS ERROR:", e)
+
+        finally:
+            self.session.close()
+
+
+    def get_device_by_hostname(self, hostname):
+        return self.session.query(Device)\
+                .filter(Device.hostname == hostname)\
+                .first()
+
+    def get_device_by_mac_address(self, mac_address):
+        return self.session.query(Device).filter(Device.mac_address == mac_address).first()
+
+    def get_device_by_ip_address(self, ip_address):
+        return self.session.query(Device).filter(Device.ip_address == ip_address).first()
+
+    def get_devices_by_status(self, status):
+        return self.session.query(Device).filter(Device.status == status).all()
+
+    def update_last_seen(self, hostname):
+        device = self.get_device_by_hostname(hostname)
+        if device:
+            device.last_seen = datetime.utcnow()
+            self.session.commit()
+            return device
+        device.last_seen = datetime.utcnow()
+        self.session.commit()
+        return True
+
+
+    def check_device_status(self, hostname: str, status: str):
+        if not hostname or not status:
+            return False
+
+        device = self.get_device_by_hostname(hostname)
+        if not device:
+            return False
+
+        if device.status == status:
+            self.update_last_seen(hostname) ; device.status = status ; self.session.commit() ; self.session.refresh(device)
+            return True
+        else:
+            self.update_last_seen(hostname)
+
+
+    def delete_device(self, device_mac_address: str):
+        device = self.get_device_by_mac_address(device_mac_address)
+        if not device:
+            return False
+
+        self.session.delete(device)
+        self.session.commit()
+        return True
+
+
+    def get_all_devices(self):
+        return self.session.query(Device).all()
+
+    def get_device_by_ip(self, ip_address: str):
+        return self.session.query(Device).filter(Device.ip_address == ip_address).first()
+
+    def get_device_by_mac(self, mac_address: str):
+        return self.session.query(Device).filter(Device.mac_address == mac_address).first()
+
+
+    def update_device(self, mac_address: str, data: dict):
+        if not mac_address or not data:
+            return False
+
+        try:
+            device = self.session.query(Device).filter(Device.mac_address == mac_address).first()
+            if not device:
+                return False
+
+            device.hostname    = data.get("hostname", device.hostname)
+            device.device_type = data.get("device_type", device.device_type)
+            device.ip_address  = data.get("ip_address", device.ip_address)
+
+            self.session.commit()
+            self.session.refresh(device)
+
+            return device
+
+        except Exception as e:
+            self.session.rollback()
+            return str(e)
+
+        finally:
+            self.session.close()

nexora_db-0.1.0/nexora_db/operations/users_service.py

@@ -0,0 +1,53 @@
+from nexora_db.models.user import User
+from nexora_db.schema.validator import UserCreate
+from nexora_db.configs.database import get_db
+
+
+
+class UserOperations:
+
+    def __init__(self):
+        self.db = next(get_db())
+
+    def create_user(self, email: str, hashed_password: str):
+        user = User(email=email, hashed_password=hashed_password)
+        self.db.add(user)
+        self.db.commit()
+        self.db.refresh(user)
+        return user
+
+    def get_user_by_email(self, email: str):
+        return self.db.query(User).filter(User.email == email).first()
+
+    def get_all_users(self):
+        return self.db.query(User).all()
+
+    def delete_user(self, user_id: int):
+        user = self.db.query(User).filter(User.id == user_id).first()
+        if not user:
+            return None
+        self.db.delete(user)
+        self.db.commit()
+        return user
+
+    def update_user(self, user_id: int, data: UserCreate):
+        user = self.db.query(User).filter(User.id == user_id).first()
+        if not user:
+            return None
+        user.email = data.email
+        user.hashed_password = data.password
+        self.db.commit()
+        self.db.refresh(user)
+        return user
+
+
+
+
+class UserUtils:
+
+    @staticmethod
+    def get_username_from_email(email):
+        if "@" in email:
+            return email.split("@")[0]
+        return email
+

nexora_db-0.1.0/nexora_db/schema/validator.py

@@ -0,0 +1,29 @@
+from pydantic import BaseModel, EmailStr, Field
+from typing import Optional
+
+
+class UserCreate(BaseModel):
+    email: EmailStr
+    password: str
+
+
+class UserOut(BaseModel):
+    id: int
+    email: EmailStr
+    role: str
+
+    class Config:
+        orm_mode = True
+
+
+class DeviceCreateForm(BaseModel):
+    hostname: str = Field(..., min_length=2, max_length=50)
+    device_type: str = Field(..., min_length=2, max_length=30)
+    ip_address: str = Field(..., min_length=7, max_length=15)
+    mac_address: str = Field(..., min_length=17, max_length=17)
+
+
+class DeviceUpdateForm(BaseModel):
+    hostname: Optional[str] = Field(None, min_length=2, max_length=50)
+    device_type: Optional[str] = Field(None, min_length=2, max_length=30)
+    ip_address: Optional[str] = Field(None, pattern=r"^\d{1,3}(\.\d{1,3}){3}$")

nexora_db-0.1.0/nexora_db.egg-info/PKG-INFO

@@ -0,0 +1,238 @@
+Metadata-Version: 2.4
+Name: nexora_db
+Version: 0.1.0
+Summary: Shared database layer for Nexora monitoring platform
+Author: Derradji
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: SQLAlchemy==2.0.43
+Requires-Dist: psycopg2-binary==2.9.11
+Requires-Dist: python-dotenv==1.1.1
+Requires-Dist: pydantic==2.11.7
+Requires-Dist: pydantic-settings==2.10.1
+
+# nexora_db
+
+**Shared database layer for the Nexora monitoring platform.**
+
+`nexora_db` is an installable Python package that provides a unified, reusable database interface for all Nexora services. It encapsulates SQLAlchemy models, database configuration, and CRUD operations for users, devices, and alerts — keeping your database logic in one place and out of your application code.
+
+---
+
+## Table of Contents
+
+- [Features](#features)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Configuration](#configuration)
+- [Project Structure](#project-structure)
+- [Usage](#usage)
+  - [Initialize the Database](#1-initialize-the-database)
+  - [Session Usage](#2-session-usage)
+  - [Users](#3-users)
+  - [Pydantic Schemas](#4-pydantic-schemas)
+- [Development](#development)
+---
+
+## Features
+
+- 🗄️ **Centralized database layer** — one package, shared across all Nexora microservices
+- 🔌 **PostgreSQL support** via `psycopg2-binary` and SQLAlchemy 2.0
+- 🧱 **SQLAlchemy ORM models** for Users, Devices, and Alerts
+- ⚙️ **Pydantic-based configuration** with `.env` file support
+- 📦 **Installable as a package** via `pip` or `pyproject.toml`
+
+---
+
+## Requirements
+
+- Python >= 3.9
+- PostgreSQL database instance
+
+---
+
+## Installation
+
+Install directly from source:
+
+```bash
+pip install .
+```
+
+Or install in editable/development mode:
+
+```bash
+pip install -e .
+```
+
+### Dependencies
+
+| Package | Version |
+|---|---|
+| SQLAlchemy | 2.0.43 |
+| psycopg2-binary | 2.9.11 |
+| python-dotenv | 1.1.1 |
+| pydantic | 2.11.7 |
+| pydantic-settings | 2.10.1 |
+
+---
+
+## Configuration
+
+`nexora_db` uses `pydantic-settings` to load configuration from environment variables or a `.env` file.
+
+Create a `.env` file in your project root:
+
+```env
+DATABASE_URL=postgresql://user:password@localhost:5432/nexora_db
+```
+
+> The `DATABASE_URL` environment variable must be set before importing any models or operations.
+
+---
+
+## Project Structure
+
+```
+nexora_db/
+├── __init__.py
+│
+├── configs/
+│   ├── __init__.py
+│   └── database.py          # Engine, session factory, Base declarative
+│
+├── models/
+│   ├── __init__.py
+│   ├── user.py              # User ORM model
+│   ├── devices_model.py     # Device ORM model
+│   └── alerts_model.py      # Alert ORM model
+│
+└── operations/
+    ├── __init__.py
+    ├── users_service.py     # User CRUD operations
+    ├── devices_ops.py       # Device CRUD operations
+    └── alerts_ops.py        # Alert CRUD operations
+```
+
+---
+
+## Usage
+
+### 1. Initialize the Database
+
+Before using any models or operations, call `init_database()` once at application startup with your PostgreSQL connection URL, then call `init_db_tables()` to create all tables.
+
+```python
+from nexora_db.configs.database import init_database, init_db_tables
+
+init_database("postgresql://user:password@localhost:5432/nexora_db")
+init_db_tables()
+```
+
+> `get_db()` and all operations will raise a `RuntimeError` if called before `init_database()`.
+
+---
+
+### 2. Session Usage
+
+`get_db()` is a generator — use it with `next()` or inside a dependency injection framework (e.g. FastAPI):
+
+```python
+from nexora_db.configs.database import get_db
+
+# Manual usage
+db = next(get_db())
+try:
+    # ... perform operations ...
+finally:
+    db.close()
+```
+
+```python
+# FastAPI dependency injection
+from fastapi import Depends
+from nexora_db.configs.database import get_db
+
+@app.get("/example")
+def example_route(db=Depends(get_db)):
+    ...
+```
+
+---
+
+### 3. Users
+
+`UserOperations` wraps all user-related database logic. Instantiate it after `init_database()` has been called.
+
+```python
+from nexora_db.operations.users_service import UserOperations, UserUtils
+from nexora_db.schema.validator import UserCreate
+
+user_ops = UserOperations()
+
+# Create a new user
+user = user_ops.create_user(
+    email="alice@example.com",
+    hashed_password="hashed_secret"
+)
+
+# Fetch by email
+user = user_ops.get_user_by_email("alice@example.com")
+
+# Fetch all users
+users = user_ops.get_all_users()
+
+# Update a user
+updated = user_ops.update_user(user_id=1, data=UserCreate(email="new@example.com", password="new_hash"))
+
+# Delete a user
+deleted = user_ops.delete_user(user_id=1)
+
+# Extract username from email
+username = UserUtils.get_username_from_email("alice@example.com")  # → "alice"
+```
+
+---
+
+### 4. Pydantic Schemas
+
+`nexora_db` ships with Pydantic v2 schemas for input validation and API serialization.
+
+```python
+from nexora_db.schema.validator import UserCreate, UserOut, DeviceCreateForm, DeviceUpdateForm
+
+# Validate user input
+payload = UserCreate(email="alice@example.com", password="secret123")
+
+# Validate device registration
+device_form = DeviceCreateForm(
+    hostname="router-01",
+    device_type="router",
+    ip_address="192.168.1.1",
+    mac_address="AA:BB:CC:DD:EE:FF"
+)
+
+# Partial device update
+update_form = DeviceUpdateForm(ip_address="10.0.0.5")
+```
+
+**Available schemas:**
+
+| Schema | Purpose |
+|---|---|
+| `UserCreate` | Email + password for creating/updating a user |
+| `UserOut` | Serialized user response (id, email, role) |
+| `DeviceCreateForm` | Full device registration payload |
+| `DeviceUpdateForm` | Partial device update (all fields optional) |
+
+---
+
+## Development
+
+Clone the repository and install in editable mode:
+
+```bash
+git clone https://github.com/your-org/nexora_db.git
+cd nexora_db
+pip install -e .
+```

nexora_db-0.1.0/nexora_db.egg-info/SOURCES.txt

@@ -0,0 +1,20 @@
+README.md
+pyproject.toml
+nexora_db/__init__.py
+nexora_db.egg-info/PKG-INFO
+nexora_db.egg-info/SOURCES.txt
+nexora_db.egg-info/dependency_links.txt
+nexora_db.egg-info/requires.txt
+nexora_db.egg-info/top_level.txt
+nexora_db/configs/__init__.py
+nexora_db/configs/database.py
+nexora_db/models/__init__.py
+nexora_db/models/alerts_model.py
+nexora_db/models/devices_model.py
+nexora_db/models/user.py
+nexora_db/operations/__init__.py
+nexora_db/operations/alerts_ops.py
+nexora_db/operations/devices_ops.py
+nexora_db/operations/users_service.py
+nexora_db/schema/__init__.py
+nexora_db/schema/validator.py

nexora_db-0.1.0/nexora_db.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

nexora_db-0.1.0/nexora_db.egg-info/requires.txt

@@ -0,0 +1,5 @@
+SQLAlchemy==2.0.43
+psycopg2-binary==2.9.11
+python-dotenv==1.1.1
+pydantic==2.11.7
+pydantic-settings==2.10.1

nexora_db-0.1.0/nexora_db.egg-info/top_level.txt

@@ -0,0 +1,2 @@
+dist
+nexora_db

nexora_db-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "nexora_db"
+version = "0.1.0"
+description = "Shared database layer for Nexora monitoring platform"
+authors = [
+    {name = "Derradji"}
+]
+readme = "README.md"
+requires-python = ">=3.9"
+
+dependencies = [
+    "SQLAlchemy==2.0.43",
+    "psycopg2-binary==2.9.11",
+    "python-dotenv==1.1.1",
+    "pydantic==2.11.7",
+    "pydantic-settings==2.10.1"
+]
+
+[tool.setuptools.packages.find]
+where = ["."]

nexora_db-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+