Skip to main content

Adding a database table

Tables live in data/DB/models.py, access goes through data/DB/Storage/storage.py. Three steps, following the existing pattern.

1. Define the table in models.py​

my_feature = sqlalchemy.Table(
"my_feature", metadata,
sqlalchemy.Column("guild_id", sqlalchemy.String, primary_key=True),
sqlalchemy.Column("data", sqlalchemy.JSON), # flexible JSON blob
sqlalchemy.Column("created_at", sqlalchemy.DateTime,
nullable=False, server_default=func.now()),
timestamp_column(), # auto updated_at
)

Conventions: per-server tables use guild_id as the primary key; other tables use their own keys (profiles is keyed by user_id, voice_xp_users by (guild_id, user_id), friendships by the pair). A data JSON column holds the actual payload so you rarely need migrations — just add keys to the dict. Scalar columns work too (the newer tables use them); either way, a new table is always safe because create_all() creates it on boot — only new columns on existing tables need the manual migration in db.py (see Data layer).

Don't forget to import the table name in storage.py.

2. Add a get/save pair in storage.py​

from data.DB.models import my_feature

async def get_my_feature(guild_id: str):
row = await database.fetch_one(
my_feature.select().where(my_feature.c.guild_id == guild_id))
return row["data"] if row else {}

async def save_my_feature(guild_id: str, data: dict):
await database.execute(_upsert(
my_feature,
{"guild_id": guild_id, "data": data},
))

_upsert() (in storage.py, built on sqlalchemy.dialects.postgresql.insert + ON CONFLICT DO UPDATE) makes save an upsert — no separate "create vs update" logic. For an insert that should silently skip on conflict instead, use _insert_ignore().

3. Use it in a cog​

from data.DB.Storage.storage import get_my_feature, save_my_feature

data = await get_my_feature(str(ctx.guild.id))
data["wins"] = data.get("wins", 0) + 1
await save_my_feature(str(ctx.guild.id), data)

When not to use Postgres​

Short answer: don't reach for JSON for new features. JSON files were the old home for game round state and similar blobs, but those all moved to tables in October 2026 and then to Postgres on 2026-11-12 (see Data layer) — the only standing JSON file is the notification bell's read state. If your data is JSON-shaped and you want the lightest path, follow the store pattern in utils/json_sqlite_store.py (Postgres-backed now, name kept for imports) rather than a new file.