Refactor sqlalchemy code in pandas.io.sql to help prepare for sqlalchemy 2.0. (pandas-dev#49531)

* DOC: Clarify behavior of DataFrame.to_sql

* CLN: Make SQLDatabase only accept a sqlalchemy Connection.

Co-authored-by: Chuck Cadman <[email protected]>

Author: 2 people

pandas/core/generic.py

@@ -2751,8 +2751,11 @@ def to_sql(
             Using SQLAlchemy makes it possible to use any DB supported by that
             library. Legacy support is provided for sqlite3.Connection objects. The user
             is responsible for engine disposal and connection closure for the SQLAlchemy
-            connectable See `here \
-                <https://docs.sqlalchemy.org/en/13/core/connections.html>`_.
+            connectable. See `here \
+                <https://docs.sqlalchemy.org/en/14/core/connections.html>`_.
+            If passing a sqlalchemy.engine.Connection which is already in a transaction,
+            the transaction will not be committed.  If passing a sqlite3.Connection,
+            it will not be possible to roll back the record insertion.
 
         schema : str, optional
             Specify the schema (if database flavor supports this). If None, use