Skip to content
Tutorials Center
My learning

Topics

Lesson 21 of 37 ยท State and Storage

Per-User and Per-Guild Settings

Build a settings service for Discord and Telegram bots: defaults, validation, SQLite persistence, a write-through cache and a /settings command handler.

Most serious bots are configurable. A Discord server wants its own command prefix and log channel; a Telegram user wants replies in their language and a daily reminder at their time zone. That means one small piece of code that reads and writes settings safely, with sensible defaults, validation and a cache.

This lesson builds that piece as a reusable SettingsStore on top of the SQLite pattern from the previous lesson. You will reuse it in the projects at the end of this track.

Scopes: who owns a setting?

Decide the scope before the table:

Scope Key Examples
Global none maintenance mode, version message
Guild or chat guild ID or chat ID prefix, welcome channel, language
User user ID time zone, notification opt-out
Member guild ID + user ID nickname color, per-server XP display

One table with a scope and an owner_id column handles all of them, so you write the code once.

SQL
CREATE TABLE settings (
  scope    TEXT NOT NULL,      -- 'guild' | 'user' | 'chat'
  owner_id TEXT NOT NULL,
  key      TEXT NOT NULL,
  value    TEXT NOT NULL,      -- JSON encoded
  PRIMARY KEY (scope, owner_id, key)
);

A schema of allowed settings

Never accept arbitrary keys from user input. Declare every setting once, with its default and a validator. The same declaration drives the /settings command, the help text and the checks.

Node.js Declare settings with defaults and validators

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Validate with allow-lists, not deny-lists. For IDs a pattern like ^\d{5,20}$ rejects mentions, links and anything else a user might paste.

The settings store

Now the store: SQLite for durability, a Map as a cache in front of it. Reads hit the cache; writes go to the database first and then update the cache. This is called write-through.

Node.js SettingsStore with a write-through cache

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

One database read per guild, no matter how many commands run. That is what makes the cache valuable: a busy guild may issue thousands of commands an hour.

The cache has to be bounded in a real bot. Use the Lru class from bot state in memory for the #cache field so inactive guilds fall out.

A /settings command handler

The store knows nothing about Discord or Telegram. A thin handler translates a command into store calls. Here it is with a Telegram-style update; the Discord version differs only in where the text and the permission info come from.

Node.js A /set command with permission and validation

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Order matters: check permission first, then shape, then validity. Each failure returns a helpful message and changes nothing.

Defaults that adapt

Two habits save pain later:

  • Store only what the user changed. Rows for defaults make it impossible to roll out a better default.
  • Include a reset action that deletes the row, so the setting falls back to the current default.

On Discord, remember that a guild may remove your bot and add it again months later. Decide whether to delete its settings on guildDelete (privacy-friendly) or keep them for a grace period (user-friendly). State your choice in the bot's privacy text.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why declare a settings schema instead of accepting any key?

    A schema is the single source of truth: allowed keys, scope, default and validator.
  2. 2. What does a write-through cache do on set()?

    The database stays the source of truth, and the cache is updated so the next read is correct and fast.
  3. 3. Why store only values the user changed?

    If a default is not stored, changing it in code instantly applies to everyone who never touched the setting.
  4. 4. In handleSet, why is the admin check first?

    Authorization comes before parsing details or revealing which keys exist, and it fails fast.

Summary

  • Choose a scope (global, guild/chat, user, member) and one table for all of them.
  • Declare each setting with a scope, default and allow-list validator.
  • Put a bounded cache in front of the database and write through on change.
  • Handlers check permission, shape and validity in that order and change nothing on failure.
  • Store only overrides so defaults can improve and reset is just a delete.

Next: Conversation state and multi-step dialogs