Mike Bayer committed 0f14385

document CircularDependencyError. [ticket:2285]

Comments (0)

Files changed (4)


 be two individual foreign key constraints instead of a single composite
 foreign key referencing two columns.
+.. _use_alter:
 Creating/Dropping Foreign Key Constraints via ALTER


           'New York')),
+.. _post_update:
 Rows that point to themselves / Mutually Dependent Rows


 class CircularDependencyError(SQLAlchemyError):
-    """Raised by topological sorts when a circular dependency is detected"""
+    """Raised by topological sorts when a circular dependency is detected.
+    There are two scenarios where this error occurs:
+    * In a Session flush operation, if two objects are mutually dependent
+      on each other, they can not be inserted or deleted via INSERT or 
+      DELETE statements alone; an UPDATE will be needed to deassociate
+      one of the foreign key constraints first.  The ``post_update`` flag
+      described at :ref:`post_update` can resolve this cycle.
+    * In a :meth:`.MetaData.create_all`, :meth:`.MetaData.drop_all`,
+      :attr:`.MetaData.sorted_tables` operation, two :class:`.ForeignKey`
+      or :class:`.ForeignKeyConstraint` objects mutually refer to each
+      other.  Apply the ``use_alter=True`` flag to one or both,
+      see :ref:`use_alter`.
+    """
     def __init__(self, message, cycles, edges):
-        message += ": cycles: %r all edges: %r" % (cycles, edges)
+        message += " Cycles: %r all edges: %r" % (cycles, edges)
         SQLAlchemyError.__init__(self, message)
         self.cycles = cycles
         self.edges = edges


         if not output:
             raise CircularDependencyError(
-                    "Circular dependency detected",
+                    "Circular dependency detected.",
                     find_cycles(tuples, allitems),