Database - Settings

The datastore setting category is Grim's persistent key/value store. It is not the same thing as config.yml, checks.yml, or database.yml; those files remain normal YAML configuration files.

Settings are currently used for:

• per-player /grim alerts state
• per-player /grim verbose state
• per-player /grim brands state
• internal server-scoped migration state

The default routing sends settings to SQLite:

database:
  routing:
    setting: sqlite

Route setting to a shared backend if staff toggle choices should follow users across multiple Grim instances:

database:
  routing:
    violation: mysql
    session: mysql
    player-identity: mysql
    setting: mysql
    blob: none

Route setting to none only if you do not want these choices persisted. The commands still toggle the in-memory alert manager for the current run, but the datastore-backed preference will not be saved for the next login.

---

Record Shape

Settings are stored as records with:

• scope
• scope_key
• key
• value
• updated_at

The public API exposes three scopes:

• PLAYER - player-specific settings keyed by UUID string.
• SERVER - server/global settings.
• EXTENSION - reserved for extension-owned data.

Current built-in player keys are:

• alerts
• verbose
• brands

These values are stored as bytes. Grim's built-in toggle values are boolean bytes (1 for true, 0 for false).

---

Player Toggle Behavior

On login, Grim asynchronously prefetches the player's alerts, verbose, and brands rows. Permission defaults such as enable-on-join are only applied if no stored value has already won.

When a player runs /grim alerts, /grim verbose, or /grim brands, the in-memory state changes immediately. The database write is coalesced with a short delay, so repeated toggles collapse into the final value. On disconnect or datastore shutdown, pending toggle writes are flushed.

Enabling verbose also persists alerts as enabled, matching the runtime behavior where verbose output implies alerts.

---

Backend Storage Names

The setting category uses the settings storage name from the backend's tables: block. The default is:

tables:
  settings: grim_settings

For SQL backends this is a table name. For MongoDB it is a collection name. For Redis it is part of the key namespace.

Changing table or collection names does not rename existing data. To move data, configure both source and destination backends and use the relevant copy path for supported records.

---

Retention

database.retention.setting is parsed, but the current retention sweeper skips the setting category. Settings persist until overwritten, deleted by a future explicit tool, or removed manually from the backend.

---

API Notes

The storage API is marked experimental. Code that writes settings uses DataStore.submit(Categories.SETTING, ...) with a SettingEvent; reads use DataStore.query(Categories.SETTING, Queries.getSetting(scope, scopeKey, key)).

Keep extension keys namespaced so they cannot collide with Grim's built-in alerts, verbose, and brands player keys.