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

2 files changed, 25 insertions, 24 deletions

diff --git a/lib/sqlalchemy/sql/base.py b/lib/sqlalchemy/sql/base.py
index 262dc4a0e..77222706a 100644
--- a/lib/sqlalchemy/sql/base.py
+++ b/lib/sqlalchemy/sql/base.py
@@ -470,6 +470,28 @@ class Generative(object):
         s.__dict__ = self.__dict__.copy()
         return s
 
+
+class HasCompileState(Generative):
+    """A class that has a :class:`.CompileState` associated with it."""
+
+    _compile_state_factory = CompileState._create
+
+    _compile_state_plugin = None
+
+
+class Executable(Generative):
+    """Mark a ClauseElement as supporting execution.
+
+    :class:`.Executable` is a superclass for all "statement" types
+    of objects, including :func:`select`, :func:`delete`, :func:`update`,
+    :func:`insert`, :func:`text`.
+
+    """
+
+    supports_execution = True
+    _execution_options = util.immutabledict()
+    _bind = None
+
     def options(self, *options):
         """Apply options to this statement.
 
@@ -501,28 +523,6 @@ class Generative(object):
         """
         self._options += options
 
-
-class HasCompileState(Generative):
-    """A class that has a :class:`.CompileState` associated with it."""
-
-    _compile_state_factory = CompileState._create
-
-    _compile_state_plugin = None
-
-
-class Executable(Generative):
-    """Mark a ClauseElement as supporting execution.
-
-    :class:`.Executable` is a superclass for all "statement" types
-    of objects, including :func:`select`, :func:`delete`, :func:`update`,
-    :func:`insert`, :func:`text`.
-
-    """
-
-    supports_execution = True
-    _execution_options = util.immutabledict()
-    _bind = None
-
     @_generative
     def execution_options(self, **kw):
         """ Set non-SQL options for the statement which take effect during
diff --git a/lib/sqlalchemy/sql/events.py b/lib/sqlalchemy/sql/events.py
index cd48d99fc..cd0ba2640 100644
--- a/lib/sqlalchemy/sql/events.py
+++ b/lib/sqlalchemy/sql/events.py
@@ -35,8 +35,9 @@ class DDLEvents(event.Events):
         some_table = Table('some_table', m, Column('data', Integer))
 
         def after_create(target, connection, **kw):
-            connection.execute("ALTER TABLE %s SET name=foo_%s" %
-                                    (target.name, target.name))
+            connection.execute(text(
+                "ALTER TABLE %s SET name=foo_%s" % (target.name, target.name)
+            ))
 
         event.listen(some_table, "after_create", after_create)