Measure before splitting the bot
Slow commands can come from database queries, a busy event loop, a large cache, or an external API. More processes only help if they address the actual limit. Record command latency, memory use, CPU, query time, and queue age during a busy period.
| Symptom | Check first | Possible change |
|---|---|---|
| Memory grows over time | Unbounded caches and retained objects | Cap caches and investigate leaks |
| Heartbeats are late | Synchronous or CPU-heavy work | Move that work to a worker |
| Commands wait on the database | Query plans and connection count | Add an index or reduce queries |
| Jobs fall behind | Arrival rate and job duration | Add bounded worker capacity |
| Gateway workload is too large | Discord’s shard recommendation | Distribute guilds across shards |
Keep slow jobs away from event handling
Acknowledge the request
Validate input and permissions. If an interaction needs more time, defer its response before doing slow work.Queue a small job
Include identifiers and the necessary inputs. Avoid placing tokens or entire message histories in the queue.Process with a worker
Use timeouts and bounded concurrency. Make repeated delivery safe with a unique job or operation ID.Save and report the result
Persist the outcome before notifying the user. Plan a fallback for jobs that outlive the interaction token.
A durable queue can survive a process restart, but jobs may still be delivered more than once. Design purchases, rewards, and scheduled posts so retrying does not repeat the side effect.
Keep caches bounded and replaceable
Cache frequently read settings when it reduces real database load. Give entries a size limit and expiry, and invalidate them when settings change. A cache miss should have a safe path back to durable storage.
Local cache
Shared cache
Coalesce simultaneous reads for the same missing key so one expiry does not trigger hundreds of identical queries. Add a little variation to expiry times when many entries are created together.
keep this durable
Purchases and balances belong in the database.
A cache can speed up an entitlement check. It should not be the only record that someone paid or that credits were transferred.
Change one boundary at a time
- Keep database connection totals within the server’s limit as workers increase.
- Use structured logs with shard, job, and release IDs.
- Test a worker crash, a cache outage, and duplicate job delivery.
- Make migrations compatible with both versions during a rollout.
- Write a rollback plan before moving data between databases.
Database sharding adds routing, migration, and cross-shard query work. Consider indexes, smaller queries, and archiving before taking it on. See the database guide for the starting choices.