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

1 files changed, 22 insertions, 22 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