Add deadlock warning to 'effective neutron'

Change-Id: Iaf9bd0b5d84ecb4f4de406e632c0d05327621bcb

diff --git a/doc/source/devref/effective_neutron.rst b/doc/source/devref/effective_neutron.rst
index 98bf8e9fb68138d33016623cf294f793c54d2a61..785859bf8fd9abdcea488a746b9560ec15e0b472 100644 (file)
--- a/doc/source/devref/effective_neutron.rst
+++ b/doc/source/devref/effective_neutron.rst
@@ -77,6 +77,12 @@ Eventlet concurrent model
 Document common pitfalls as well as good practices done when using eventlet and monkey
 patching.
 
+* Do not use with_lockmode('update') on SQL queries without protecting the operation
+  with a lockutils semaphore. For some SQLAlchemy database drivers that operators may
+  choose (e.g. MySQLdb) it may result in a temporary deadlock by yielding to another
+  coroutine while holding the DB lock. The following wiki provides more details:
+  https://wiki.openstack.org/wiki/OpenStack_and_SQLAlchemy#MySQLdb_.2B_eventlet_.3D_sad
+
 Mocking and testing
 ~~~~~~~~~~~~~~~~~~~