Skip to main content

​
Overview

The Setting model provides a simple key-value store for application configuration data. It’s used internally by the system to persist settings like the master code hash, theme preferences, and other configuration options.
This model is primarily used by internal services. Most settings should be managed through the admin interface rather than direct database access.

​
Database Schema

data/models/setting.py
from sqlalchemy import String, Text
from sqlalchemy.orm import Mapped, mapped_column
from data.db.base import Base

class Setting(Base):
    __tablename__ = "settings"

    key: Mapped[str] = mapped_column(String(60), primary_key=True)
    value: Mapped[str] = mapped_column(Text)

​
Fields

​
key
str
required
Setting identifier (primary key)Max length: 60 charactersCommon keys:
  • MASTER_CODE_HASH - Hashed master code for assistant elevation
  • theme - UI theme preference (light/dark)
  • last_backup_at - Timestamp of last automatic backup
​
value
str
required
Setting value stored as textValues can be strings, JSON, timestamps, or hashed passwords depending on the key.

​
Usage Examples

​
Reading Settings

from data.db.session import SessionLocal
from data.models.setting import Setting

db = SessionLocal()
setting = db.query(Setting).filter(Setting.key == "theme").first()
if setting:
    theme = setting.value
    print(f"Current theme: {theme}")
db.close()

​
Writing Settings

from data.db.session import SessionLocal
from data.models.setting import Setting

db = SessionLocal()

# Update or create setting
setting = db.query(Setting).filter(Setting.key == "theme").first()
if setting:
    setting.value = "dark"
else:
    setting = Setting(key="theme", value="dark")
    db.add(setting)

db.commit()
db.close()

​
Used By

The Setting model is accessed by:
  • Permissions Service - Stores and validates master code hash
  • Theme Management - Persists user theme preferences
  • Backup Service - Tracks last backup timestamp
Never store sensitive data like passwords in plain text. Always use proper hashing (bcrypt) for security-sensitive values like MASTER_CODE_HASH.

​
Database Operations

​
Get Setting Value

def get_setting(key: str) -> str | None:
    """Retrieve a setting value by key."""
    db = SessionLocal()
    try:
        setting = db.query(Setting).filter(Setting.key == key).first()
        return setting.value if setting else None
    finally:
        db.close()

​
Set Setting Value

def set_setting(key: str, value: str) -> None:
    """Create or update a setting."""
    db = SessionLocal()
    try:
        setting = db.query(Setting).filter(Setting.key == key).first()
        if setting:
            setting.value = value
        else:
            setting = Setting(key=key, value=value)
            db.add(setting)
        db.commit()
    finally:
        db.close()

​
Related Documentation

Permissions Service

Master code storage and validation

Admin Role

Admin settings management capabilities

Build docs developers (and LLMs) love

Get started for freeTalk to us