SQLPyHelper 0.1.4__py3-none-any.whl → 0.1.6__py3-none-any.whl

sqlpyhelper/__init__.py

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

sqlpyhelper/automation_utils.py

@@ -1,9 +1,11 @@
-import pandas as pd
-from sqlpyhelper.db_helper import SQLPyHelper
-import subprocess
-from datetime import datetime
 import os
 import shutil
+import subprocess
+from datetime import datetime
+
+import pandas as pd
+
+from sqlpyhelper.db_helper import SQLPyHelper
 
 
 class AutomationUtils:
@@ -43,12 +45,17 @@ class AutomationUtils:
                 subprocess.run(
                     [
                         "pg_dump",
-                        "-h", host,
-                        "-p", port,
-                        "-U", user,
+                        "-h",
+                        host,
+                        "-p",
+                        port,
+                        "-U",
+                        user,
                         db_name,
-                        "-F", "c",
-                        "-f", filepath,
+                        "-F",
+                        "c",
+                        "-f",
+                        filepath,
                     ],
                     check=True,
                     shell=False,
@@ -82,7 +89,7 @@ class AutomationUtils:
             entity_column (str): Column representing entity ID.
             date_column (str): Column representing timestamp/date.
         """
-        if self.db.db_type == 'sqlite':
+        if self.db.db_type == "sqlite":
             month_expr = f"strftime('%Y-%m', {date_column})"
         else:
             month_expr = f"DATE_TRUNC('month', {date_column})"
@@ -95,7 +102,9 @@ class AutomationUtils:
         self.db.execute_query(query)
         return self.db.fetch_all()
 
-    def aggregate_column(self, table, value_column, group_column=None, time_column=None):
+    def aggregate_column(
+        self, table, value_column, group_column=None, time_column=None
+    ):
         """
         Computes sum of any value column grouped by entity or month.
 
@@ -105,7 +114,7 @@ class AutomationUtils:
             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':
+        if self.db.db_type == "sqlite":
             month_expr = f"strftime('%Y-%m', {time_column})"
         else:
             month_expr = f"DATE_TRUNC('month', {time_column})"
@@ -133,11 +142,13 @@ class AutomationUtils:
             threshold (int): Number of standard deviations from mean to flag as outlier.
         """
         query = f"""
-            SELECT *, {numeric_column} 
-            AS value FROM {table}
+        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])
+        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()

sqlpyhelper/cli.py

@@ -1,6 +1,7 @@
 import click
-from sqlpyhelper.db_helper import SQLPyHelper
+
 from sqlpyhelper.automation_utils import AutomationUtils
+from sqlpyhelper.db_helper import SQLPyHelper
 
 
 @click.group()
@@ -10,15 +11,17 @@ def cli():
 
 
 @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')
+@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)
+    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)
@@ -26,14 +29,16 @@ def run_query(db_type, host, user, password, database, query):
 
 
 @cli.command()
-@click.option('--db_type', required=True)
-@click.option('--host')
-@click.option('--user')
-@click.option('--password')
-@click.option('--database', required=True)
+@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)
+    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> ")
@@ -50,14 +55,14 @@ def interactive_shell(db_type, host, user, password, database):
 
 
 @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')
+@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(
@@ -66,77 +71,125 @@ def backup(target, tag, db_type, host, user, password, database, port):
         user=user,
         password=password,
         database=database,
-        port=port
+        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')
+@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 = 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):
+@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)
+    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):
+@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)
+    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):
+@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)
+    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)

sqlpyhelper/db_helper.py

@@ -1,9 +1,19 @@
 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()  # Load environment variables from .env file
+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:
@@ -12,7 +22,7 @@ def _validate_identifier(name: str) -> str:
     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):
+    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."
@@ -37,8 +47,17 @@ class BackupError(SQLPyHelperError):
 
 
 class SQLPyHelper:
-    def __init__(self, db_type=None, host=None, user=None, password=None,
-                 database=None, driver=None, port=None, oracle_sid=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 = {
@@ -52,52 +71,71 @@ class SQLPyHelper:
             "oracle_sid": oracle_sid,
         }
 
-        self.db_type = db_type or os.getenv("DB_TYPE").lower()
-        self.host = host or os.getenv("DB_HOST")
-        self.user = user or os.getenv("DB_USER")
-        self.password = password or os.getenv("DB_PASSWORD")
-        self.database = database or os.getenv("DB_NAME")
-        self.driver = driver or os.getenv("DB_DRIVER")
-        self.port = port or os.getenv("DB_PORT")
-        self.oracle_sid = oracle_sid or os.getenv("ORACLE_SID")
-        self.pool = None
+        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 __enter__(self):
+    def __enter__(self) -> "SQLPyHelper":
         return self
 
-    def __exit__(self, exc_type, exc_val, exc_tb):
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> Literal[False]:
         self.close()
         return False
 
-    def execute_query(self, query, params=None):
+    def execute_query(self, query: str, params: Optional[tuple] = None) -> None:
         """Executes a query with optional parameters"""
         try:
             if params:
@@ -106,28 +144,33 @@ 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:
                 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:
             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:
             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:
             table_name = _validate_identifier(table_name)
             column_name = _validate_identifier(column_name)
@@ -138,15 +181,15 @@ class SQLPyHelper:
         except Exception as e:
             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:
             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:
@@ -154,14 +197,18 @@ class SQLPyHelper:
         """
         try:
             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()])
+            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:
             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:
@@ -181,7 +228,7 @@ class SQLPyHelper:
         except Exception as e:
             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:
@@ -195,56 +242,83 @@ class SQLPyHelper:
 
             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:
             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:
             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, connection=None) -> None:
+    def return_connection_to_pool(self, connection: Any = None) -> None:
         """Returns a connection back to the pool."""
         conn = connection or self.connection
         if self.pool is None:
-            raise RuntimeError("No connection pool initialised. Call setup_connection_pool() first.")
+            raise RuntimeError(
+                "No connection pool initialised. Call setup_connection_pool() first."
+            )
 
         if self.db_type == "postgres":
             self.pool.putconn(conn)
@@ -255,22 +329,47 @@ class SQLPyHelper:
         else:
             conn.close()
 
-    def reconnect(self):
+    def reconnect(self) -> None:
         """Reconnects to the database if connection is lost"""
         try:
             self.connection.close()
-            self.__init__(**self._init_kwargs)
+            self.__init__(**self._init_kwargs)  # type: ignore[misc]
             print("Database reconnected successfully.")
         except Exception as 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 rollback_transaction(self):
-        self.execute_query("ROLLBACK")
+    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, data: dict):
+    def insert_dynamic(self, table: str, data: dict[str, Any]) -> None:
         """
         Dynamically constructs and executes an INSERT query with database-specific placeholders.
         """

{sqlpyhelper-0.1.4.dist-info → sqlpyhelper-0.1.6.dist-info}/METADATA

@@ -1,10 +1,11 @@
 Metadata-Version: 2.4
 Name: SQLPyHelper
-Version: 0.1.4
+Version: 0.1.6
 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: Documentation, https://sqlpyhelper.readthedocs.io/en/latest/
 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
@@ -32,12 +33,12 @@ Requires-Dist: mysql-connector-python; extra == "mysql"
 Provides-Extra: sqlserver
 Requires-Dist: pyodbc; extra == "sqlserver"
 Provides-Extra: oracle
-Requires-Dist: cx_Oracle; 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: cx_Oracle; extra == "all"
+Requires-Dist: oracledb; extra == "all"
 Dynamic: author
 Dynamic: author-email
 Dynamic: classifier
@@ -59,10 +60,19 @@ Dynamic: summary
 [![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)
+[![Documentation](https://readthedocs.org/projects/sqlpyhelper/badge/?version=latest)](https://sqlpyhelper.readthedocs.io/en/latest/)
 
-# 📌 SQLPyHelper v.0.1.4 🚀
+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)
@@ -81,7 +91,7 @@ A Python library for simplified database interactions across **SQLite, PostgreSQ
 
 ---
 
-## 🚀 Features in v0.1.3
+## 🚀 Features in v0.1.4
 - Unified connection pooling for multiple databases. 
 - Automatic reconnection for lost connections. 
 - Transaction support (BEGIN, ROLLBACK, COMMIT). 
@@ -92,10 +102,21 @@ A Python library for simplified database interactions across **SQLite, PostgreSQ
 
 ---
 ## 📦 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:
@@ -208,7 +229,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.6.dist-info/RECORD

@@ -0,0 +1,11 @@
+sqlpyhelper/__init__.py,sha256=7hQ4FRKUaUU_TiGuU1cldnvTmG4S2riZP43SqxA4fUI,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.6.dist-info/licenses/LICENSE,sha256=9XzXxZ_8mWFM9-2TlqyE3L69zvRf4VPY_xIzSj5iU-g,1076
+sqlpyhelper-0.1.6.dist-info/METADATA,sha256=JA0zdZYH5pceNjom3LQQPuUhfGe9kH_6RjXBrKiOi4A,9763
+sqlpyhelper-0.1.6.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+sqlpyhelper-0.1.6.dist-info/entry_points.txt,sha256=uAzSqwkAbbJqQUKHlPNwOebTJVA0FqkOvn2CRP6xSz8,52
+sqlpyhelper-0.1.6.dist-info/top_level.txt,sha256=FrLqTmqTGDa8jHnnf2ZVkYO-gFvLXX9QonpUCE6wKGs,12
+sqlpyhelper-0.1.6.dist-info/RECORD,,

sqlpyhelper-0.1.4.dist-info/RECORD

@@ -1,11 +0,0 @@
-sqlpyhelper/__init__.py,sha256=8hopTneD8N4lddcHwD9y-PJHbqElOYw5_aw-HZSMvbo,169
-sqlpyhelper/automation_utils.py,sha256=z-9yTdMuOMu1TVUwJ9Q6D3wTrCRh2K6DhCldJ_7MLdI,5227
-sqlpyhelper/cli.py,sha256=fJHztOrzufPnQ6agFe7OgepSCNcPT0RcpZw8gg8BgWI,5322
-sqlpyhelper/db_helper.py,sha256=Dtpuxa2s67-kitgNQLbAa5JF-AFoN5bC9mLfQ1o4V48,11514
-sqlpyhelper/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-sqlpyhelper-0.1.4.dist-info/licenses/LICENSE,sha256=9XzXxZ_8mWFM9-2TlqyE3L69zvRf4VPY_xIzSj5iU-g,1076
-sqlpyhelper-0.1.4.dist-info/METADATA,sha256=_gPYGlQmVm6dJS-1z-TYfvWIAKOS4PEsNVzVONUMxnw,8601
-sqlpyhelper-0.1.4.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-sqlpyhelper-0.1.4.dist-info/entry_points.txt,sha256=uAzSqwkAbbJqQUKHlPNwOebTJVA0FqkOvn2CRP6xSz8,52
-sqlpyhelper-0.1.4.dist-info/top_level.txt,sha256=FrLqTmqTGDa8jHnnf2ZVkYO-gFvLXX9QonpUCE6wKGs,12
-sqlpyhelper-0.1.4.dist-info/RECORD,,