From e254ed41d2fa310bc4fdec7351df3bbfe9b9eb9a Mon Sep 17 00:00:00 2001
From: Isaac Connor <isaac@zoneminder.com>
Date: Sat, 16 May 2026 22:44:14 -0400
Subject: [PATCH] docs: expand triggers.sql lock-order block with full writer
 list

Adds zm_event.cpp's create path (Events INSERT -> bucket INSERTs ->
Event_Summaries UPDATE; event_insert_trigger itself is commented out so
zmc does this directly), and lists zmaudit.pl alongside zmstats.pl, so
the comment enumerates every writer obligated to follow the canonical
order rather than just the trigger paths.
---
 db/triggers.sql | 29 ++++++++++++++++++++---------
 1 file changed, 20 insertions(+), 9 deletions(-)

diff --git a/db/triggers.sql b/db/triggers.sql
index 774ead5d1..2da2b1ab3 100644
--- a/db/triggers.sql
+++ b/db/triggers.sql
@@ -117,16 +117,27 @@ FOR EACH ROW
 drop procedure if exists update_storage_stats//
 
 /* ============================================================================
- * Lock-acquisition order for the Events update/delete triggers (and for the
- * scripts that touch the same tables). InnoDB X-locks the matched Events row
- * during WHERE evaluation, before either BEFORE or AFTER trigger bodies fire,
- * so the order is the same regardless of trigger timing:
+ * Canonical lock-acquisition order for every writer that touches Events,
+ * the bucket tables, and Event_Summaries. InnoDB X-locks the matched Events
+ * row during WHERE evaluation, before either BEFORE or AFTER trigger bodies
+ * fire, so the order is the same regardless of trigger timing:
+ *
  *   Events[Id] -> Events_Hour/Day/Week/Month[EventId] -> Event_Summaries[MonitorId]
- * zmstats.pl prune+resync follows the matching prefix (bucket DELETEs then
- * UPDATE Event_Summaries) and crucially does NOT pre-lock Event_Summaries —
- * pre-locking ES would invert against the trigger body order and reintroduce
- * deadlocks against filter / zma writers. The bucket update/delete triggers
- * also propagate into Event_Summaries[MonitorId] in the same direction.
+ *
+ * Writers that follow this order (and must continue to):
+ *   - event_update_trigger (AFTER UPDATE on Events)
+ *   - event_delete_trigger (BEFORE DELETE on Events)
+ *   - src/zm_event.cpp Event::createNotification path: INSERT Events, then
+ *     INSERT Events_Hour/Day/Week/Month, then INSERT/UPDATE Event_Summaries
+ *     (event_insert_trigger is commented out below; zmc does it directly)
+ *   - The bucket update/delete triggers cascade into Event_Summaries in the
+ *     same direction
+ *   - zmstats.pl prune+resync (bucket DELETEs then UPDATE Event_Summaries)
+ *   - zmaudit.pl resync (bucket SELECTs then UPDATE Event_Summaries)
+ *
+ * Crucially: do NOT pre-lock Event_Summaries before touching the bucket
+ * tables — that inverts the order and reintroduces the deadlock cycle
+ * against zma/filter/zmc writers.
  * ============================================================================ */
 drop trigger if exists event_update_trigger//