DEPR: Add FutureWarning for pandas.io.sql.execute

doc/source/whatsnew/v2.0.0.rst

@@ -553,9 +553,10 @@ Other API changes
 Deprecations
 ~~~~~~~~~~~~
 - Deprecated argument ``infer_datetime_format`` in :func:`to_datetime` and :func:`read_csv`, as a strict version of it is now the default (:issue:`48621`)
+- Deprecated :func:`pandas.io.sql.execute`(:issue:`50185`)
+-
 
 .. ---------------------------------------------------------------------------
-
 .. _whatsnew_200.prior_deprecations:
 
 Removal of prior version deprecations/changes

pandas/core/generic.py

@@ -2858,8 +2858,11 @@ def to_sql(
 
         >>> df.to_sql('users', con=engine)
         3
-        >>> engine.execute("SELECT * FROM users").fetchall()
-        [(0, 'User 1'), (1, 'User 2'), (2, 'User 3')]
+        >>> pd.read_sql_query("SELECT * FROM users", con=engine)
+            index    name
+        0      0  User 1
+        1      1  User 2
+        2      2  User 3
 
         An `sqlalchemy.engine.Connection` can also be passed to `con`:
 
@@ -2874,18 +2877,25 @@ def to_sql(
         >>> df2 = pd.DataFrame({'name' : ['User 6', 'User 7']})
         >>> df2.to_sql('users', con=engine, if_exists='append')
         2
-        >>> engine.execute("SELECT * FROM users").fetchall()
-        [(0, 'User 1'), (1, 'User 2'), (2, 'User 3'),
-         (0, 'User 4'), (1, 'User 5'), (0, 'User 6'),
-         (1, 'User 7')]
+        >>> pd.read_sql_query("SELECT * FROM users", con=engine)
+            index    name
+        0      0  User 1
+        1      1  User 2
+        2      2  User 3
+        3      0  User 4
+        4      1  User 5
+        5      0  User 6
+        6      1  User 7
 
         Overwrite the table with just ``df2``.
 
         >>> df2.to_sql('users', con=engine, if_exists='replace',
         ...            index_label='id')
         2
-        >>> engine.execute("SELECT * FROM users").fetchall()
-        [(0, 'User 6'), (1, 'User 7')]
+        >>> pd.read_sql_query("SELECT * FROM users", con=engine)
+           id    name
+        0   0  User 6
+        1   1  User 7
 
         Specify the dtype (especially useful for integers with missing values).
         Notice that while pandas is forced to store the data as floating point,
@@ -2904,8 +2914,11 @@ def to_sql(
         ...           dtype={"A": Integer()})
         3
 
-        >>> engine.execute("SELECT * FROM integers").fetchall()
-        [(1,), (None,), (2,)]
+        >>> pd.read_sql("SELECT * FROM integers", con=engine)
+             A
+        0  1.0
+        1  NaN
+        2  2.0
         """  # noqa:E501
         from pandas.io import sql
 

pandas/io/sql.py

@@ -201,6 +201,12 @@ def execute(sql, con, params=None):
     -------
     Results Iterable
     """
+    warnings.warn(
+        "`pandas.io.sql.execute` is deprecated and "
+        "will be removed in the future version.",
+        FutureWarning,
+        stacklevel=find_stack_level(),
+    )  # GH50185
     sqlalchemy = import_optional_dependency("sqlalchemy", errors="ignore")
 
     if sqlalchemy is not None and isinstance(con, (str, sqlalchemy.engine.Engine)):

pandas/tests/io/test_sql.py

@@ -668,6 +668,16 @@ def test_execute_typeerror(sqlite_iris_engine):
         sql.execute("select * from iris", sqlite_iris_engine)
 
 
+def test_execute_deprecated(sqlite_buildin_iris):
+    # GH50185
+    with tm.assert_produces_warning(
+        FutureWarning,
+        match="`pandas.io.sql.execute` is deprecated and "
+        "will be removed in the future version.",
+    ):
+        sql.execute("select * from iris", sqlite_buildin_iris)
+
+
 class MixInBase:
     def teardown_method(self):
         # if setup fails, there may not be a connection to close.