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

sqlpyhelper/__init__.py

@@ -1,9 +1,15 @@
 # Match the version in setup.py
-__version__ = "0.1.6"
+__version__ = "0.1.8"
 
+from sqlpyhelper.async_helper import (  # noqa: F401
+    AsyncConnectionError,
+    AsyncQueryError,
+    AsyncSQLPyHelper,
+)
 from sqlpyhelper.db_helper import (  # noqa: F401
     BackupError,
     ConnectionError,
     QueryError,
     SQLPyHelperError,
 )
+from sqlpyhelper.migration import MigrationError  # noqa: F401

sqlpyhelper/async_helper.py

@@ -0,0 +1,599 @@
+"""
+sqlpyhelper.async_helper
+~~~~~~~~~~~~~~~~~~~~~~~~
+Async-native database helper supporting SQLite, PostgreSQL, MySQL,
+SQL Server, and Oracle.
+
+Uses async-native drivers:
+- SQLite:     aiosqlite
+- PostgreSQL: asyncpg
+- MySQL:      aiomysql
+- SQL Server: aioodbc
+- Oracle:     python-oracledb (async mode)
+
+Example usage::
+
+    import asyncio
+    from sqlpyhelper.async_helper import AsyncSQLPyHelper
+
+    async def main():
+        async with AsyncSQLPyHelper(db_type="sqlite", database="my.db") as db:
+            await db.execute("CREATE TABLE IF NOT EXISTS users (id INTEGER, name TEXT)")
+            await db.execute("INSERT INTO users VALUES ($1, $2)", 1, "Alice")
+            rows = await db.fetch_all("SELECT * FROM users")
+            print(rows)
+
+    asyncio.run(main())
+"""
+
+import logging
+import os
+from typing import Any, Optional
+
+from dotenv import load_dotenv
+
+load_dotenv()
+
+logger = logging.getLogger("sqlpyhelper.async")
+
+
+class AsyncConnectionError(Exception):
+    """Raised when an async database connection fails."""
+
+
+class AsyncQueryError(Exception):
+    """Raised when an async query fails."""
+
+
+class AsyncSQLPyHelper:
+    """
+    Async-native database helper with a unified API across
+    SQLite, PostgreSQL, MySQL, SQL Server, and Oracle.
+
+    Use as an async context manager::
+
+        async with AsyncSQLPyHelper(db_type="postgres", ...) as db:
+            rows = await db.fetch_all("SELECT * FROM users")
+
+    Or manage the connection lifecycle manually::
+
+        db = AsyncSQLPyHelper(db_type="sqlite", database="my.db")
+        await db.connect()
+        try:
+            rows = await db.fetch_all("SELECT * FROM users")
+        finally:
+            await db.close()
+    """
+
+    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:
+        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._connection: Any = None
+        self._pool: Any = None
+
+        if not self.db_type or not self.database:
+            raise ValueError("Missing required database configuration.")
+
+        if self.db_type not in ("sqlite", "postgres", "mysql", "sqlserver", "oracle"):
+            raise ValueError(f"Unsupported database type: {self.db_type!r}")
+
+    # -----------------------------------------------------------------------
+    # Connection lifecycle
+    # -----------------------------------------------------------------------
+
+    async def connect(self) -> None:
+        """Open the database connection."""
+        try:
+            if self.db_type == "sqlite":
+                import aiosqlite
+
+                self._connection = await aiosqlite.connect(self.database or "")  # type: ignore[arg-type]
+                self._connection.row_factory = aiosqlite.Row
+                logger.info("Connected to SQLite database: %s", self.database)
+
+            elif self.db_type == "postgres":
+                import asyncpg
+
+                self._connection = await asyncpg.connect(
+                    host=self.host,
+                    port=int(self.port or 5432),
+                    user=self.user,
+                    password=self.password,
+                    database=self.database,
+                )
+                logger.info("Connected to PostgreSQL database: %s", self.database)
+
+            elif self.db_type == "mysql":
+                import aiomysql
+
+                self._connection = await aiomysql.connect(
+                    host=self.host or "localhost",
+                    port=int(self.port or 3306),
+                    user=self.user,
+                    password=self.password or "",
+                    db=self.database,
+                    autocommit=False,
+                )
+                logger.info("Connected to MySQL database: %s", self.database)
+
+            elif self.db_type == "sqlserver":
+                import aioodbc
+
+                dsn = (
+                    f"DRIVER={self.driver};"
+                    f"SERVER={self.host};"
+                    f"DATABASE={self.database};"
+                    f"UID={self.user};"
+                    f"PWD={self.password}"
+                )
+                self._connection = await aioodbc.connect(dsn=dsn)
+                logger.info("Connected to SQL Server database: %s", self.database)
+
+            elif self.db_type == "oracle":
+                import oracledb
+
+                oracle_port = int(os.getenv("ORACLE_DB_PORT", "1521"))
+                dsn = oracledb.makedsn(
+                    self.host, oracle_port, sid=self.oracle_sid  # type: ignore[arg-type]
+                )
+                self._connection = await oracledb.connect_async(
+                    user=self.user, password=self.password, dsn=dsn
+                )
+                logger.info("Connected to Oracle database: %s", self.oracle_sid)
+
+        except Exception as e:
+            raise AsyncConnectionError(
+                f"Failed to connect to {self.db_type}: {e}"
+            ) from e
+
+    async def close(self) -> None:
+        """Close the database connection."""
+        try:
+            if self._connection is not None:
+                await self._connection.close()
+                self._connection = None
+                logger.info("Closed %s connection", self.db_type)
+        except Exception as e:
+            raise AsyncConnectionError(f"Failed to close connection: {e}") from e
+
+    async def __aenter__(self) -> "AsyncSQLPyHelper":
+        await self.connect()
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> bool:
+        await self.close()
+        return False
+
+    # -----------------------------------------------------------------------
+    # Internal helpers
+    # -----------------------------------------------------------------------
+
+    def _check_connection(self) -> None:
+        if self._connection is None:
+            raise AsyncConnectionError(
+                "No active connection. Call connect() or use async with."
+            )
+
+    def _adapt_query(self, query: str, args: tuple) -> tuple[str, tuple]:
+        """
+        Adapt a query and its arguments for the active database driver.
+
+        asyncpg uses $1, $2, ... positional placeholders.
+        aiosqlite and aiomysql use ? and %s respectively.
+        Callers should write queries using $1, $2, ... style and this
+        method will translate as needed.
+        """
+        if not args:
+            return query, args
+
+        if self.db_type == "postgres":
+            # asyncpg natively uses $1, $2 — pass through unchanged
+            return query, args
+
+        elif self.db_type == "sqlite":
+            # Replace $1, $2 with ?
+            import re
+
+            adapted = re.sub(r"\$\d+", "?", query)
+            return adapted, args
+
+        elif self.db_type in ("mysql", "sqlserver"):
+            # Replace $1, $2 with %s
+            import re
+
+            adapted = re.sub(r"\$\d+", "%s", query)
+            return adapted, args
+
+        elif self.db_type == "oracle":
+            # Replace $1, $2 with :1, :2
+            import re
+
+            def replace_placeholder(m: Any) -> str:
+                return f":{m.group(0)[1:]}"
+
+            adapted = re.sub(r"\$(\d+)", replace_placeholder, query)
+            return adapted, args
+
+        return query, args
+
+    # -----------------------------------------------------------------------
+    # Query execution
+    # -----------------------------------------------------------------------
+
+    async def execute(self, query: str, *args: Any) -> None:
+        """
+        Execute a SQL statement (INSERT, UPDATE, DELETE, DDL).
+
+        Use $1, $2, ... for parameterised values::
+
+            await db.execute(
+                "INSERT INTO users (id, name) VALUES ($1, $2)",
+                1, "Alice"
+            )
+
+        Args:
+            query: SQL query string using $1, $2 placeholders.
+            *args: Query parameters.
+
+        Raises:
+            AsyncQueryError: If the query fails.
+        """
+        self._check_connection()
+        adapted_query, adapted_args = self._adapt_query(query, args)
+        try:
+            if self.db_type == "postgres":
+                await self._connection.execute(adapted_query, *adapted_args)
+
+            elif self.db_type == "sqlite":
+                await self._connection.execute(adapted_query, adapted_args)
+                await self._connection.commit()
+
+            elif self.db_type in ("mysql", "sqlserver"):
+                async with self._connection.cursor() as cursor:
+                    await cursor.execute(adapted_query, adapted_args)
+                await self._connection.commit()
+
+            elif self.db_type == "oracle":
+                cursor = self._connection.cursor()
+                await cursor.execute(adapted_query, adapted_args)
+                await self._connection.commit()
+
+            logger.debug("Executed: %s", query)
+
+        except Exception as e:
+            raise AsyncQueryError(f"Query failed: {e}") from e
+
+    async def fetch_one(self, query: str, *args: Any) -> Optional[Any]:
+        """
+        Execute a SELECT query and return a single row, or None.
+
+        Args:
+            query: SQL query string using $1, $2 placeholders.
+            *args: Query parameters.
+
+        Returns:
+            A single row, or None if no rows matched.
+
+        Raises:
+            AsyncQueryError: If the query fails.
+        """
+        self._check_connection()
+        adapted_query, adapted_args = self._adapt_query(query, args)
+        try:
+            if self.db_type == "postgres":
+                return await self._connection.fetchrow(adapted_query, *adapted_args)
+
+            elif self.db_type == "sqlite":
+                async with self._connection.execute(
+                    adapted_query, adapted_args
+                ) as cursor:
+                    return await cursor.fetchone()
+
+            elif self.db_type in ("mysql", "sqlserver"):
+                async with self._connection.cursor() as cursor:
+                    await cursor.execute(adapted_query, adapted_args)
+                    return await cursor.fetchone()
+
+            elif self.db_type == "oracle":
+                cursor = self._connection.cursor()
+                await cursor.execute(adapted_query, adapted_args)
+                return await cursor.fetchone()
+
+            return None
+
+        except Exception as e:
+            raise AsyncQueryError(f"fetch_one failed: {e}") from e
+
+    async def fetch_all(self, query: str, *args: Any) -> list[Any]:
+        """
+        Execute a SELECT query and return all rows.
+
+        Args:
+            query: SQL query string using $1, $2 placeholders.
+            *args: Query parameters.
+
+        Returns:
+            A list of rows (empty list if no rows matched).
+
+        Raises:
+            AsyncQueryError: If the query fails.
+        """
+        self._check_connection()
+        adapted_query, adapted_args = self._adapt_query(query, args)
+        try:
+            if self.db_type == "postgres":
+                return await self._connection.fetch(adapted_query, *adapted_args)
+
+            elif self.db_type == "sqlite":
+                async with self._connection.execute(
+                    adapted_query, adapted_args
+                ) as cursor:
+                    return await cursor.fetchall()
+
+            elif self.db_type in ("mysql", "sqlserver"):
+                async with self._connection.cursor() as cursor:
+                    await cursor.execute(adapted_query, adapted_args)
+                    return await cursor.fetchall()
+
+            elif self.db_type == "oracle":
+                cursor = self._connection.cursor()
+                await cursor.execute(adapted_query, adapted_args)
+                return await cursor.fetchall()
+
+            return []
+
+        except Exception as e:
+            raise AsyncQueryError(f"fetch_all failed: {e}") from e
+
+    async def fetch_val(self, query: str, *args: Any) -> Optional[Any]:
+        """
+        Execute a SELECT query and return a single scalar value.
+
+        Useful for COUNT, SUM, or any query returning one value::
+
+            count = await db.fetch_val("SELECT COUNT(*) FROM users")
+
+        Args:
+            query: SQL query string using $1, $2 placeholders.
+            *args: Query parameters.
+
+        Returns:
+            A single scalar value, or None.
+
+        Raises:
+            AsyncQueryError: If the query fails.
+        """
+        self._check_connection()
+        adapted_query, adapted_args = self._adapt_query(query, args)
+        try:
+            if self.db_type == "postgres":
+                return await self._connection.fetchval(adapted_query, *adapted_args)
+
+            elif self.db_type == "sqlite":
+                async with self._connection.execute(
+                    adapted_query, adapted_args
+                ) as cursor:
+                    row = await cursor.fetchone()
+                    return row[0] if row else None
+
+            elif self.db_type in ("mysql", "sqlserver"):
+                async with self._connection.cursor() as cursor:
+                    await cursor.execute(adapted_query, adapted_args)
+                    row = await cursor.fetchone()
+                    return row[0] if row else None
+
+            elif self.db_type == "oracle":
+                cursor = self._connection.cursor()
+                await cursor.execute(adapted_query, adapted_args)
+                row = await cursor.fetchone()
+                return row[0] if row else None
+
+            return None
+
+        except Exception as e:
+            raise AsyncQueryError(f"fetch_val failed: {e}") from e
+
+    async def execute_many(self, query: str, args_list: list[tuple]) -> None:
+        """
+        Execute a SQL statement multiple times with different parameters.
+        Efficient for bulk inserts::
+
+            await db.execute_many(
+                "INSERT INTO users (id, name) VALUES ($1, $2)",
+                [(1, "Alice"), (2, "Bob"), (3, "Charlie")]
+            )
+
+        Args:
+            query:     SQL query string using $1, $2 placeholders.
+            args_list: List of parameter tuples.
+
+        Raises:
+            AsyncQueryError: If the operation fails.
+        """
+        self._check_connection()
+        if not args_list:
+            return
+        try:
+            if self.db_type == "postgres":
+                await self._connection.executemany(query, args_list)
+
+            elif self.db_type == "sqlite":
+                import re
+
+                adapted = re.sub(r"\$\d+", "?", query)
+                await self._connection.executemany(adapted, args_list)
+                await self._connection.commit()
+
+            elif self.db_type in ("mysql", "sqlserver"):
+                import re
+
+                adapted = re.sub(r"\$\d+", "%s", query)
+                async with self._connection.cursor() as cursor:
+                    await cursor.executemany(adapted, args_list)
+                await self._connection.commit()
+
+            elif self.db_type == "oracle":
+                import re
+
+                def replace_placeholder(m: Any) -> str:
+                    return f":{m.group(1)}"
+
+                adapted = re.sub(r"\$(\d+)", replace_placeholder, query)
+                cursor = self._connection.cursor()
+                await cursor.executemany(adapted, args_list)
+                await self._connection.commit()
+
+            logger.debug("execute_many: %d rows", len(args_list))
+
+        except Exception as e:
+            raise AsyncQueryError(f"execute_many failed: {e}") from e
+
+    # -----------------------------------------------------------------------
+    # Transaction management
+    # -----------------------------------------------------------------------
+
+    async def begin_transaction(self) -> None:
+        """
+        Begin an explicit transaction.
+
+        For PostgreSQL, use the transaction() context manager instead,
+        which is the idiomatic asyncpg approach.
+
+        Raises:
+            AsyncQueryError: If the transaction cannot be started.
+        """
+        self._check_connection()
+        try:
+            if self.db_type == "sqlite":
+                await self._connection.execute("BEGIN")
+            elif self.db_type == "mysql":
+                await self._connection.begin()
+            elif self.db_type == "sqlserver":
+                async with self._connection.cursor() as cursor:
+                    await cursor.execute("BEGIN TRANSACTION")
+            elif self.db_type == "oracle":
+                pass  # Oracle starts transactions implicitly
+            elif self.db_type == "postgres":
+                # asyncpg transactions are managed via connection.transaction()
+                # Calling begin() manually is supported but the context manager
+                # is preferred — see transaction() below
+                self._pg_transaction = self._connection.transaction()
+                await self._pg_transaction.start()
+            logger.info("Transaction started on %s", self.db_type)
+        except Exception as e:
+            raise AsyncQueryError(f"Failed to begin transaction: {e}") from e
+
+    async def commit_transaction(self) -> None:
+        """Commit the current transaction."""
+        self._check_connection()
+        try:
+            if self.db_type == "postgres":
+                await self._pg_transaction.commit()
+            else:
+                await self._connection.commit()
+            logger.info("Transaction committed on %s", self.db_type)
+        except Exception as e:
+            raise AsyncQueryError(f"Failed to commit transaction: {e}") from e
+
+    async def rollback_transaction(self) -> None:
+        """Roll back the current transaction."""
+        self._check_connection()
+        try:
+            if self.db_type == "postgres":
+                await self._pg_transaction.rollback()
+            else:
+                await self._connection.rollback()
+            logger.info("Transaction rolled back on %s", self.db_type)
+        except Exception as e:
+            raise AsyncQueryError(f"Failed to rollback transaction: {e}") from e
+
+    # -----------------------------------------------------------------------
+    # Connection pooling
+    # -----------------------------------------------------------------------
+
+    async def setup_pool(self, min_size: int = 1, max_size: int = 10) -> None:
+        """
+        Set up an async connection pool.
+
+        Supported for PostgreSQL and MySQL only.
+        After calling this, use get_connection_from_pool() to acquire
+        connections.
+
+        Args:
+            min_size: Minimum number of connections in the pool.
+            max_size: Maximum number of connections in the pool.
+
+        Raises:
+            AsyncConnectionError: If pool setup fails or db_type
+                                  does not support pooling.
+        """
+        try:
+            if self.db_type == "postgres":
+                import asyncpg
+
+                self._pool = await asyncpg.create_pool(
+                    host=self.host,
+                    port=int(self.port or 5432),
+                    user=self.user,
+                    password=self.password,
+                    database=self.database,
+                    min_size=min_size,
+                    max_size=max_size,
+                )
+                logger.info(
+                    "PostgreSQL async pool created (min=%d, max=%d)", min_size, max_size
+                )
+
+            elif self.db_type == "mysql":
+                import aiomysql
+
+                self._pool = await aiomysql.create_pool(
+                    host=self.host or "localhost",
+                    port=int(self.port or 3306),
+                    user=self.user,
+                    password=self.password or "",
+                    db=self.database,
+                    minsize=min_size,
+                    maxsize=max_size,
+                )
+                logger.info(
+                    "MySQL async pool created (min=%d, max=%d)", min_size, max_size
+                )
+
+            else:
+                raise AsyncConnectionError(
+                    f"Async connection pooling not supported for {self.db_type!r}. "
+                    "Supported: postgres, mysql."
+                )
+        except AsyncConnectionError:
+            raise
+        except Exception as e:
+            raise AsyncConnectionError(f"Failed to create async pool: {e}") from e
+
+    async def close_pool(self) -> None:
+        """Close the async connection pool."""
+        if self._pool is not None:
+            if self.db_type == "mysql":
+                self._pool.close()
+                await self._pool.wait_closed()
+            else:
+                await self._pool.close()
+            self._pool = None
+            logger.info("Async pool closed for %s", self.db_type)

sqlpyhelper/migration.py

@@ -0,0 +1,382 @@
+"""
+sqlpyhelper.migration
+~~~~~~~~~~~~~~~~~~~~~
+Cross-database table migration utilities.
+
+Copies data (and optionally schema) from one database to another.
+Supports SQLite, PostgreSQL, MySQL, SQL Server, and Oracle.
+
+Example usage::
+
+    from sqlpyhelper.db_helper import SQLPyHelper
+    from sqlpyhelper.migration import migrate_table
+
+    with SQLPyHelper(db_type="sqlite", database="local.db") as source:
+        with SQLPyHelper(db_type="postgres", host="localhost",
+                         user="user", password="pass",
+                         database="mydb") as target:
+
+            migrate_table(
+                source=source,
+                target=target,
+                table="users",
+            )
+"""
+
+import logging
+from typing import Any, Optional
+
+logger = logging.getLogger("sqlpyhelper.migration")
+
+
+class MigrationError(Exception):
+    """Raised when a migration operation fails."""
+
+
+# ---------------------------------------------------------------------------
+# Type mapping
+# ---------------------------------------------------------------------------
+
+# Maps (source_db_type, generic_type) -> target SQL type string.
+# Generic types are normalised from the source cursor description.
+
+
+_TYPE_MAP: dict[str, dict[str, str]] = {
+    "sqlite": {
+        "integer": "INTEGER",
+        "real": "REAL",
+        "text": "TEXT",
+        "blob": "BLOB",
+        "numeric": "NUMERIC",
+    },
+    "postgres": {
+        "integer": "INTEGER",
+        "real": "DOUBLE PRECISION",
+        "text": "TEXT",
+        "blob": "BYTEA",
+        "numeric": "NUMERIC",
+        "varchar": "TEXT",
+        "bool": "BOOLEAN",
+        "date": "DATE",
+        "timestamp": "TIMESTAMP",
+    },
+    "mysql": {
+        "integer": "INT",
+        "real": "DOUBLE",
+        "text": "TEXT",
+        "blob": "BLOB",
+        "numeric": "DECIMAL",
+        "varchar": "VARCHAR(255)",
+        "bool": "TINYINT(1)",
+        "date": "DATE",
+        "timestamp": "DATETIME",
+    },
+    "sqlserver": {
+        "integer": "INT",
+        "real": "FLOAT",
+        "text": "NVARCHAR(MAX)",
+        "blob": "VARBINARY(MAX)",
+        "numeric": "DECIMAL",
+        "varchar": "NVARCHAR(255)",
+        "bool": "BIT",
+        "date": "DATE",
+        "timestamp": "DATETIME2",
+    },
+    "oracle": {
+        "integer": "NUMBER",
+        "real": "FLOAT",
+        "text": "CLOB",
+        "blob": "BLOB",
+        "numeric": "NUMBER",
+        "varchar": "VARCHAR2(255)",
+        "bool": "NUMBER(1)",
+        "date": "DATE",
+        "timestamp": "TIMESTAMP",
+    },
+}
+
+
+def _normalise_type(raw_type: Optional[str]) -> str:
+    """
+    Normalise a raw column type string from a cursor description
+    into a generic type key used for cross-database mapping.
+    """
+    if raw_type is None:
+        return "text"
+    t = raw_type.lower().split("(")[0].strip()
+    if t in (
+        "int",
+        "integer",
+        "int4",
+        "int8",
+        "bigint",
+        "smallint",
+        "tinyint",
+        "number",
+    ):
+        return "integer"
+    if t in ("real", "float", "double", "double precision", "float4", "float8"):
+        return "real"
+    if t in (
+        "text",
+        "clob",
+        "nvarchar",
+        "nvarchar2",
+        "ntext",
+        "longtext",
+        "mediumtext",
+    ):
+        return "text"
+    if t in ("varchar", "varchar2", "character varying", "char", "nchar"):
+        return "varchar"
+    if t in ("blob", "bytea", "varbinary", "binary", "longblob", "mediumblob"):
+        return "blob"
+    if t in ("numeric", "decimal"):
+        return "numeric"
+    if t in ("bool", "boolean"):
+        return "bool"
+    if t in ("date",):
+        return "date"
+    if t in ("timestamp", "datetime", "datetime2", "timestamp without time zone"):
+        return "timestamp"
+    return "text"  # safe fallback
+
+
+def _map_type(raw_type: Optional[str], target_db: str) -> str:
+    """Map a source column type to the appropriate type for the target database."""
+    generic = _normalise_type(raw_type)
+    target_types = _TYPE_MAP.get(target_db, _TYPE_MAP["sqlite"])
+    return target_types.get(generic, "TEXT")
+
+
+def _get_column_info(source: Any, table: str) -> list[tuple[str, str]]:
+    """
+    Return a list of (column_name, raw_type_string) tuples
+    by inspecting the source database schema.
+    """
+    db_type = source.db_type
+
+    if db_type == "sqlite":
+        source.execute_query(f"PRAGMA table_info({table})")
+        rows = source.fetch_all()
+        # PRAGMA table_info returns: (cid, name, type, notnull, dflt_value, pk)
+        return [(row[1], row[2]) for row in rows]
+
+    elif db_type == "postgres":
+        source.execute_query(
+            """
+            SELECT column_name, data_type
+            FROM information_schema.columns
+            WHERE table_name = %s
+            ORDER BY ordinal_position
+            """,
+            (table,),
+        )
+        return source.fetch_all()
+
+    elif db_type == "mysql":
+        source.execute_query(
+            """
+            SELECT column_name, data_type
+            FROM information_schema.columns
+            WHERE table_name = %s AND table_schema = DATABASE()
+            ORDER BY ordinal_position
+            """,
+            (table,),
+        )
+        return source.fetch_all()
+
+    elif db_type == "sqlserver":
+        source.execute_query(
+            """
+            SELECT column_name, data_type
+            FROM information_schema.columns
+            WHERE table_name = %s
+            ORDER BY ordinal_position
+            """,
+            (table,),
+        )
+        return source.fetch_all()
+
+    elif db_type == "oracle":
+        source.execute_query(
+            """
+            SELECT column_name, data_type
+            FROM user_tab_columns
+            WHERE table_name = UPPER(:1)
+            ORDER BY column_id
+            """,
+            (table,),
+        )
+        return source.fetch_all()
+
+    else:
+        raise MigrationError(f"Cannot inspect schema for db_type={db_type!r}")
+
+
+def _build_create_table_sql(
+    table: str,
+    columns: list[tuple[str, str]],
+    target_db: str,
+) -> str:
+    """Build a CREATE TABLE IF NOT EXISTS statement for the target database."""
+    col_defs = ", ".join(
+        f"{col_name} {_map_type(col_type, target_db)}" for col_name, col_type in columns
+    )
+    return f"CREATE TABLE IF NOT EXISTS {table} ({col_defs})"
+
+
+def _build_insert_sql(
+    table: str,
+    column_names: list[str],
+    target_db: str,
+) -> str:
+    """Build a parameterised INSERT statement for the target database."""
+    cols = ", ".join(column_names)
+    placeholder = "?" if target_db == "sqlite" else "%s"
+    placeholders = ", ".join([placeholder] * len(column_names))
+    return f"INSERT INTO {table} ({cols}) VALUES ({placeholders})"
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def migrate_table(
+    source: Any,
+    target: Any,
+    table: str,
+    create_table: bool = True,
+    batch_size: int = 500,
+    truncate_target: bool = False,
+) -> dict[str, Any]:
+    """
+    Migrate a table from one database to another.
+
+    Copies all rows from ``source`` to ``target``. Optionally creates
+    the target table using best-effort type mapping from the source schema.
+
+    Args:
+        source: A connected SQLPyHelper instance (the data source).
+        target: A connected SQLPyHelper instance (the destination).
+        table:  Name of the table to migrate.
+        create_table: If True, creates the table in the target database
+                      using best-effort type mapping. If False, the table
+                      must already exist in the target. Default: True.
+        batch_size: Number of rows to insert per batch. Default: 500.
+        truncate_target: If True, deletes all existing rows in the target
+                         table before inserting. Default: False.
+
+    Returns:
+        A dict with migration statistics::
+
+            {
+                "table": "users",
+                "rows_migrated": 1234,
+                "batches": 3,
+                "source_db": "sqlite",
+                "target_db": "postgres",
+            }
+
+    Raises:
+        MigrationError: If the migration fails for any reason.
+
+    Example::
+
+        from sqlpyhelper.db_helper import SQLPyHelper
+        from sqlpyhelper.migration import migrate_table
+
+        with SQLPyHelper(db_type="sqlite", database="local.db") as source:
+            with SQLPyHelper(db_type="postgres", host="localhost",
+                             user="user", password="pass",
+                             database="mydb") as target:
+
+                stats = migrate_table(
+                    source=source,
+                    target=target,
+                    table="users",
+                    create_table=True,
+                    batch_size=1000,
+                )
+                print(f"Migrated {stats['rows_migrated']} rows")
+    """
+    source_db = source.db_type
+    target_db = target.db_type
+
+    logger.info(
+        "Starting migration of table '%s' from %s -> %s",
+        table,
+        source_db,
+        target_db,
+    )
+
+    try:
+        # Step 1 — fetch column info from source
+        columns = _get_column_info(source, table)
+        if not columns:
+            raise MigrationError(
+                f"Table '{table}' not found in source database " f"or has no columns."
+            )
+        column_names = [col[0] for col in columns]
+        logger.info("Found %d columns: %s", len(columns), column_names)
+
+        # Step 2 — optionally create the table in the target
+        if create_table:
+            ddl = _build_create_table_sql(table, columns, target_db)
+            logger.info("Creating target table: %s", ddl)
+            target.execute_query(ddl)
+
+        # Step 3 — optionally truncate the target table
+        if truncate_target:
+            if target_db == "sqlite":
+                target.execute_query(f"DELETE FROM {table}")
+            else:
+                target.execute_query(f"TRUNCATE TABLE {table}")
+            logger.info("Truncated target table '%s'", table)
+
+        # Step 4 — fetch all rows from source
+        source.execute_query(f"SELECT * FROM {table}")
+        all_rows = source.fetch_all()
+        total_rows = len(all_rows)
+        logger.info("Fetched %d rows from source", total_rows)
+
+        if total_rows == 0:
+            logger.info("Source table '%s' is empty — nothing to migrate", table)
+            return {
+                "table": table,
+                "rows_migrated": 0,
+                "batches": 0,
+                "source_db": source_db,
+                "target_db": target_db,
+            }
+
+        # Step 5 — insert in batches
+        insert_sql = _build_insert_sql(table, column_names, target_db)
+        batches = 0
+        for i in range(0, total_rows, batch_size):
+            batch = all_rows[i : i + batch_size]
+            target.cursor.executemany(insert_sql, batch)
+            target.connection.commit()
+            batches += 1
+            logger.info(
+                "Inserted batch %d (%d/%d rows)",
+                batches,
+                min(i + batch_size, total_rows),
+                total_rows,
+            )
+
+        logger.info("Migration complete: %d rows in %d batches", total_rows, batches)
+
+        return {
+            "table": table,
+            "rows_migrated": total_rows,
+            "batches": batches,
+            "source_db": source_db,
+            "target_db": target_db,
+        }
+
+    except MigrationError:
+        raise
+    except Exception as e:
+        raise MigrationError(f"Migration of '{table}' failed: {e}") from e

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: SQLPyHelper
-Version: 0.1.6
+Version: 0.1.8
 Summary: A simple SQL database helper package for Python.
 Home-page: https://github.com/adebayopeter/sqlpyhelper
 Author: Adebayo Olaonipekun
@@ -34,11 +34,28 @@ Provides-Extra: sqlserver
 Requires-Dist: pyodbc; extra == "sqlserver"
 Provides-Extra: oracle
 Requires-Dist: oracledb; extra == "oracle"
+Provides-Extra: async-postgres
+Requires-Dist: asyncpg; extra == "async-postgres"
+Provides-Extra: async-mysql
+Requires-Dist: aiomysql; extra == "async-mysql"
+Provides-Extra: async-sqlite
+Requires-Dist: aiosqlite; extra == "async-sqlite"
+Provides-Extra: async-sqlserver
+Requires-Dist: aioodbc; extra == "async-sqlserver"
+Provides-Extra: async-all
+Requires-Dist: asyncpg; extra == "async-all"
+Requires-Dist: aiomysql; extra == "async-all"
+Requires-Dist: aiosqlite; extra == "async-all"
+Requires-Dist: aioodbc; extra == "async-all"
 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"
+Requires-Dist: asyncpg; extra == "all"
+Requires-Dist: aiomysql; extra == "all"
+Requires-Dist: aiosqlite; extra == "all"
+Requires-Dist: aioodbc; extra == "all"
 Dynamic: author
 Dynamic: author-email
 Dynamic: classifier
@@ -56,11 +73,11 @@ Dynamic: summary
 # SQLPyHelper
 
 [![PyPI version](https://img.shields.io/pypi/v/sqlpyhelper.svg)](https://pypi.org/project/sqlpyhelper/)
+[![Documentation](https://readthedocs.org/projects/sqlpyhelper/badge/?version=latest)](https://sqlpyhelper.readthedocs.io/en/latest/)
 [![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)
-[![Documentation](https://readthedocs.org/projects/sqlpyhelper/badge/?version=latest)](https://sqlpyhelper.readthedocs.io/en/latest/)
 
 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.
 

sqlpyhelper-0.1.8.dist-info/RECORD

@@ -0,0 +1,13 @@
+sqlpyhelper/__init__.py,sha256=UN7k9UyQVsxtFLDH496vDYQdGOIa525T4lGvVXjRM8s,370
+sqlpyhelper/async_helper.py,sha256=_R01cUZSj_q9QH4pGT30gh56GJGSfgi0hIhgDJqmyYw,21534
+sqlpyhelper/automation_utils.py,sha256=pC6pH6bJ-k8iPVeHJ4gUiwEe822dasmKg53ya9bMxyE,5381
+sqlpyhelper/cli.py,sha256=yj0kWJu3oh_JLnmi0L7a5ing2_0x4CQGOKSOhZLAtoY,5646
+sqlpyhelper/db_helper.py,sha256=4DbdBVo86zz1d0hNHtSc4b3Tks7bJGTMTyabsydQyOE,14191
+sqlpyhelper/migration.py,sha256=byAn7ToVgIB8tl1N39DB0MbHigjH2l-qX7QSskgzzTg,11673
+sqlpyhelper/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sqlpyhelper-0.1.8.dist-info/licenses/LICENSE,sha256=9XzXxZ_8mWFM9-2TlqyE3L69zvRf4VPY_xIzSj5iU-g,1076
+sqlpyhelper-0.1.8.dist-info/METADATA,sha256=l-kKKsEjezQU1GjTsXHFeRpDAjiPfK-5AIlepQ396Wk,10450
+sqlpyhelper-0.1.8.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+sqlpyhelper-0.1.8.dist-info/entry_points.txt,sha256=uAzSqwkAbbJqQUKHlPNwOebTJVA0FqkOvn2CRP6xSz8,52
+sqlpyhelper-0.1.8.dist-info/top_level.txt,sha256=FrLqTmqTGDa8jHnnf2ZVkYO-gFvLXX9QonpUCE6wKGs,12
+sqlpyhelper-0.1.8.dist-info/RECORD,,

sqlpyhelper-0.1.6.dist-info/RECORD

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