- document implicit_returning feature on create_engine()

- add "Triggers" section to MS-SQL docs describing implicit_returning
flag on both Table and create_engine(). [ticket:1994]

diff --git a/lib/sqlalchemy/dialects/mssql/base.py b/lib/sqlalchemy/dialects/mssql/base.py
index 0ef8bd4408d792b33ff6ee488fa8acea17771acf..aa85d47859f501dc82b9f1d89cfa90f3ee84b782 100644 (file)
--- a/lib/sqlalchemy/dialects/mssql/base.py
+++ b/lib/sqlalchemy/dialects/mssql/base.py
@@ -114,6 +114,32 @@ compatibiility level information. Because of this, if running under
 a backwards compatibility mode SQAlchemy may attempt to use T-SQL
 statements that are unable to be parsed by the database server.
 
+Triggers
+--------
+
+SQLAlchemy by default uses OUTPUT INSERTED to get at newly
+generated primary key values via SEQUENCE columns.   MS-SQL does not 
+allow the usage of OUTPUT INSERTED on tables that have triggers.
+To disable the usage of OUTPUT INSERTED on a per-table basis,
+specify ``implicit_returning=False`` to each :class:`.Table`
+which has sequences::
+
+    Table('mytable', metadata, 
+        Column('id', Integer, primary_key=True), 
+        # ...,
+        implicit_returning=False
+    )
+    
+Declarative form::
+
+    class MyClass(Base):
+        # ...
+        __table_args__ = {'implicit_returning':False}
+        
+        
+This option can also be specified enginewide using the
+``implicit_returning=False`` argument on :func:`.create_engine`.
+
 Known Issues
 ------------
 

diff --git a/lib/sqlalchemy/engine/__init__.py b/lib/sqlalchemy/engine/__init__.py
index aebf3543655a671bdd6ba667c8e72bba0734d009..e33dff53bde65204de11327245a6f9c73c8d7d5f 100644 (file)
--- a/lib/sqlalchemy/engine/__init__.py
+++ b/lib/sqlalchemy/engine/__init__.py
@@ -175,6 +175,16 @@ def create_engine(*args, **kwargs):
         be applied to all connections.  See
         :meth:`~sqlalchemy.engine.base.Connection.execution_options`
 
+    :param implicit_returning=True: When ``False``, the RETURNING
+        feature of the database, if available, will not be used 
+        to fetch newly generated primary key values.   This applies
+        to those backends which support RETURNING or a compatible
+        construct, including Postgresql, Firebird, Oracle, Microsoft
+        SQL Server.  The default behavior is to use a compatible RETURNING
+        construct when a single-row INSERT statement is emitted with no 
+        existing returning() clause in order to fetch newly generated 
+        primary key values.
+
     :param label_length=None: optional integer value which limits
         the size of dynamically generated column labels to that many
         characters. If less than 6, labels are generated as