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

sqlpyhelper/__init__.py

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

sqlpyhelper/automation_utils.py

@@ -0,0 +1,145 @@
+import pandas as pd
+from sqlpyhelper.db_helper import SQLPyHelper
+import subprocess
+from datetime import datetime
+import os
+import shutil
+
+
+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,146 @@
+import click
+from sqlpyhelper.db_helper import SQLPyHelper
+from sqlpyhelper.automation_utils import AutomationUtils
+
+
+@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,27 +1,70 @@
 import csv
 from dotenv import load_dotenv
 import os
+import re
 
 load_dotenv()  # Load environment variables from .env file
 
 
-def log_query(query):
-    """Logs queries for debugging purposes."""
-    with open("query_log.txt", "a") as f:
-        f.write(query + "\n")
+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."""
+
+
+class QueryError(SQLPyHelperError):
+    """Raised when a query fails to execute."""
+
+
+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")
+    def __init__(self, db_type=None, host=None, user=None, password=None,
+                 database=None, driver=None, port=None, oracle_sid=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 = 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
 
+        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)
@@ -47,6 +90,13 @@ class SQLPyHelper:
 
         self.cursor = self.connection.cursor()
 
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.close()
+        return False
+
     def execute_query(self, query, params=None):
         """Executes a query with optional parameters"""
         try:
@@ -56,24 +106,45 @@ class SQLPyHelper:
                 self.cursor.execute(query)
             self.connection.commit()
         except Exception as e:
-            print(f"Error executing query: {e}")
+            if "server has gone away" in str(e):  # Example check for MySQL lost connection
+                self.reconnect()
+                self.cursor.execute(query, params)
+                self.connection.commit()
+            else:
+                raise QueryError(f"Query failed: {e}") from e
 
     def fetch_one(self):
-        return self.cursor.fetchone()
+        """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):
         """Fetches all rows from the last executed query"""
-        return self.cursor.fetchall()
+        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):
-        query = f"SELECT * FROM {table_name} WHERE {column_name} = %s"
-        self.cursor.execute(query, (value,))
-        return self.cursor.fetchall()  # Fetch matching rows
+        try:
+            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:
+            raise QueryError(f"Failed to fetch by param: {e}") from e
 
     def close(self):
         """Closes the connection"""
-        self.cursor.close()
-        self.connection.close()
+        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):
         """
@@ -81,9 +152,14 @@ class SQLPyHelper:
         Example:
         columns = {'id': 'INTEGER PRIMARY KEY', 'name': 'TEXT', 'age': 'INTEGER'}
         """
-        column_defs = ", ".join(f"{col} {dtype}" for col, dtype in columns.items())
-        query = f"CREATE TABLE {table_name} ({column_defs})"
-        self.execute_query(query)
+        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()])
+            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):
         """
@@ -91,12 +167,19 @@ class SQLPyHelper:
         Example:
         data = [{'id': 1, 'name': 'Alice'}, {'id': 2, 'name': 'Bob'}]
         """
-        columns = ", ".join(data[0].keys())  # Extract column names
-        placeholders = ", ".join(["%s" for _ in data[0].keys()])  # Generate placeholders
-        query = f"INSERT INTO {table_name} ({columns}) VALUES ({placeholders})"
-        values = [tuple(row.values()) for row in data]  # Convert dictionaries to tuples
-        self.cursor.executemany(query, values)
-        self.connection.commit()
+        try:
+            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:
+            raise QueryError(f"Failed to insert bulk rows: {e}") from e
 
     def backup_table(self, table_name, backup_file):
         """
@@ -104,32 +187,98 @@ class SQLPyHelper:
         Example:
         backup_table('users', 'users_backup.csv')
         """
-        query = f"SELECT * FROM {table_name}"
-        self.execute_query(query)
-        rows = self.fetch_all()
+        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.writerows(rows)
+            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.writerows(rows)
+        except Exception as e:
+            raise BackupError(f"Failed to backup table: {e}") from e
 
-    def setup_postgres_pool(self, min_conn=1, max_conn=5):
-        """
-        Creates a connection pool for PostgreSQL.
-        Example:
-        setup_postgres_pool(min_conn=2, max_conn=10)
-        """
-        from psycopg2 import pool
-        self.pool = pool.SimpleConnectionPool(min_conn, max_conn,
-                                              host=self.host,
-                                              user=self.user,
-                                              password=self.password,
-                                              dbname=self.database)
+    def setup_connection_pool(self, min_conn=1, max_conn=5, pool_size=5):
+        """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)
+
+            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)
+
+            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")
+                    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)
+
+            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):
         """Fetches a connection from the pool."""
-        return self.pool.getconn()
+        return self.pool.get_connection()
 
-    def return_connection_to_pool(self, conn):
+    def return_connection_to_pool(self, connection=None) -> None:
         """Returns a connection back to the pool."""
-        self.pool.putconn(conn)
+        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):
+        """Reconnects to the database if connection is lost"""
+        try:
+            self.connection.close()
+            self.__init__(**self._init_kwargs)
+            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 rollback_transaction(self):
+        self.execute_query("ROLLBACK")
+
+    def insert_dynamic(self, table, data: dict):
+        """
+        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())
+
+        sql = f"INSERT INTO {table} ({columns}) VALUES ({placeholders})"
+        self.execute_query(sql, values)

sqlpyhelper-0.1.4.dist-info/METADATA

@@ -0,0 +1,238 @@
+Metadata-Version: 2.4
+Name: SQLPyHelper
+Version: 0.1.4
+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: 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
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: python-dotenv
+Requires-Dist: click
+Provides-Extra: postgres
+Requires-Dist: psycopg2; extra == "postgres"
+Provides-Extra: mysql
+Requires-Dist: mysql-connector-python; extra == "mysql"
+Provides-Extra: sqlserver
+Requires-Dist: pyodbc; extra == "sqlserver"
+Provides-Extra: oracle
+Requires-Dist: cx_Oracle; 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"
+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
+
+[![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 v.0.1.4 🚀
+
+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.
+
+## 📖 Table of Contents
+- [🚀 Features](#-features)
+- [📦 Installation](#-installation)
+- [⚙️ Setup Using `.env`](#️-setup-using-env)
+- [🛠 Usage Examples](#-usage-examples)
+  - [SQLite Example](#sqlite-example)
+  - [PostgreSQL Example](#postgresql-example)
+  - [MySQL Example](#mysql-example)
+  - [SQL Server Example](#sql-server-example)
+  - [Oracle Example](#oracle-example)
+- [📂 Project Structure](#-project-structure)
+- [📌 Available Methods in SQLPyHelper](#-available-methods-in-sqlpyhelper)
+- [🌍 Contributing](#-contributing)
+- [☕ Support the Project](#-support-the-project)
+
+---
+
+## 🚀 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.
+
+---
+## 📦 Installation
+#### Install via PyPI:
+```sh
+pip install sqlpyhelper
+```
+📌 Package on PyPI: [SQLPyHelper on PyPI](https://pypi.org/project/SQLPyHelper/)
+
+For local development:
+```sh
+git clone https://github.com/adebayopeter/sqlpyhelper.git
+cd sqlpyhelper
+pip install -r requirements.txt
+```
+
+---
+
+## ⚙️ Setup Using `.env`
+Create a `.env` file in your project root to manage database configurations securely by renaming `.env_example`.
+
+```sh
+# .env_example (Rename to .env)
+DB_TYPE=postgres
+DB_HOST=localhost
+DB_USER=your_user
+DB_PASSWORD=your_secure_password
+DB_NAME=database_name
+DB_DRIVER={ODBC Driver 17 for SQL Server}
+ORACLE_SID=XE
+ORACLE_DB_PORT=1521
+```
+### Loading `.env` in Code
+```pycon
+from dotenv import load_dotenv
+import os
+
+load_dotenv()
+db_type = os.getenv("DB_TYPE")
+host = os.getenv("DB_HOST")
+user = os.getenv("DB_USER")
+password = os.getenv("DB_PASSWORD")
+database = os.getenv("DB_NAME")
+```
+---
+## 🛠 Usage Examples
+### Initialize SQLPyHelper
+```pycon
+from sqlpyhelper.db_helper import SQLPyHelper
+db = SQLPyHelper()  # Auto-detects database type based on `DB_TYPE`
+```
+### SQLite Example
+```pycon
+db.execute_query("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)")
+db.execute_query("INSERT INTO users (name) VALUES (?)", ("Alice",))
+print(db.fetch_all()) # Expected Output: [(1, 'Alice')]
+db.close()
+```
+### PostgreSQL Example
+```pycon
+db.execute_query("CREATE TABLE customers (id SERIAL PRIMARY KEY, name TEXT)")
+db.execute_query("INSERT INTO customers (name) VALUES (%s)", ("Bob",))
+db.begin_transaction()
+db.execute_query("DELETE FROM customers WHERE name=%s", ("Bob",))
+db.rollback_transaction()  # Undo delete
+```
+### MySQL Example
+```pycon 
+db.execute_query("CREATE TABLE users (id INT PRIMARY KEY, name VARCHAR(100))")
+db.execute_query("INSERT INTO users (id, name) VALUES (%s, %s)", (1, "Alice"))
+print(db.fetch_by_param("users", "id", 1))  # Expected Output: [(1, 'Alice')]
+db.close()
+```
+### SQL Server Example
+```pycon
+db.execute_query("CREATE TABLE orders (order_id INT PRIMARY KEY, item NVARCHAR(100))")
+db.insert_bulk("orders", [{"order_id": 1, "item": "Laptop"}, {"order_id": 2, "item": "Mouse"}])
+db.backup_table("orders", "orders_backup.csv")  # Export data to CSV
+```
+### Oracle Example
+```pycon
+db.execute_query("CREATE TABLE employees (id NUMBER PRIMARY KEY, name VARCHAR2(100))")
+db.execute_query("INSERT INTO employees (id, name) VALUES (:1, :2)", (1, "Charlie"))
+db.setup_connection_pool(min_conn=2, max_conn=10)  # Enable pooling for better performance
+conn = db.get_connection_from_pool()
+db.return_connection_to_pool(conn)
+```
+
+## 📂 Project Structure
+```
+📦 SQLPyHelper/
+├─ sqlpyhelper/
+│  ├─ __init__.py
+│  └─ db_helper.py
+├─ tests/
+│  └─ test_sqlpyhelper.py
+├─ .env_example
+├─ .gitignore
+├─ setup.py
+├─ README.md
+└─ requirements.txt
+```
+---
+## 📌 Available Methods in SQLPyHelper
+
+| Method | Description |
+|--------|-------------|
+| `execute_query(query, params=None)` | Executes a SQL query with optional parameters. |
+| `fetch_one()` | Retrieves a **single row** from query results. |
+| `fetch_all()` | Retrieves **all rows** from query results. |
+| `fetch_by_param(table, column, value)` | Fetches **rows dynamically** based on a given parameter. |
+| `create_table(table_name, columns_dict)` | Creates a table dynamically with a dictionary format. |
+| `insert_bulk(table, data_list)` | Inserts **multiple rows at once** efficiently. |
+| `backup_table(table, backup_file.csv)` | Exports table data to **CSV format**. |
+| `setup_connection_pool()` | Initializes **database connection pooling**. |
+| `get_connection_from_pool()` | Fetches a connection from the pool. |
+| `return_connection_to_pool(conn)` | Returns connection back to pool. |
+| `begin_transaction()` | Begins an **explicit transaction**. |
+| `rollback_transaction()` | Rolls back **uncommitted transactions**. |
+| `close()` | Closes the database connection safely. |
+
+---
+## 🌍 Contributing
+We welcome contributions from the **open-source community**! Follow these steps to contribute:
+
+1. Fork the repo: [SQLPyHelper GitHub Repository](https://github.com/adebayopeter/sqlpyhelper)
+2. Clone your fork:
+   ```sh
+   git clone https://github.com/adebayopeter/sqlpyhelper.git
+   ```
+3. Create a new branch:
+   ```sh
+   git checkout -b feature-new-functionality
+   ```
+4. Make changes, commit, and push:
+   ```sh
+   git commit -m "Added new feature"
+   git push origin feature-new-functionality
+   ```
+5. Submit a Pull Request!
+
+---
+## ☕ Support the Project
+
+If you find SQLPyHelper useful, consider buying me a coffee to support continued development! 
+Donate Here: [PayPal](https://paypal.me/adebayopeter?country.x=GB&locale.x=en_GB)
+---

sqlpyhelper-0.1.4.dist-info/RECORD

@@ -0,0 +1,11 @@
+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,,

{sqlpyhelper-0.1.2.dist-info → sqlpyhelper-0.1.4.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.4.dist-info/entry_points.txt

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

sqlpyhelper-0.1.2.dist-info/METADATA

@@ -1,211 +0,0 @@
-Metadata-Version: 2.4
-Name: SQLPyHelper
-Version: 0.1.2
-Summary: A simple SQL database helper package for Python.
-Author: Adebayo Olaonipekun
-Author-email: pekunmi@live.com
-Classifier: Programming Language :: Python :: 3
-Classifier: Development Status :: 5 - Production/Stable
-Classifier: Intended Audience :: Developers
-Classifier: Topic :: Database :: Database Engines/Servers
-Classifier: Operating System :: OS Independent
-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"
-Provides-Extra: postgres
-Requires-Dist: psycopg2; extra == "postgres"
-Provides-Extra: oracle
-Requires-Dist: cx_Oracle; extra == "oracle"
-Provides-Extra: sqlserver
-Requires-Dist: pyodbc; extra == "sqlserver"
-Provides-Extra: sqlite
-Dynamic: author
-Dynamic: author-email
-Dynamic: classifier
-Dynamic: description
-Dynamic: description-content-type
-Dynamic: license-file
-Dynamic: provides-extra
-Dynamic: requires-dist
-Dynamic: requires-python
-Dynamic: summary
-
-# 📌 SQLPyHelper
-
-A Python library for simplified database interactions across **SQLite, PostgreSQL, MySQL, SQL Server, and Oracle**. This open-source package provides an intuitive API for handling database operations efficiently.
-
-## 📖 Table of Contents
-- [🚀 Features](#-features)
-- [📦 Installation](#-installation)
-- [⚙️ Setup Using `.env`](#️-setup-using-env)
-- [🛠 Usage Examples](#-usage-examples)
-  - [SQLite Example](#sqlite-example)
-  - [PostgreSQL Example](#postgresql-example)
-  - [MySQL Example](#mysql-example)
-  - [SQL Server Example](#sql-server-example)
-  - [Oracle Example](#oracle-example)
-- [📂 Project Structure](#-project-structure)
-- [🌍 Contributing](#-contributing)
-- [☕ Support the Project](#-support-the-project)
-
----
-
-## 🚀 Features
-- **Unified Interface** for multiple databases  
-- **Connection pooling support** for PostgreSQL  
-- **Bulk insertion & dynamic table creation**  
-- **Automated logging & query execution**  
-- **CSV export & backup functionality**  
-
----
-## 📦 Installation
-#### Install via PyPI:
-```sh
-pip install sqlpyhelper
-```
-📌 Package on PyPI: [SQLPyHelper on PyPI](https://pypi.org/project/SQLPyHelper/)
-
-Or, if working from source:
-```sh
-git clone https://github.com/adebayopeter/sqlpyhelper.git
-cd sqlpyhelper
-pip install -r requirements.txt
-```
-
----
-
-## ⚙️ Setup Using `.env`
-Create a `.env` file in your project root to manage database configurations securely by renaming `.env_example`.
-
-```sh
-# .env_example (Rename to .env)
-DB_TYPE=postgres
-DB_HOST=localhost
-DB_USER=your_user
-DB_PASSWORD=your_secure_password
-DB_NAME=database_name
-DB_DRIVER={ODBC Driver 17 for SQL Server}
-ORACLE_SID=XE
-ORACLE_DB_PORT=1521
-```
-### Loading `.env` in Code
-```pycon
-from dotenv import load_dotenv
-import os
-
-load_dotenv()
-db_type = os.getenv("DB_TYPE")
-host = os.getenv("DB_HOST")
-user = os.getenv("DB_USER")
-password = os.getenv("DB_PASSWORD")
-database = os.getenv("DB_NAME")
-```
----
-## 🛠 Usage Examples
-### SQLite Example
-```pycon
-from sqlpyhelper.db_helper import SQLPyHelper
-
-db = SQLPyHelper()
-db.execute_query("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)")
-db.execute_query("INSERT INTO users (name) VALUES (?)", ("Alice",))
-db.execute_query("SELECT * FROM users")
-print(db.fetch_all())
-db.close()
-```
-### PostgreSQL Example
-```pycon
-db = SQLPyHelper()
-db.execute_query("CREATE TABLE IF NOT EXISTS employees (id SERIAL PRIMARY KEY, name VARCHAR(100))")
-db.execute_query("INSERT INTO employees (name) VALUES (%s)", ("Charlie",))
-db.execute_query("SELECT * FROM employees")
-print(db.fetch_all())
-db.close()
-```
-### MySQL Example
-```pycon
-db = SQLPyHelper()
-db.execute_query("CREATE TABLE IF NOT EXISTS customers (id INT PRIMARY KEY AUTO_INCREMENT, name VARCHAR(100))")
-db.execute_query("INSERT INTO customers (name) VALUES (%s)", ("David",))
-db.execute_query("SELECT * FROM customers")
-print(db.fetch_all())
-db.close()
-```
-```pycon
-db = SQLPyHelper()
-
-# Fetch rows where customer_id = 3
-customers = db.fetch_by_param("customers", "id", 3)
-print(customers)
-
-db.close()
-```
-
-### SQL Server Example
-```pycon
-db = SQLPyHelper()
-db.execute_query("CREATE TABLE IF NOT EXISTS orders (id INT PRIMARY KEY, product VARCHAR(100))")
-db.execute_query("INSERT INTO orders (id, product) VALUES (?, ?)", (1, "Laptop"))
-db.execute_query("SELECT * FROM orders")
-print(db.fetch_all())
-db.close()
-```
-### Oracle Example
-```pycon
-db = SQLPyHelper()
-db.execute_query("CREATE TABLE employees (id NUMBER PRIMARY KEY, name VARCHAR2(100))")
-db.execute_query("INSERT INTO employees (id, name) VALUES (:1, :2)", (1, "Emily"))
-db.execute_query("SELECT * FROM employees")
-print(db.fetch_all())
-db.close()
-```
-
-## 📂 Project Structure
-```
-📦 SQLPyHelper/
-├─ sqlpyhelper/
-│  ├─ __init__.py
-│  └─ db_helper.py
-├─ tests/
-│  └─ test_sqlpyhelper.py
-├─ .env_example
-├─ .gitignore
-├─ setup.py
-├─ README.md
-└─ requirements.txt
-```
-
----
-## 🌍 Contributing
-We welcome contributions from the **open-source community**! Follow these steps to contribute:
-
-1. Fork the repo: [SQLPyHelper GitHub Repository](https://github.com/adebayopeter/sqlpyhelper)
-2. Clone your fork:
-   ```sh
-   git clone https://github.com/adebayopeter/sqlpyhelper.git
-   ```
-3. Create a new branch:
-   ```sh
-   git checkout -b feature-new-functionality
-   ```
-4. Make changes, commit, and push:
-   ```sh
-   git commit -m "Added new feature"
-   git push origin feature-new-functionality
-   ```
-5. Submit a Pull Request!
-
----
-## ☕ Support the Project
-
-If you find SQLPyHelper useful, consider buying me a coffee to support continued development! 
-Donate Here: [PayPal](https://paypal.me/adebayopeter?country.x=GB&locale.x=en_GB)
----

sqlpyhelper-0.1.2.dist-info/RECORD

@@ -1,7 +0,0 @@
-sqlpyhelper/__init__.py,sha256=kJA4mgypZmLd3SnwwTNkVwB0yIJ8PKP4h9cjOCIPfTA,54
-sqlpyhelper/db_helper.py,sha256=TT93q3f1EVjkgUSXA4iXCy9Uw5gdGuRbqH-Wl-8OjeI,5269
-sqlpyhelper-0.1.2.dist-info/licenses/LICENSE,sha256=9XzXxZ_8mWFM9-2TlqyE3L69zvRf4VPY_xIzSj5iU-g,1076
-sqlpyhelper-0.1.2.dist-info/METADATA,sha256=ATC92p-IcBVUFEBHKXqqMBkYC524FsdQpxDVBmhQ3JI,5954
-sqlpyhelper-0.1.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-sqlpyhelper-0.1.2.dist-info/top_level.txt,sha256=FrLqTmqTGDa8jHnnf2ZVkYO-gFvLXX9QonpUCE6wKGs,12
-sqlpyhelper-0.1.2.dist-info/RECORD,,