document autocommit when using the compiler extension, update the "understanding autocommit" section

1 files changed, 49 insertions, 0 deletions

diff --git a/lib/sqlalchemy/ext/compiler.py b/lib/sqlalchemy/ext/compiler.py
index 7b0837741..cb126c374 100644
--- a/lib/sqlalchemy/ext/compiler.py
+++ b/lib/sqlalchemy/ext/compiler.py
@@ -91,6 +91,11 @@ Produces::
 
     "INSERT INTO mytable (SELECT mytable.x, mytable.y, mytable.z FROM mytable WHERE mytable.x > :x_1)"
 
+.. note:: 
+
+   The above ``InsertFromSelect`` construct probably wants to have "autocommit" 
+   enabled.  See :ref:`enabling_compiled_autocommit` for this step.
+
 Cross Compiling between SQL and DDL compilers
 ---------------------------------------------
 
@@ -106,6 +111,50 @@ constraint that embeds a SQL expression::
             ddlcompiler.sql_compiler.process(constraint.expression)
         )
 
+.. _enabling_compiled_autocommit:
+
+Enabling Autocommit on a Construct
+==================================
+
+Recall from the section :ref:`autocommit` that the :class:`.Engine`, when asked to execute
+a construct in the absence of a user-defined transaction, detects if the given
+construct represents DML or DDL, that is, a data modification or data definition statement, which 
+requires (or may require, in the case of DDL) that the transaction generated by the DBAPI be committed
+(recall that DBAPI always has a transaction going on regardless of what SQLAlchemy does).   Checking 
+for this is actually accomplished
+by checking for the "autocommit" execution option on the construct.    When building a construct like
+an INSERT derivation, a new DDL type, or perhaps a stored procedure that alters data, the "autocommit" 
+option needs to be set in order for the statement to function with "connectionless" execution
+(as described in :ref:`dbengine_implicit`).
+
+Currently a quick way to do this is to subclass :class:`.Executable`, then add the "autocommit" flag
+to the ``_execution_options`` dictionary (note this is a "frozen" dictionary which supplies a generative
+``union()`` method)::
+
+    from sqlalchemy.sql.expression import Executable, ClauseElement
+
+    class MyInsertThing(Executable, ClauseElement):
+        _execution_options = \\
+            Executable._execution_options.union({'autocommit': True})
+
+More succinctly, if the construct is truly similar to an INSERT, UPDATE, or DELETE, :class:`.UpdateBase`
+can be used, which already is a subclass of :class:`.Executable`, :class:`.ClauseElement` and includes the
+``autocommit`` flag::
+
+    from sqlalchemy.sql.expression import UpdateBase
+
+    class MyInsertThing(UpdateBase):
+        def __init__(self, ...):
+            ...
+        
+        
+    
+
+DDL elements that subclass :class:`.DDLElement` already have the "autocommit" flag turned on.
+
+    
+
+
 Changing the default compilation of existing constructs
 =======================================================