Discord bot reminders that fire exactly once, with natural time parsing
Krypton's remind command: parsing 'tomorrow at 9am' and 'in 2h30m' in each user's time zone, limits under an advisory lock, and an atomic claim so no cluster or deploy ever sends a reminder twice.
Krypton had no reminders at all. Adding them looked simple until two requirements met: people type times like humans, and the bot runs as several processes that restart during deploys. A reminder must arrive once, not zero times and not twice.
Parsing human time
The parser accepts what people actually write:
- Relative:
in 6 minutes,in 2h30m,in an hour and 30 minutes,in 2 months. - Clock times and dates:
at 5pm,tomorrow at 9 AM,tonight,next monday,on friday at 18:00,on 25 dec,2026-12-25 10:00. - Either order: "to study tomorrow at 9am" works as well as "tomorrow at 9am to study".
- Bare hours pick the next occurrence, so "at 5" in the afternoon means 17:00, not 05:00 tomorrow.
Time zones
"At 9am" means nothing without a zone. Each user sets theirs once, as an IANA name, a city, a common abbreviation or an offset like UTC+5:30, and it is shared with the premium bot and the dashboard. Clock times default to UTC, and every confirmation says which zone was used, so a wrong assumption is visible immediately rather than at the wrong time.
Limits without races
Each user can have 25 pending reminders, from one minute to one year ahead, up to 1,000 characters. The count is enforced under a per-user PostgreSQL advisory lock: without it, two commands at the same moment could both see 24 and both insert.
Delivering exactly once
Reminders are stored in PostgreSQL, so they survive restarts. Before sending, a process claims one atomically:
UPDATE reminders SET claimed_at = now()
WHERE id = ANY($1::bigint[]) AND claimed_at IS NULL
RETURNING *;Only one process can turn NULL into a time, so only one sends. Two clusters, or an old and a new process overlapping during a deploy, can never both deliver it. After sending, the row is deleted; if sending fails, the claim is released and an attempt counter goes up, so it is retried later rather than lost. Each cluster only looks at reminders for servers on its own shards.
Where reminders arrive
In the channel where the reminder was set, pinging only its owner. The bot never DMs. Setting a reminder is refused in channels where the bot cannot post, so it never accepts a reminder it would be unable to deliver. The claim pattern is one of several in PostgreSQL patterns for multi-process bots.
