Deprecate plain string in execute and introduce `exec_driver_sql`

Execution of literal sql string is deprecated in the
:meth:`.Connection.execute` and a warning is raised when used stating
that it will be coerced to :func:`.text` in a future release.
To execute a raw sql string the new connection method
:meth:`.Connection.exec_driver_sql` was added, that will retain the previous
behavior, passing the string to the DBAPI driver unchanged.
Usage of scalar or tuple positional parameters in :meth:`.Connection.execute`
is also deprecated.

Fixes: #4848
Fixes: #5178
Change-Id: I2830181054327996d594f7f0d59c157d477c3aa9

4 files changed, 13 insertions, 5 deletions

diff --git a/lib/sqlalchemy/testing/suite/test_results.py b/lib/sqlalchemy/testing/suite/test_results.py
index 5186e189c..7a3e92564 100644
--- a/lib/sqlalchemy/testing/suite/test_results.py
+++ b/lib/sqlalchemy/testing/suite/test_results.py
@@ -15,6 +15,7 @@ from ... import sql
 from ... import String
 from ... import testing
 from ... import text
+from ... import util
 
 
 class RowFetchTest(fixtures.TablesTest):
@@ -287,7 +288,10 @@ class ServerSideCursorsTest(
     ):
         engine = self._fixture(engine_ss_arg)
         with engine.begin() as conn:
-            result = conn.execute(statement)
+            if isinstance(statement, util.string_types):
+                result = conn.exec_driver_sql(statement)
+            else:
+                result = conn.execute(statement)
             eq_(self._is_server_side(result.cursor), cursor_ss_status)
             result.close()
 
@@ -298,7 +302,7 @@ class ServerSideCursorsTest(
         result = (
             engine.connect()
             .execution_options(stream_results=True)
-            .execute("select 1")
+            .exec_driver_sql("select 1")
         )
         assert self._is_server_side(result.cursor)
 
diff --git a/lib/sqlalchemy/testing/suite/test_rowcount.py b/lib/sqlalchemy/testing/suite/test_rowcount.py
index 83c2f8da4..ae189bc79 100644
--- a/lib/sqlalchemy/testing/suite/test_rowcount.py
+++ b/lib/sqlalchemy/testing/suite/test_rowcount.py
@@ -95,7 +95,7 @@ class RowCountTest(fixtures.TablesTest):
 
     def test_raw_sql_rowcount(self, connection):
         # test issue #3622, make sure eager rowcount is called for text
-        result = connection.execute(
+        result = connection.exec_driver_sql(
             "update employees set department='Z' where department='C'"
         )
         eq_(result.rowcount, 3)
diff --git a/lib/sqlalchemy/testing/suite/test_select.py b/lib/sqlalchemy/testing/suite/test_select.py
index 3b64b0f29..5a7fd28e1 100644
--- a/lib/sqlalchemy/testing/suite/test_select.py
+++ b/lib/sqlalchemy/testing/suite/test_select.py
@@ -175,6 +175,10 @@ class LimitOffsetTest(fixtures.TablesTest):
     def _assert_result(self, select, result, params=()):
         eq_(config.db.execute(select, params).fetchall(), result)
 
+    def _assert_result_str(self, select, result, params=()):
+        conn = config.db.connect(close_with_result=True)
+        eq_(conn.exec_driver_sql(select, params).fetchall(), result)
+
     def test_simple_limit(self):
         table = self.tables.some_table
         self._assert_result(
@@ -209,7 +213,7 @@ class LimitOffsetTest(fixtures.TablesTest):
         )
         sql = str(sql)
 
-        self._assert_result(sql, [(2, 2, 3), (3, 3, 4)])
+        self._assert_result_str(sql, [(2, 2, 3), (3, 3, 4)])
 
     @testing.requires.bound_limit_offset
     def test_bound_limit(self):
diff --git a/lib/sqlalchemy/testing/suite/test_types.py b/lib/sqlalchemy/testing/suite/test_types.py
index 73cd1deca..9dabdbd65 100644
--- a/lib/sqlalchemy/testing/suite/test_types.py
+++ b/lib/sqlalchemy/testing/suite/test_types.py
@@ -1075,7 +1075,7 @@ class JSONStringCastIndexTest(_LiteralRoundTripFixture, fixtures.TablesTest):
                     )
                 )
 
-                eq_(conn.scalar(literal_sql), expected)
+                eq_(conn.exec_driver_sql(literal_sql).scalar(), expected)
 
     def test_string_cast_crit_spaces_in_key(self):
         name = self.tables.data_table.c.name