From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Tue, 15 Mar 2016 15:16:21 +0000 (-0400)
Subject: - add notes for pyodbc limitations with rowcount fixes #3675
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=e81857d8dd1e253fa2a9d71e8867a0d5989ceda8;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

- add notes for pyodbc limitations with rowcount fixes #3675

(cherry picked from commit 8bc370ed382a45654101fa34bac4a2886ce089c3)
---

diff --git a/lib/sqlalchemy/dialects/mssql/base.py b/lib/sqlalchemy/dialects/mssql/base.py
index 40bca670ed..544890eadd 100644
--- a/lib/sqlalchemy/dialects/mssql/base.py
+++ b/lib/sqlalchemy/dialects/mssql/base.py
@@ -337,6 +337,40 @@ Declarative form::
 This option can also be specified engine-wide using the
 ``implicit_returning=False`` argument on :func:`.create_engine`.
 
+.. _mssql_rowcount_versioning:
+
+Rowcount Support / ORM Versioning
+---------------------------------
+
+The SQL Server drivers have very limited ability to return the number
+of rows updated from an UPDATE or DELETE statement.  In particular, the
+pymssql driver has no support, whereas the pyodbc driver can only return
+this value under certain conditions.
+
+In particular, updated rowcount is not available when OUTPUT INSERTED
+is used.  This impacts the SQLAlchemy ORM's versioning feature when
+server-side versioning schemes are used.  When
+using pyodbc, the "implicit_returning" flag needs to be set to false
+for any ORM mapped class that uses a version_id column in conjunction with
+a server-side version generator::
+
+    class MyTable(Base):
+        __tablename__ = 'mytable'
+        id = Column(Integer, primary_key=True)
+        stuff = Column(String(10))
+        timestamp = Column(TIMESTAMP(), default=text('DEFAULT'))
+        __mapper_args__ = {
+            'version_id_col': timestamp,
+            'version_id_generator': False,
+        }
+        __table_args__ = {
+            'implicit_returning': False
+        }
+
+Without the implicit_returning flag above, the UPDATE statement will
+use ``OUTPUT inserted.timestamp`` and the rowcount will be returned as
+-1, causing the versioning logic to fail.
+
 Enabling Snapshot Isolation
 ---------------------------
 
diff --git a/lib/sqlalchemy/dialects/mssql/pyodbc.py b/lib/sqlalchemy/dialects/mssql/pyodbc.py
index d901e0ee1c..36905004c1 100644
--- a/lib/sqlalchemy/dialects/mssql/pyodbc.py
+++ b/lib/sqlalchemy/dialects/mssql/pyodbc.py
@@ -110,6 +110,13 @@ for unix + PyODBC.
 .. versionadded:: 0.7.7
     ``supports_unicode_binds`` parameter to ``create_engine()``\ .
 
+Rowcount Support
+----------------
+
+Pyodbc only has partial support for rowcount.  See the notes at
+:ref:`mssql_rowcount_versioning` for important notes when using ORM
+versioning.
+
 """
 
 from .base import MSExecutionContext, MSDialect