SQLPyHelper 0.1.6__tar.gz → 0.1.7__tar.gz

{sqlpyhelper-0.1.6 → sqlpyhelper-0.1.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: SQLPyHelper
-Version: 0.1.6
+Version: 0.1.7
 Summary: A simple SQL database helper package for Python.
 Home-page: https://github.com/adebayopeter/sqlpyhelper
 Author: Adebayo Olaonipekun
@@ -56,11 +56,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.6 → sqlpyhelper-0.1.7}/README.md

@@ -1,11 +1,11 @@
 # 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.6 → sqlpyhelper-0.1.7}/SQLPyHelper.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: SQLPyHelper
-Version: 0.1.6
+Version: 0.1.7
 Summary: A simple SQL database helper package for Python.
 Home-page: https://github.com/adebayopeter/sqlpyhelper
 Author: Adebayo Olaonipekun
@@ -56,11 +56,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.6 → sqlpyhelper-0.1.7}/SQLPyHelper.egg-info/SOURCES.txt

@@ -13,5 +13,7 @@ sqlpyhelper/__init__.py
 sqlpyhelper/automation_utils.py
 sqlpyhelper/cli.py
 sqlpyhelper/db_helper.py
+sqlpyhelper/migration.py
 sqlpyhelper/py.typed
+test/test_migration.py
 test/test_sqlpyhelper.py

{sqlpyhelper-0.1.6 → sqlpyhelper-0.1.7}/setup.py

@@ -5,7 +5,7 @@ with open("README.md", "r", encoding="utf-8") as f:
 
 setup(
     name='SQLPyHelper',
-    version='0.1.6',
+    version='0.1.7',
     description='A simple SQL database helper package for Python.',
     long_description=long_description,
     long_description_content_type="text/markdown",

{sqlpyhelper-0.1.6 → sqlpyhelper-0.1.7}/sqlpyhelper/__init__.py

@@ -1,5 +1,5 @@
 # Match the version in setup.py
-__version__ = "0.1.6"
+__version__ = "0.1.7"
 
 from sqlpyhelper.db_helper import (  # noqa: F401
     BackupError,
@@ -7,3 +7,4 @@ from sqlpyhelper.db_helper import (  # noqa: F401
     QueryError,
     SQLPyHelperError,
 )
+from sqlpyhelper.migration import MigrationError  # noqa: F401

sqlpyhelper-0.1.7/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.7/test/test_migration.py

@@ -0,0 +1,317 @@
+"""
+Tests for sqlpyhelper.migration
+All tests use mocking — no live database required.
+"""
+
+from unittest.mock import MagicMock
+
+import pytest
+
+from sqlpyhelper.migration import (
+    MigrationError,
+    _build_create_table_sql,
+    _build_insert_sql,
+    _map_type,
+    _normalise_type,
+    migrate_table,
+)
+
+# ---------------------------------------------------------------------------
+# _normalise_type
+# ---------------------------------------------------------------------------
+
+
+class TestNormaliseType:
+    def test_integer_variants(self):
+        for t in ("int", "integer", "bigint", "smallint", "tinyint", "number"):
+            assert _normalise_type(t) == "integer"
+
+    def test_real_variants(self):
+        for t in ("real", "float", "double", "double precision"):
+            assert _normalise_type(t) == "real"
+
+    def test_text_variants(self):
+        for t in ("text", "clob", "nvarchar", "longtext"):
+            assert _normalise_type(t) == "text"
+
+    def test_varchar_variants(self):
+        for t in ("varchar", "varchar2", "character varying", "char"):
+            assert _normalise_type(t) == "varchar"
+
+    def test_blob_variants(self):
+        for t in ("blob", "bytea", "varbinary"):
+            assert _normalise_type(t) == "blob"
+
+    def test_bool_variants(self):
+        for t in ("bool", "boolean"):
+            assert _normalise_type(t) == "bool"
+
+    def test_none_returns_text(self):
+        assert _normalise_type(None) == "text"
+
+    def test_unknown_returns_text(self):
+        assert _normalise_type("jsonb") == "text"
+
+    def test_strips_length_spec(self):
+        assert _normalise_type("varchar(255)") == "varchar"
+        assert _normalise_type("numeric(10,2)") == "numeric"
+
+
+# ---------------------------------------------------------------------------
+# _map_type
+# ---------------------------------------------------------------------------
+
+
+class TestMapType:
+    def test_sqlite_integer(self):
+        assert _map_type("integer", "sqlite") == "INTEGER"
+
+    def test_postgres_integer(self):
+        assert _map_type("integer", "postgres") == "INTEGER"
+
+    def test_mysql_integer(self):
+        assert _map_type("integer", "mysql") == "INT"
+
+    def test_sqlserver_integer(self):
+        assert _map_type("integer", "sqlserver") == "INT"
+
+    def test_oracle_integer(self):
+        assert _map_type("integer", "oracle") == "NUMBER"
+
+    def test_postgres_text(self):
+        assert _map_type("text", "postgres") == "TEXT"
+
+    def test_sqlserver_text(self):
+        assert _map_type("text", "sqlserver") == "NVARCHAR(MAX)"
+
+    def test_oracle_text(self):
+        assert _map_type("text", "oracle") == "CLOB"
+
+    def test_unknown_db_falls_back(self):
+        result = _map_type("integer", "unknowndb")
+        assert result == "INTEGER"
+
+
+# ---------------------------------------------------------------------------
+# _build_create_table_sql
+# ---------------------------------------------------------------------------
+
+
+class TestBuildCreateTableSql:
+    def test_sqlite_ddl(self):
+        columns = [("id", "integer"), ("name", "text")]
+        sql = _build_create_table_sql("users", columns, "sqlite")
+        assert "CREATE TABLE IF NOT EXISTS users" in sql
+        assert "id INTEGER" in sql
+        assert "name TEXT" in sql
+
+    def test_postgres_ddl(self):
+        columns = [("id", "integer"), ("name", "varchar")]
+        sql = _build_create_table_sql("users", columns, "postgres")
+        assert "id INTEGER" in sql
+        assert "name TEXT" in sql
+
+    def test_mysql_ddl(self):
+        columns = [("id", "integer"), ("name", "text")]
+        sql = _build_create_table_sql("users", columns, "mysql")
+        assert "id INT" in sql
+        assert "name TEXT" in sql
+
+    def test_sqlserver_ddl(self):
+        columns = [("id", "integer"), ("notes", "text")]
+        sql = _build_create_table_sql("orders", columns, "sqlserver")
+        assert "CREATE TABLE IF NOT EXISTS orders" in sql
+        assert "id INT" in sql
+        assert "notes NVARCHAR(MAX)" in sql
+
+    def test_oracle_ddl(self):
+        columns = [("id", "integer"), ("name", "varchar")]
+        sql = _build_create_table_sql("users", columns, "oracle")
+        assert "id NUMBER" in sql
+        assert "name VARCHAR2(255)" in sql
+
+
+# ---------------------------------------------------------------------------
+# _build_insert_sql
+# ---------------------------------------------------------------------------
+
+
+class TestBuildInsertSql:
+    def test_sqlite_uses_question_mark(self):
+        sql = _build_insert_sql("users", ["id", "name"], "sqlite")
+        assert "?" in sql
+        assert "%s" not in sql
+
+    def test_postgres_uses_percent_s(self):
+        sql = _build_insert_sql("users", ["id", "name"], "postgres")
+        assert "%s" in sql
+        assert "?" not in sql
+
+    def test_correct_column_count(self):
+        sql = _build_insert_sql("users", ["id", "name", "email"], "mysql")
+        assert sql.count("%s") == 3
+
+    def test_table_name_in_sql(self):
+        sql = _build_insert_sql("orders", ["id", "item"], "postgres")
+        assert "INSERT INTO orders" in sql
+
+
+# ---------------------------------------------------------------------------
+# migrate_table
+# ---------------------------------------------------------------------------
+
+
+def make_mock_db(db_type="sqlite"):
+    """Create a mock SQLPyHelper instance."""
+    db = MagicMock()
+    db.db_type = db_type
+    db.cursor = MagicMock()
+    db.connection = MagicMock()
+    return db
+
+
+class TestMigrateTable:
+    def test_basic_sqlite_to_postgres(self):
+        source = make_mock_db("sqlite")
+        target = make_mock_db("postgres")
+
+        # Mock PRAGMA response for SQLite column info
+        source.fetch_all.side_effect = [
+            [(0, "id", "integer", 0, None, 1), (1, "name", "text", 0, None, 0)],
+            [(1, "Alice"), (2, "Bob")],
+        ]
+
+        stats = migrate_table(source=source, target=target, table="users")
+
+        assert stats["rows_migrated"] == 2
+        assert stats["source_db"] == "sqlite"
+        assert stats["target_db"] == "postgres"
+        assert stats["table"] == "users"
+        assert stats["batches"] == 1
+
+    def test_create_table_called_when_flag_true(self):
+        source = make_mock_db("sqlite")
+        target = make_mock_db("postgres")
+
+        source.fetch_all.side_effect = [
+            [(0, "id", "integer", 0, None, 1)],
+            [(1,), (2,)],
+        ]
+
+        migrate_table(source=source, target=target, table="users", create_table=True)
+        target.execute_query.assert_called()
+        first_call = target.execute_query.call_args_list[0][0][0]
+        assert "CREATE TABLE IF NOT EXISTS users" in first_call
+
+    def test_create_table_not_called_when_flag_false(self):
+        source = make_mock_db("sqlite")
+        target = make_mock_db("postgres")
+
+        source.fetch_all.side_effect = [
+            [(0, "id", "integer", 0, None, 1)],
+            [(1,)],
+        ]
+
+        migrate_table(source=source, target=target, table="users", create_table=False)
+        # execute_query should not be called on target for DDL
+        for call in target.execute_query.call_args_list:
+            assert "CREATE TABLE" not in str(call)
+
+    def test_empty_table_returns_zero_rows(self):
+        source = make_mock_db("sqlite")
+        target = make_mock_db("postgres")
+
+        source.fetch_all.side_effect = [
+            [(0, "id", "integer", 0, None, 1)],
+            [],
+        ]
+
+        stats = migrate_table(source=source, target=target, table="users")
+        assert stats["rows_migrated"] == 0
+        assert stats["batches"] == 0
+        target.cursor.executemany.assert_not_called()
+
+    def test_batching(self):
+        source = make_mock_db("sqlite")
+        target = make_mock_db("postgres")
+
+        rows = [(i,) for i in range(25)]
+        source.fetch_all.side_effect = [
+            [(0, "id", "integer", 0, None, 1)],
+            rows,
+        ]
+
+        stats = migrate_table(
+            source=source, target=target, table="users", batch_size=10
+        )
+        assert stats["rows_migrated"] == 25
+        assert stats["batches"] == 3
+        assert target.cursor.executemany.call_count == 3
+
+    def test_truncate_target_sqlite(self):
+        source = make_mock_db("sqlite")
+        target = make_mock_db("sqlite")
+
+        source.fetch_all.side_effect = [
+            [(0, "id", "integer", 0, None, 1)],
+            [(1,)],
+        ]
+
+        migrate_table(source=source, target=target, table="users", truncate_target=True)
+        delete_calls = [
+            str(c) for c in target.execute_query.call_args_list if "DELETE" in str(c)
+        ]
+        assert len(delete_calls) == 1
+
+    def test_truncate_target_postgres(self):
+        source = make_mock_db("sqlite")
+        target = make_mock_db("postgres")
+
+        source.fetch_all.side_effect = [
+            [(0, "id", "integer", 0, None, 1)],
+            [(1,)],
+        ]
+
+        migrate_table(source=source, target=target, table="users", truncate_target=True)
+        truncate_calls = [
+            str(c) for c in target.execute_query.call_args_list if "TRUNCATE" in str(c)
+        ]
+        assert len(truncate_calls) == 1
+
+    def test_raises_migration_error_on_empty_columns(self):
+        source = make_mock_db("sqlite")
+        target = make_mock_db("postgres")
+
+        source.fetch_all.return_value = []
+
+        with pytest.raises(MigrationError, match="not found in source database"):
+            migrate_table(source=source, target=target, table="nonexistent")
+
+    def test_raises_migration_error_on_db_failure(self):
+        source = make_mock_db("sqlite")
+        target = make_mock_db("postgres")
+
+        source.fetch_all.side_effect = Exception("connection lost")
+
+        with pytest.raises(MigrationError, match="Migration of 'users' failed"):
+            migrate_table(source=source, target=target, table="users")
+
+    def test_returns_correct_stats_structure(self):
+        source = make_mock_db("mysql")
+        target = make_mock_db("sqlserver")
+
+        source.fetch_all.side_effect = [
+            [("id", "int"), ("name", "varchar")],
+            [(1, "Alice"), (2, "Bob"), (3, "Charlie")],
+        ]
+
+        stats = migrate_table(source=source, target=target, table="customers")
+        assert set(stats.keys()) == {
+            "table",
+            "rows_migrated",
+            "batches",
+            "source_db",
+            "target_db",
+        }
+        assert stats["source_db"] == "mysql"
+        assert stats["target_db"] == "sqlserver"