BUG: improve error message for non-string dtype with DB-API connection (GH#61385)

doc/source/whatsnew/v3.1.0.rst

@@ -346,6 +346,7 @@ MultiIndex
 I/O
 ^^^
 - :func:`read_csv` with ``memory_map=True`` and an in-memory buffer (e.g. ``BytesIO``) now raises a clear ``ValueError`` instead of a cryptic ``UnsupportedOperation: fileno`` (:issue:`45630`)
+- :meth:`DataFrame.to_sql` now raises a clearer ``ValueError`` when a non-string ``dtype`` is passed for a raw DB-API (e.g. sqlite3) connection, explaining that SQLAlchemy types require a SQLAlchemy engine (:issue:`61385`)
 - Fixed bug in :func:`read_csv` with the ``c`` engine where an embedded ``\r`` followed by a space in an unquoted field could cause an infinite re-parsing loop, producing spurious rows or a buffer overflow (:issue:`51141`)
 - Fixed bug in :func:`read_excel` where usage of ``skiprows`` could lead to an infinite loop (:issue:`64027`)
 - Fixed bug where :func:`read_html` parsed nested tables incorrectly when using ``html5lib`` or ``bs4`` flavors (:issue:`64524`)

pandas/io/sql.py

@@ -2867,7 +2867,12 @@ def to_sql(
 
             for col, my_type in dtype.items():
                 if not isinstance(my_type, str):
-                    raise ValueError(f"{col} ({my_type}) not a string")
+                    raise ValueError(
+                        f"Column '{col}' has type '{my_type}' which is not a "
+                        "string. When using a DB-API connection (e.g. sqlite3), "
+                        "dtype values must be SQL type strings (e.g. 'TEXT', "
+                        "'FLOAT')."
+                    )
 
         table = SQLiteTable(
             name,

pandas/tests/io/test_sql.py

@@ -4066,7 +4066,7 @@ def test_sqlite_test_dtype(sqlite_buildin):
     assert get_sqlite_column_type(conn, "dtype_test", "B") == "INTEGER"
 
     assert get_sqlite_column_type(conn, "dtype_test2", "B") == "STRING"
-    msg = r"B \(<class 'bool'>\) not a string"
+    msg = r"Column 'B' has type '<class 'bool'>' which is not a string"
     with pytest.raises(ValueError, match=msg):
         df.to_sql(name="error", con=conn, dtype={"B": bool})