- Fixed ORM bug where changing the primary key of an object, then marking

it for DELETE would fail to target the correct row for DELETE.
Then to compound matters, basic "number of rows matched" checks were
not being performed.  Both issues are fixed, however note that the
"rows matched" check requires so-called "sane multi-row count"
functionality; the DBAPI's executemany() method must count up the
rows matched by individual statements and SQLAlchemy's dialect must
mark this feature as supported, currently applies to some mysql dialects,
psycopg2, sqlite only. fixes #3006
- Enabled "sane multi-row count" checking for the psycopg2 DBAPI, as
this seems to be supported as of psycopg2 2.0.9.

1 files changed, 21 insertions, 2 deletions

diff --git a/lib/sqlalchemy/ext/orderinglist.py b/lib/sqlalchemy/ext/orderinglist.py
index 9310c6071..16bab6b29 100644
--- a/lib/sqlalchemy/ext/orderinglist.py
+++ b/lib/sqlalchemy/ext/orderinglist.py
@@ -91,8 +91,27 @@ attribute, so that the ordering is correct when first loaded.
 .. warning::
 
   :class:`.OrderingList` only provides limited functionality when a primary
-  key column or unique column is the target of the sort.  Since changing the
-  order of entries often means that two rows must trade values, this is not
+  key column or unique column is the target of the sort.  The two operations
+  that are unsupported or are problematic are:
+
+    * two entries must trade values.  This is not supported directly in the
+      case of a primary key or unique constraint because it means at least
+      one row would need to be temporarily removed first, or changed to
+      a third, neutral value while the switch occurs.
+
+    * an entry must be deleted in order to make room for a new entry.  SQLAlchemy's
+      unit of work performs all INSERTs before DELETEs within a single flush
+      by default.  A future feature will allow this to be configurable for
+      specific sets of columns on mappings.
+
+  Additional issues when using primary keys as ordering keys are that UPDATE
+  or DELETE statements on target rows may fail to fire correctly as orderinglist
+  may change their primary key value
+
+
+  Since changing the
+  order of entries often means that either rows must trade values,
+  or rows must be deleted to make way for new inserts, this is not
   possible when the value is constrained by a primary key or unique
   constraint, since one of the rows would temporarily have to point to a
   third available value so that the other row could take its old