Skip to content

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.

3 min read

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:

sql
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.

Illustrated avatar of Kumar Manas

Written by Kumar Manas

Full-stack developer in India. I build Melodius and Krypton.

Related projectKrypton: discord security bot