From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Sat, 8 Jan 2011 21:05:09 +0000 (-0500)
Subject: - document implicit_returning feature on create_engine()
X-Git-Tag: rel_0_6_6~1
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=4993c7eae8e5d117ff342bdc59f3b0635b898e2c;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

- 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 0ef8bd4408..aa85d47859 100644
--- 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 aebf354365..e33dff53bd 100644
--- 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