SQLPyHelper 0.1.3__py3-none-any.whl → 0.1.5__py3-none-any.whl

sqlpyhelper/__init__.py

@@ -1,2 +1,9 @@
 # Match the version in setup.py
-__version__ = "0.1.3"
+__version__ = "0.1.5"
+
+from sqlpyhelper.db_helper import (  # noqa: F401
+    BackupError,
+    ConnectionError,
+    QueryError,
+    SQLPyHelperError,
+)

sqlpyhelper/automation_utils.py

@@ -0,0 +1,156 @@
+import os
+import shutil
+import subprocess
+from datetime import datetime
+
+import pandas as pd
+
+from sqlpyhelper.db_helper import SQLPyHelper
+
+
+class AutomationUtils:
+    def __init__(self, db=None, **db_kwargs):
+        """
+        Optionally accepts db instance or connection parameters like:
+        db_type, host, user, password, database, port, driver.
+        """
+        self.db = db or SQLPyHelper(**db_kwargs)
+
+    def backup_database(self, target="local", tag="autobackup"):
+        """
+        Backs up the active PostgreSQL database using pg_dump.
+
+        Args:
+            target (str): Backup destination ("local" only for now).
+            tag (str): Custom tag for backup file naming.
+        """
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M")
+        filename = f"{tag}_{timestamp}.sql"
+        backup_dir = "backups"
+        os.makedirs(backup_dir, exist_ok=True)
+        filepath = os.path.join(backup_dir, filename)
+
+        db_name = self.db.database
+        user = self.db.user
+        host = self.db.host or "localhost"
+        port = str(self.db.port or "5432")
+
+        try:
+            if self.db.db_type == "sqlite":
+                filename2 = f"{tag}_{timestamp}.db"
+                sqlite_filepath = os.path.join(backup_dir, filename2)
+                shutil.copy2(self.db.database, sqlite_filepath)
+            else:
+                print(f"📦 Backing up database to {filepath}")
+                subprocess.run(
+                    [
+                        "pg_dump",
+                        "-h",
+                        host,
+                        "-p",
+                        port,
+                        "-U",
+                        user,
+                        db_name,
+                        "-F",
+                        "c",
+                        "-f",
+                        filepath,
+                    ],
+                    check=True,
+                    shell=False,
+                )
+        except subprocess.CalledProcessError as e:
+            print("❌ Backup failed:", e)
+
+    def load_data_from_csv(self, file_path, table_name, if_exists="append"):
+        """
+        Loads a CSV file into the specified database table.
+
+        Args:
+            file_path (str): Path to the CSV file.
+            table_name (str): Destination table name in the database.
+            if_exists (str): 'append' or 'replace'. Default is 'append'.
+        """
+        df = pd.read_csv(file_path)
+
+        if if_exists == "replace":
+            self.db.execute_query(f"DROP TABLE IF EXISTS {table_name}")
+
+        for _, row in df.iterrows():
+            self.db.insert_dynamic(table_name, row.to_dict())
+
+    def detect_missing_periods(self, table, entity_column, date_column):
+        """
+        Flags rows where recurring time periods (e.g. monthly) are missing per entity.
+
+        Args:
+            table (str): Table name to query.
+            entity_column (str): Column representing entity ID.
+            date_column (str): Column representing timestamp/date.
+        """
+        if self.db.db_type == "sqlite":
+            month_expr = f"strftime('%Y-%m', {date_column})"
+        else:
+            month_expr = f"DATE_TRUNC('month', {date_column})"
+        query = f"""
+        SELECT {entity_column}, COUNT(DISTINCT {month_expr}) AS recorded_months
+        FROM {table}
+        GROUP BY {entity_column}
+        HAVING COUNT(DISTINCT {month_expr}) < 12
+        """
+        self.db.execute_query(query)
+        return self.db.fetch_all()
+
+    def aggregate_column(
+        self, table, value_column, group_column=None, time_column=None
+    ):
+        """
+        Computes sum of any value column grouped by entity or month.
+
+        Args:
+            table (str): Table name.
+            value_column (str): Numeric column to aggregate.
+            group_column (str, optional): Entity or category to group by.
+            time_column (str, optional): Timestamp to extract month grouping.
+        """
+        if self.db.db_type == "sqlite":
+            month_expr = f"strftime('%Y-%m', {time_column})"
+        else:
+            month_expr = f"DATE_TRUNC('month', {time_column})"
+
+        if group_column and time_column:
+            query = f"""
+            SELECT {group_column}, {month_expr} AS month, SUM({value_column}) AS total
+            FROM {table}
+            GROUP BY {group_column}, month
+            ORDER BY month
+            """
+        else:
+            query = f"SELECT SUM({value_column}) FROM {table}"
+
+        self.db.execute_query(query)
+        return self.db.fetch_all()
+
+    def detect_outliers(self, table, numeric_column, threshold=2):
+        """
+        Detects statistical outliers based on deviation from mean.
+
+        Args:
+            table (str): Table name.
+            numeric_column (str): Column to analyze.
+            threshold (int): Number of standard deviations from mean to flag as outlier.
+        """
+        query = f"""
+        SELECT *, {numeric_column} AS value FROM {table}
+        """
+        self.db.execute_query(query)
+        data = pd.DataFrame(
+            self.db.fetch_all(),
+            columns=[desc[0] for desc in self.db.cursor.description],
+        )
+
+        mean_val = data["value"].mean()
+        std_val = data["value"].std()
+        outliers = data[abs(data["value"] - mean_val) > threshold * std_val]
+        return outliers.values.tolist()

sqlpyhelper/cli.py

@@ -0,0 +1,199 @@
+import click
+
+from sqlpyhelper.automation_utils import AutomationUtils
+from sqlpyhelper.db_helper import SQLPyHelper
+
+
+@click.group()
+def cli():
+    """SQLPyHelper Command Line Interface"""
+    pass
+
+
+@cli.command()
+@click.option("--db_type", help="Type of database (e.g., sqlite, postgres, mysql)")
+@click.option("--host", help="Database host")
+@click.option("--user", help="Username")
+@click.option("--password", help="Password")
+@click.option("--database", help="Database name or file")
+@click.option("--query", required=True, help="SQL query to run")
+def run_query(db_type, host, user, password, database, query):
+    """Run a single SQL query and print results"""
+    db = SQLPyHelper(
+        db_type=db_type, host=host, user=user, password=password, database=database
+    )
+    results = db.execute_query(query)
+    for row in results:
+        click.echo(row)
+    db.close()
+
+
+@cli.command()
+@click.option("--db_type", required=True)
+@click.option("--host")
+@click.option("--user")
+@click.option("--password")
+@click.option("--database", required=True)
+def interactive_shell(db_type, host, user, password, database):
+    """Launch an interactive SQL shell"""
+    db = SQLPyHelper(
+        db_type=db_type, host=host, user=user, password=password, database=database
+    )
+    click.echo("Interactive shell started. Type your SQL query or 'exit'")
+    while True:
+        query = input("sqlpy> ")
+        if query.lower() in ("exit", "quit"):
+            break
+        try:
+            db.execute_query(query)
+            results = db.fetch_all()
+            for row in results:
+                click.echo(row)
+        except Exception as e:
+            click.echo(f"Error: {e}")
+    db.close()
+
+
+@cli.command()
+@click.option("--target", default="local", help="Backup destination")
+@click.option("--tag", default="autobackup", help="Tag for backup file naming")
+@click.option("--db-type")
+@click.option("--host")
+@click.option("--user")
+@click.option("--password")
+@click.option("--database")
+@click.option("--port")
+def backup(target, tag, db_type, host, user, password, database, port):
+    """Create a timestamped backup of the connected database."""
+    utils = AutomationUtils(
+        db_type=db_type,
+        host=host,
+        user=user,
+        password=password,
+        database=database,
+        port=port,
+    )
+    utils.backup_database(target=target, tag=tag)
+
+
+@cli.command()
+@click.option("--file", required=True, help="Path to CSV file")
+@click.option("--table", required=True, help="Destination table")
+@click.option(
+    "--if-exists",
+    default="append",
+    type=click.Choice(["append", "replace"]),
+    help="What to do if table exists",
+)
+@click.option("--db-type")
+@click.option("--host")
+@click.option("--user")
+@click.option("--password")
+@click.option("--database")
+@click.option("--port")
+def load_data(file, table, if_exists, db_type, host, user, password, database, port):
+    """Load data from CSV into database table."""
+    utils = AutomationUtils(
+        db_type=db_type,
+        host=host,
+        user=user,
+        password=password,
+        database=database,
+        port=port,
+    )
+    utils.load_data_from_csv(file, table, if_exists=if_exists)
+
+
+@cli.command()
+@click.option("--table", required=True)
+@click.option("--entity-column", required=True)
+@click.option("--date-column", required=True)
+@click.option("--db-type")
+@click.option("--host")
+@click.option("--user")
+@click.option("--password")
+@click.option("--database")
+@click.option("--port")
+def detect_missing_periods(
+    table, entity_column, date_column, db_type, host, user, password, database, port
+):
+    """Flag entities with fewer than 12 months of activity."""
+    utils = AutomationUtils(
+        db_type=db_type,
+        host=host,
+        user=user,
+        password=password,
+        database=database,
+        port=port,
+    )
+    results = utils.detect_missing_periods(table, entity_column, date_column)
+    for row in results:
+        click.echo(row)
+
+
+@cli.command()
+@click.option("--table", required=True)
+@click.option("--value-column", required=True)
+@click.option("--group-column")
+@click.option("--time-column")
+@click.option("--db-type")
+@click.option("--host")
+@click.option("--user")
+@click.option("--password")
+@click.option("--database")
+@click.option("--port")
+def aggregate(
+    table,
+    value_column,
+    group_column,
+    time_column,
+    db_type,
+    host,
+    user,
+    password,
+    database,
+    port,
+):
+    """Aggregate numeric column optionally grouped by entity and time."""
+    utils = AutomationUtils(
+        db_type=db_type,
+        host=host,
+        user=user,
+        password=password,
+        database=database,
+        port=port,
+    )
+    results = utils.aggregate_column(table, value_column, group_column, time_column)
+    for row in results:
+        click.echo(row)
+
+
+@cli.command()
+@click.option("--table", required=True)
+@click.option("--numeric-column", required=True)
+@click.option("--threshold", default=2, type=int)
+@click.option("--db-type")
+@click.option("--host")
+@click.option("--user")
+@click.option("--password")
+@click.option("--database")
+@click.option("--port")
+def detect_outliers(
+    table, numeric_column, threshold, db_type, host, user, password, database, port
+):
+    """Flag rows where values deviate statistically from average."""
+    utils = AutomationUtils(
+        db_type=db_type,
+        host=host,
+        user=user,
+        password=password,
+        database=database,
+        port=port,
+    )
+    results = utils.detect_outliers(table, numeric_column, threshold)
+    for row in results:
+        click.echo(row)
+
+
+if __name__ == "__main__":
+    cli()

sqlpyhelper/db_helper.py

@@ -1,53 +1,141 @@
 import csv
-from dotenv import load_dotenv
+import logging
 import os
+import re
+from typing import Any, Literal, Optional
+
+from dotenv import load_dotenv
+
+load_dotenv()
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+    datefmt="%Y-%m-%d %H:%M:%S",
+)
+logger = logging.getLogger("sqlpyhelper")
+
+
+def _validate_identifier(name: str) -> str:
+    """
+    Validate a SQL identifier (table or column name).
+    Allows only alphanumeric characters and underscores.
+    Raises ValueError for anything else, preventing SQL injection via identifiers.
+    """
+    if not re.match(r"^[A-Za-z_][A-Za-z0-9_]*$", name):
+        raise ValueError(
+            f"Invalid SQL identifier: {name!r}. "
+            "Only letters, digits, and underscores are allowed."
+        )
+    return name
+
+
+class SQLPyHelperError(Exception):
+    """Base exception for SQLPyHelper errors."""
+
+
+class ConnectionError(SQLPyHelperError):
+    """Raised when a database connection fails."""
+
 
-load_dotenv()  # Load environment variables from .env file
+class QueryError(SQLPyHelperError):
+    """Raised when a query fails to execute."""
 
 
-def log_query(query):
-    """Logs queries for debugging purposes."""
-    with open("query_log.txt", "a") as f:
-        f.write(query + "\n")
+class BackupError(SQLPyHelperError):
+    """Raised when a backup operation fails."""
 
 
 class SQLPyHelper:
-    def __init__(self):
-        self.db_type = os.getenv("DB_TYPE").lower()
-        self.host = os.getenv("DB_HOST")
-        self.user = os.getenv("DB_USER")
-        self.password = os.getenv("DB_PASSWORD")
-        self.database = os.getenv("DB_NAME")
-        self.driver = os.getenv("DB_DRIVER")
-        self.oracle_sid = os.getenv("ORACLE_SID")
-        self.pool = None
+    def __init__(
+        self,
+        db_type: Optional[str] = None,
+        host: Optional[str] = None,
+        user: Optional[str] = None,
+        password: Optional[str] = None,
+        database: Optional[str] = None,
+        driver: Optional[str] = None,
+        port: Optional[str] = None,
+        oracle_sid: Optional[str] = None,
+    ) -> None:
+
+        # Store original params so reconnect() can replay them
+        self._init_kwargs = {
+            "db_type": db_type,
+            "host": host,
+            "user": user,
+            "password": password,
+            "database": database,
+            "driver": driver,
+            "port": port,
+            "oracle_sid": oracle_sid,
+        }
+
+        self.db_type: str = (db_type or os.getenv("DB_TYPE") or "").lower()
+        self.host: Optional[str] = host or os.getenv("DB_HOST")
+        self.user: Optional[str] = user or os.getenv("DB_USER")
+        self.password: Optional[str] = password or os.getenv("DB_PASSWORD")
+        self.database: Optional[str] = database or os.getenv("DB_NAME")
+        self.driver: Optional[str] = driver or os.getenv("DB_DRIVER")
+        self.port: Optional[str] = port or os.getenv("DB_PORT")
+        self.oracle_sid: Optional[str] = oracle_sid or os.getenv("ORACLE_SID")
+        self.pool: Any = None
+
+        if not self.db_type or not self.database:
+            raise ValueError("Missing required database configuration.")
 
         if self.db_type == "sqlite":
             import sqlite3
+
             self.connection = sqlite3.connect(self.database)
         elif self.db_type == "postgres":
             import psycopg2
-            self.connection = psycopg2.connect(host=self.host, user=self.user,
-                                               password=self.password, dbname=self.database)
+
+            self.connection = psycopg2.connect(
+                host=self.host,
+                user=self.user,
+                password=self.password,
+                dbname=self.database,
+            )
         elif self.db_type == "mysql":
             import mysql.connector
-            self.connection = mysql.connector.connect(host=self.host, user=self.user,
-                                                      password=self.password, database=self.database)
+
+            self.connection = mysql.connector.connect(
+                host=self.host,
+                user=self.user,
+                password=self.password,
+                database=self.database,
+            )  # type: ignore[assignment]
         elif self.db_type == "sqlserver":
             import pyodbc
-            self.connection = pyodbc.connect(f"DRIVER={self.driver};SERVER={self.host};DATABASE={self.database};"
-                                             f"UID={self.user};PWD={self.password}")
+
+            self.connection = pyodbc.connect(
+                f"DRIVER={self.driver};SERVER={self.host};DATABASE={self.database};"
+                f"UID={self.user};PWD={self.password}"
+            )
         elif self.db_type == "oracle":
-            import cx_Oracle
-            oracle_port = os.getenv("ORACLE_DB_PORT", "1521")  # Default to 1521 if not set
-            dsn = cx_Oracle.makedsn(self.host, oracle_port, self.oracle_sid)
-            self.connection = cx_Oracle.connect(self.user, self.password, dsn)
+            import oracledb
+
+            oracle_port = os.getenv("ORACLE_DB_PORT", 1521)
+            dsn = oracledb.makedsn(
+                self.host, oracle_port, sid=self.oracle_sid  # type: ignore[arg-type]
+            )
+            self.connection = oracledb.connect(
+                user=self.user, password=self.password, dsn=dsn
+            )  # type: ignore[assignment]
         else:
             raise ValueError("Unsupported database type")
 
         self.cursor = self.connection.cursor()
 
-    def execute_query(self, query, params=None):
+    def __enter__(self) -> "SQLPyHelper":
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> Literal[False]:
+        self.close()
+        return False
+
+    def execute_query(self, query: str, params: Optional[tuple] = None) -> None:
         """Executes a query with optional parameters"""
         try:
             if params:
@@ -56,154 +144,240 @@ class SQLPyHelper:
                 self.cursor.execute(query)
             self.connection.commit()
         except Exception as e:
-            if "server has gone away" in str(e):  # Example check for MySQL lost connection
+            if "server has gone away" in str(
+                e
+            ):  # Example check for MySQL lost connection
                 self.reconnect()
-                self.cursor.execute(query, params)
+                self.cursor.execute(query, params)  # type: ignore[arg-type]
                 self.connection.commit()
             else:
-                print(f"Error executing query: {e}")
+                raise QueryError(f"Query failed: {e}") from e
 
-    def fetch_one(self):
+    def fetch_one(self) -> Optional[tuple]:
         """Fetches a single row"""
         try:
             return self.cursor.fetchone()
         except Exception as e:
-            print(f"Error fetching row: {e}")
-            return None
+            raise QueryError(f"Failed to fetch row: {e}") from e
 
-    def fetch_all(self):
+    def fetch_all(self) -> list[tuple]:
         """Fetches all rows from the last executed query"""
         try:
             return self.cursor.fetchall()
         except Exception as e:
-            print(f"Error fetching rows: {e}")
-            return None
+            raise QueryError(f"Failed to fetch rows: {e}") from e
 
-    def fetch_by_param(self, table_name, column_name, value):
+    def fetch_by_param(
+        self, table_name: str, column_name: str, value: Any
+    ) -> list[tuple]:
+        """Fetches rows from a table where a column matches the given value."""
         try:
-            query = f"SELECT * FROM {table_name} WHERE {column_name} = %s"
+            table_name = _validate_identifier(table_name)
+            column_name = _validate_identifier(column_name)
+            placeholder = "?" if self.db_type == "sqlite" else "%s"
+            query = f"SELECT * FROM {table_name} WHERE {column_name} = {placeholder}"
             self.cursor.execute(query, (value,))
             return self.cursor.fetchall()
         except Exception as e:
-            print(f"Error fetching row(s): {e}")
-            return None
+            raise QueryError(f"Failed to fetch by param: {e}") from e
 
-    def close(self):
-        """Closes the connection"""
+    def close(self) -> None:
+        """Closes the cursor and database connection."""
         try:
             self.cursor.close()
             self.connection.close()
         except Exception as e:
-            print(f"Error closing connection: {e}")
-            return None
+            raise ConnectionError(f"Failed to close connection: {e}") from e
 
-    def create_table(self, table_name, columns):
+    def create_table(self, table_name: str, columns: dict[str, str]) -> None:
         """
         Creates a table dynamically using a dictionary format.
         Example:
         columns = {'id': 'INTEGER PRIMARY KEY', 'name': 'TEXT', 'age': 'INTEGER'}
         """
         try:
-            column_defs = ", ".join(f"{col} {dtype}" for col, dtype in columns.items())
-            query = f"CREATE TABLE {table_name} ({column_defs})"
+            table_name = _validate_identifier(table_name)
+            validated_cols = {
+                _validate_identifier(col): dtype for col, dtype in columns.items()
+            }
+            columns_def = ", ".join(
+                [f"{col} {dtype}" for col, dtype in validated_cols.items()]
+            )
+            query = f"CREATE TABLE IF NOT EXISTS {table_name} ({columns_def})"
             self.execute_query(query)
         except Exception as e:
-            print(f"Error creating table: {e}")
-            return None
+            raise QueryError(f"Failed to create table: {e}") from e
 
-    def insert_bulk(self, table_name, data):
+    def insert_bulk(self, table_name: str, data: list[dict[str, Any]]) -> None:
         """
         Inserts multiple rows at once.
         Example:
         data = [{'id': 1, 'name': 'Alice'}, {'id': 2, 'name': 'Bob'}]
         """
         try:
-            columns = ", ".join(data[0].keys())  # Extract column names
-            placeholders = ", ".join(["%s" for _ in data[0].keys()])  # Generate placeholders
+            table_name = _validate_identifier(table_name)
+            col_names = [_validate_identifier(col) for col in data[0].keys()]
+            columns = ", ".join(col_names)
+            placeholder = "?" if self.db_type == "sqlite" else "%s"
+            placeholders = ", ".join([placeholder] * len(data[0]))
             query = f"INSERT INTO {table_name} ({columns}) VALUES ({placeholders})"
             values = [tuple(row.values()) for row in data]
             self.cursor.executemany(query, values)
             self.connection.commit()
 
         except Exception as e:
-            print(f"Error inserting bulk rows: {e}")
-            return None
+            raise QueryError(f"Failed to insert bulk rows: {e}") from e
 
-    def backup_table(self, table_name, backup_file):
+    def backup_table(self, table_name: str, backup_file: str) -> None:
         """
         Exports table data into a CSV file.
         Example:
         backup_table('users', 'users_backup.csv')
         """
         try:
+            table_name = _validate_identifier(table_name)
             query = f"SELECT * FROM {table_name}"
             self.execute_query(query)
             rows = self.fetch_all()
 
             with open(backup_file, mode="w", newline="") as file:
                 writer = csv.writer(file)
-                writer.writerow([desc[0] for desc in self.cursor.description])  # Column headers
+                writer.writerow(
+                    [desc[0] for desc in self.cursor.description]
+                )  # Column headers
                 writer.writerows(rows)
         except Exception as e:
-            print(f"Error backing up table: {e}")
-            return None
+            raise BackupError(f"Failed to backup table: {e}") from e
 
-    def setup_connection_pool(self, min_conn=1, max_conn=5, pool_size=5):
+    def setup_connection_pool(
+        self, min_conn: int = 1, max_conn: int = 5, pool_size: int = 5
+    ) -> None:
         """Sets up connection pooling based on the database type"""
         try:
             if self.db_type == "postgres":
                 from psycopg2 import pool
-                self.pool = pool.SimpleConnectionPool(min_conn, max_conn,
-                                                      host=self.host, user=self.user,
-                                                      password=self.password, dbname=self.database)
+
+                self.pool = pool.SimpleConnectionPool(
+                    min_conn,
+                    max_conn,
+                    host=self.host,
+                    user=self.user,
+                    password=self.password,
+                    dbname=self.database,
+                )
 
             elif self.db_type == "mysql":
                 import mysql.connector.pooling
-                self.pool = mysql.connector.pooling.MySQLConnectionPool(pool_name="mypool",
-                                                                        pool_size=pool_size, host=self.host,
-                                                                        user=self.user, password=self.password,
-                                                                        database=self.database)
+
+                self.pool = mysql.connector.pooling.MySQLConnectionPool(
+                    pool_name="mypool",
+                    pool_size=pool_size,
+                    host=self.host,
+                    user=self.user,
+                    password=self.password,
+                    database=self.database,
+                )
 
             elif self.db_type == "sqlserver":
                 import pyodbc
+
                 self.pool = [
-                    pyodbc.connect(f"DRIVER={self.driver};SERVER={self.host};DATABASE={self.database};"
-                                   f"UID={self.user};PWD={self.password};ConnectionPooling=Yes")
+                    pyodbc.connect(
+                        f"DRIVER={self.driver};SERVER={self.host};DATABASE={self.database};"
+                        f"UID={self.user};PWD={self.password};ConnectionPooling=Yes"
+                    )
                     for _ in range(pool_size)
                 ]
 
             elif self.db_type == "oracle":
-                import cx_Oracle
-                oracle_port = os.getenv("ORACLE_DB_PORT", "1521")  # Default Oracle port
-                dsn = cx_Oracle.makedsn(self.host, oracle_port, self.oracle_sid)
-                self.pool = cx_Oracle.SessionPool(user=self.user, password=self.password, dsn=dsn,
-                                                  min=min_conn, max=max_conn, increment=1, threaded=True)
+                import oracledb
+
+                oracle_port = os.getenv("ORACLE_DB_PORT", 1521)
+                dsn = oracledb.makedsn(self.host, oracle_port, sid=self.oracle_sid)  # type: ignore[arg-type]
+                self.pool = oracledb.create_pool(
+                    user=self.user,
+                    password=self.password,
+                    dsn=dsn,
+                    min=min_conn,
+                    max=max_conn,
+                    increment=1,
+                )
 
             else:
                 raise ValueError(f"Connection pooling not supported for {self.db_type}")
         except Exception as e:
-            print(f"⚠️ Error setting up connection pool: {e}")
-            self.pool = None  # Prevent broken pool usage
+            raise ConnectionError(f"Failed to set up connection pool: {e}") from e
 
-    def get_connection_from_pool(self):
+    def get_connection_from_pool(self) -> Any:
         """Fetches a connection from the pool."""
         return self.pool.get_connection()
 
-    def return_connection_to_pool(self):
+    def return_connection_to_pool(self, connection: Any = None) -> None:
         """Returns a connection back to the pool."""
-        self.connection.close()
+        conn = connection or self.connection
+        if self.pool is None:
+            raise RuntimeError(
+                "No connection pool initialised. Call setup_connection_pool() first."
+            )
+
+        if self.db_type == "postgres":
+            self.pool.putconn(conn)
+        elif self.db_type == "mysql":
+            conn.close()
+        elif self.db_type == "oracle":
+            self.pool.release(conn)
+        else:
+            conn.close()
 
-    def reconnect(self):
+    def reconnect(self) -> None:
         """Reconnects to the database if connection is lost"""
         try:
-            self.connection.close()  # Close existing connection
-            self.__init__()  # Reinitialize the connection
+            self.connection.close()
+            self.__init__(**self._init_kwargs)  # type: ignore[misc]
             print("Database reconnected successfully.")
         except Exception as e:
-            print(f"Error during reconnection: {e}")
+            raise ConnectionError(f"Reconnection failed: {e}") from e
 
-    def begin_transaction(self):
-        self.execute_query("START TRANSACTION")
+    def begin_transaction(self) -> None:
+        """Begin an explicit transaction. Works across all supported databases."""
+        try:
+            if self.db_type == "sqlite":
+                self.execute_query("BEGIN")
+            elif self.db_type in ("postgres", "mysql"):
+                self.execute_query("START TRANSACTION")
+            elif self.db_type == "sqlserver":
+                self.execute_query("BEGIN TRANSACTION")
+            elif self.db_type == "oracle":
+                pass  # Oracle starts transactions implicitly on first DML statement
+            logger.info("Transaction started on %s database", self.db_type)
+        except Exception as e:
+            raise QueryError(f"Failed to begin transaction: {e}") from e
+
+    def commit_transaction(self) -> None:
+        """Commit the current transaction."""
+        try:
+            self.connection.commit()
+            logger.info("Transaction committed on %s database", self.db_type)
+        except Exception as e:
+            raise QueryError(f"Failed to commit transaction: {e}") from e
+
+    def rollback_transaction(self) -> None:
+        """Roll back the current transaction."""
+        try:
+            self.connection.rollback()
+            logger.info("Transaction rolled back on %s database", self.db_type)
+        except Exception as e:
+            raise QueryError(f"Failed to rollback transaction: {e}") from e
+
+    def insert_dynamic(self, table: str, data: dict[str, Any]) -> None:
+        """
+        Dynamically constructs and executes an INSERT query with database-specific placeholders.
+        """
+        table = _validate_identifier(table)
+        columns = ", ".join(_validate_identifier(col) for col in data.keys())
+        placeholders_style = "?" if self.db_type == "sqlite" else "%s"
+        placeholders = ", ".join([placeholders_style] * len(data))
+        values = tuple(data.values())
 
-    def rollback_transaction(self):
-        self.execute_query("ROLLBACK")
+        sql = f"INSERT INTO {table} ({columns}) VALUES ({placeholders})"
+        self.execute_query(sql, values)

{sqlpyhelper-0.1.3.dist-info → sqlpyhelper-0.1.5.dist-info}/METADATA

@@ -1,11 +1,21 @@
 Metadata-Version: 2.4
 Name: SQLPyHelper
-Version: 0.1.3
+Version: 0.1.5
 Summary: A simple SQL database helper package for Python.
+Home-page: https://github.com/adebayopeter/sqlpyhelper
 Author: Adebayo Olaonipekun
 Author-email: pekunmi@live.com
+Project-URL: Source, https://github.com/adebayopeter/sqlpyhelper
+Project-URL: Bug Tracker, https://github.com/adebayopeter/sqlpyhelper/issues
+Project-URL: Changelog, https://github.com/adebayopeter/sqlpyhelper/blob/main/CHANGELOG.md
+Keywords: database,sql,sqlite,postgresql,mysql,sqlserver,oracle,db,query,helper
 Classifier: Programming Language :: Python :: 3
-Classifier: Development Status :: 5 - Production/Stable
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Topic :: Database :: Database Engines/Servers
 Classifier: Operating System :: OS Independent
@@ -13,34 +23,54 @@ Classifier: License :: OSI Approved :: MIT License
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: psycopg2
-Requires-Dist: mysql-connector-python
-Requires-Dist: pyodbc
-Requires-Dist: cx_Oracle
 Requires-Dist: python-dotenv
-Provides-Extra: mysql
-Requires-Dist: mysql-connector-python; extra == "mysql"
+Requires-Dist: click
 Provides-Extra: postgres
 Requires-Dist: psycopg2; extra == "postgres"
-Provides-Extra: oracle
-Requires-Dist: cx_Oracle; extra == "oracle"
+Provides-Extra: mysql
+Requires-Dist: mysql-connector-python; extra == "mysql"
 Provides-Extra: sqlserver
 Requires-Dist: pyodbc; extra == "sqlserver"
-Provides-Extra: sqlite
+Provides-Extra: oracle
+Requires-Dist: oracledb; extra == "oracle"
+Provides-Extra: all
+Requires-Dist: psycopg2; extra == "all"
+Requires-Dist: mysql-connector-python; extra == "all"
+Requires-Dist: pyodbc; extra == "all"
+Requires-Dist: oracledb; extra == "all"
 Dynamic: author
 Dynamic: author-email
 Dynamic: classifier
 Dynamic: description
 Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
 Dynamic: license-file
+Dynamic: project-url
 Dynamic: provides-extra
 Dynamic: requires-dist
 Dynamic: requires-python
 Dynamic: summary
 
-# 📌 SQLPyHelper v.0.1.3 🚀
+# SQLPyHelper
+
+[![PyPI version](https://img.shields.io/pypi/v/sqlpyhelper.svg)](https://pypi.org/project/sqlpyhelper/)
+[![PyPI downloads](https://img.shields.io/pypi/dm/sqlpyhelper.svg)](https://pypi.org/project/sqlpyhelper/)
+[![Python versions](https://img.shields.io/pypi/pyversions/sqlpyhelper.svg)](https://pypi.org/project/sqlpyhelper/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://github.com/adebayopeter/sqlpyhelper/blob/main/LICENSE)
+[![GitHub stars](https://img.shields.io/github/stars/adebayopeter/sqlpyhelper?style=social)](https://github.com/adebayopeter/sqlpyhelper)
+
+SQLPyHelper is a lightweight Python library that gives you a single, consistent API across **SQLite, PostgreSQL, MySQL, SQL Server, and Oracle** — without the overhead of an ORM.
 
-A Python library for simplified database interactions across **SQLite, PostgreSQL, MySQL, SQL Server, and Oracle**. SQLPyHelper provides an intuitive API for handling queries, connection pooling, transactions, logging, and backups efficiently.
+If you need to run queries, manage transactions, pool connections, or back up tables across multiple database types without learning SQLAlchemy's abstraction layer or wiring up five different drivers manually, SQLPyHelper handles that boilerplate for you.
+
+```python
+# Works identically across all five supported databases
+with SQLPyHelper(db_type="postgres", host="localhost", user="user", 
+                 password="pass", database="mydb") as db:
+    db.execute_query("INSERT INTO orders (item) VALUES (%s)", ("Laptop",))
+    results = db.fetch_all()
+```
 
 ## 📖 Table of Contents
 - [🚀 Features](#-features)
@@ -59,21 +89,32 @@ A Python library for simplified database interactions across **SQLite, PostgreSQ
 
 ---
 
-## 🚀 Features in v0.1.3
-✅ Unified connection pooling for multiple databases. 
-✅ Automatic reconnection for lost connections. 
-✅ Transaction support (BEGIN, ROLLBACK, COMMIT). 
-✅ Secure parameterized queries to prevent SQL injection. 
-✅ Bulk insertion & dynamic table creation. 
-✅ Logging & error handling for better debugging. 
-✅ CSV export & database backups.
+## 🚀 Features in v0.1.4
+- Unified connection pooling for multiple databases. 
+- Automatic reconnection for lost connections. 
+- Transaction support (BEGIN, ROLLBACK, COMMIT). 
+- Secure parameterized queries to prevent SQL injection. 
+- Bulk insertion & dynamic table creation. 
+- Logging & error handling for better debugging. 
+- CSV export & database backups.
 
 ---
 ## 📦 Installation
-#### Install via PyPI:
+
+Install the base package (includes SQLite support out of the box):
 ```sh
 pip install sqlpyhelper
 ```
+
+Install with your database driver:
+```sh
+pip install sqlpyhelper[postgres]    # PostgreSQL
+pip install sqlpyhelper[mysql]       # MySQL
+pip install sqlpyhelper[sqlserver]   # SQL Server
+pip install sqlpyhelper[oracle]      # Oracle
+pip install sqlpyhelper[all]         # All databases
+```
+
 📌 Package on PyPI: [SQLPyHelper on PyPI](https://pypi.org/project/SQLPyHelper/)
 
 For local development:
@@ -186,7 +227,9 @@ db.return_connection_to_pool(conn)
 | `return_connection_to_pool(conn)` | Returns connection back to pool. |
 | `begin_transaction()` | Begins an **explicit transaction**. |
 | `rollback_transaction()` | Rolls back **uncommitted transactions**. |
+| `commit_transaction()` | Commits the current transaction. |
 | `close()` | Closes the database connection safely. |
+| `__enter__` / `__exit__()` | Use as a context manager — connection closes automatically. |
 
 ---
 ## 🌍 Contributing

sqlpyhelper-0.1.5.dist-info/RECORD

@@ -0,0 +1,11 @@
+sqlpyhelper/__init__.py,sha256=nkFTrXkOtL4V7KVPw_bdjl5afqWroUG81WRVdCm0-NQ,183
+sqlpyhelper/automation_utils.py,sha256=pC6pH6bJ-k8iPVeHJ4gUiwEe822dasmKg53ya9bMxyE,5381
+sqlpyhelper/cli.py,sha256=yj0kWJu3oh_JLnmi0L7a5ing2_0x4CQGOKSOhZLAtoY,5646
+sqlpyhelper/db_helper.py,sha256=4DbdBVo86zz1d0hNHtSc4b3Tks7bJGTMTyabsydQyOE,14191
+sqlpyhelper/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sqlpyhelper-0.1.5.dist-info/licenses/LICENSE,sha256=9XzXxZ_8mWFM9-2TlqyE3L69zvRf4VPY_xIzSj5iU-g,1076
+sqlpyhelper-0.1.5.dist-info/METADATA,sha256=s_qc18w4ulfBx46s9azplWDBZsFUSvqnTVDw_32EnkE,9555
+sqlpyhelper-0.1.5.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+sqlpyhelper-0.1.5.dist-info/entry_points.txt,sha256=uAzSqwkAbbJqQUKHlPNwOebTJVA0FqkOvn2CRP6xSz8,52
+sqlpyhelper-0.1.5.dist-info/top_level.txt,sha256=FrLqTmqTGDa8jHnnf2ZVkYO-gFvLXX9QonpUCE6wKGs,12
+sqlpyhelper-0.1.5.dist-info/RECORD,,

{sqlpyhelper-0.1.3.dist-info → sqlpyhelper-0.1.5.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.9.0)
+Generator: setuptools (82.0.1)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

sqlpyhelper-0.1.5.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+sqlpyhelper = sqlpyhelper.cli:cli

sqlpyhelper-0.1.3.dist-info/RECORD

@@ -1,7 +0,0 @@
-sqlpyhelper/__init__.py,sha256=v4m1w8m6t3Ypvteu4Ukto47uZG_pAHHkBFcKjWrk__Q,54
-sqlpyhelper/db_helper.py,sha256=hRgwzPM5Ze_xKwgphQLJovQmkVpVhKffmAa1C7Lje9g,8447
-sqlpyhelper-0.1.3.dist-info/licenses/LICENSE,sha256=9XzXxZ_8mWFM9-2TlqyE3L69zvRf4VPY_xIzSj5iU-g,1076
-sqlpyhelper-0.1.3.dist-info/METADATA,sha256=zYkK-eNm3BBm4T0bStWMSWdIR44pyWQgJOjUHh6lnQ8,7253
-sqlpyhelper-0.1.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-sqlpyhelper-0.1.3.dist-info/top_level.txt,sha256=FrLqTmqTGDa8jHnnf2ZVkYO-gFvLXX9QonpUCE6wKGs,12
-sqlpyhelper-0.1.3.dist-info/RECORD,,