The bug that only shows up under load
A weekly digest sounds like the easiest scheduled job you could write: once a week, loop over admins, send an email. Then you run two backend replicas behind a load balancer, both on the same clock, and both wake up in the same minute to check "is it Monday 8am yet?" Both say yes. Both send.
Nobody notices this in development, because development has one process. It shows up the first week you scale past one instance — an admin gets the same digest twice, three minutes apart, and asks support if something's broken.
Why a boolean flag doesn't fix it
The instinctive fix is a flag: check alreadySent, and if not, set it and send. That works fine until two requests read the flag at the same moment — before either has written true back. Both see "not sent yet." Both send. The flag was never wrong; the check-then-act sequence just isn't atomic, and no amount of adding more flags fixes a race condition made of two separate steps.
The actual fix: let the database refuse the duplicate
WKFGo's digest table has a unique index on (org_id, week_key), where week_key is the ISO year-week, like 2026-W28. Sending a digest means inserting a row first, then building the email:
if err := s.db.Create(&Send{OrgID: orgID, WeekKey: weekKey, ...}).Error; err != nil {
// unique violation → this week's digest was already sent (or raced)
return 0, nil
}
If two replicas race, the database serializes the two INSERTs. One succeeds and proceeds to build and send the email. The other gets a unique-constraint violation and returns immediately, no email built, no email sent. There's no window where both check and both pass — the check is the write, and the database only allows one of those writes to succeed.
This is the same principle as an idempotency key on a payment API: don't ask "has this happened?" and then act — try to record that it happened, and let the storage layer be the referee.
Why this generalizes
Any "send this exactly once" problem has the same shape: a reminder email, a webhook delivery, a recurring task materializing (see [Recurring tasks that don't leave duplicates](/blog/recurring-tasks-without-duplicates) for the same idea applied to task creation). The fix is never "check more carefully" — it's making the record of "this happened" the same operation as the thing that's only supposed to happen once, backed by a constraint the database enforces regardless of how many processes are asking at the same moment.
What still needs application logic
The unique constraint stops duplicate sends. It doesn't decide who gets a digest, or what a manual out-of-schedule resend looks like. WKFGo handles the second case with a distinguishable key — a forced resend uses a manual-<timestamp> week key instead of the real ISO week, so it can't collide with (and doesn't block) the following week's scheduled send.
Common mistakes
Deduping in the email provider instead of your own table. Some SMTP relays offer "suppress duplicate content" features. They key on subject/body hashing, which breaks the moment you personalize the email per recipient.
Using SELECT then INSERT as two statements. This reintroduces the exact race you were trying to close — the gap between the read and the write is where two replicas both slip through.
Forgetting the index needs to be unique, not just present. A regular (non-unique) index on (org_id, week_key) speeds up lookups but enforces nothing; only a unique index makes the second INSERT fail.
FAQ
What if the send partially fails — row inserted, but SMTP times out?
The row stays inserted (send is considered "claimed"), and the email delivery itself goes through WKFGo's existing retry queue, which is separate from the dedupe check. A claimed-but-undelivered week doesn't silently retry as a duplicate next tick — that's the tradeoff of "at most once" over "at least once," and it's the right one for a digest email.
Does this need a separate cron per replica?
No — every replica runs the same ticker and every replica attempts the same insert; the constraint decides which one wins. No leader election needed for this particular guarantee (WKFGo does still use leader election for other singleton jobs like recycle-bin cleanup, so only one replica attempts most background work — this dedupe is the backstop for the one job cheap enough to let every replica try).
Can an admin opt out?
Yes, weekly_digest is a per-user boolean; the recipient query filters on it before any of this dedupe logic runs.
Summary
If you're building a "make sure this only happens once" feature, don't reach for a flag and a check — reach for a unique constraint and an insert. The database was built to arbitrate exactly this kind of race, and it does it in one atomic step instead of two racy ones.