aurorabot/shared/db/AGENTS.md

Database Layer

Column Types

• Bigint (mode: 'bigint'): All Discord snowflake IDs (userId, guildId, roleId, channelId), currency amounts (balance, xp, transaction amount, item price, inventory quantity). Use 0n BigInt literals, never Number().
• Integer: Small counts and internal IDs — level, daily_streak, progress, reward_amount in lootdrops, auto-increment serial('id') for items.

Composite Primary Keys

• inventory(userId, itemId) — one stack per user per item
• userQuests(userId, questId) — one assignment per user per quest
• userTimers(userId, type, key) — one timer per user per type/key combo

Constraints

• inventory.quantity > 0 check constraint — never store zero-quantity rows
• classes.name and items.name are unique
• Cascade deletes on user FK; set null on relatedUserId (preserves transaction history)

JSON Columns (JSONB)

• quests.requirements: { target: number }
• quests.rewards: { xp?: number, balance?: number }
• gameSettings fields: Typed via .$type<T>() — LevelingConfig, EconomyConfig, etc.
• guildSettings.featureOverrides: Record<string, boolean> (sparse)
• guildSettings.colorRoleIds: string[]
• users.settings, userTimers.metadata, items.usageData: Untyped JSONB, default {}

Enums

Defined as TypeScript enums in shared/lib/constants.ts, not as database enums. Schema columns use varchar with length constraints. Key enum types:

• TimerType: COOLDOWN, EFFECT, ACCESS, EXAM_SYSTEM, TRIVIA_COOLDOWN
• TransactionType: TRANSFER_IN, DAILY_REWARD, etc. (8 values)
• ModerationCaseType: warn, timeout, kick, ban, note, prune
• ItemType: MATERIAL, CONSUMABLE, EQUIPMENT, QUEST

Notable Indexes

• user_timers_lookup_idx: Composite on (userId, type, key) — fast timer checks
• user_timers_expires_at_idx: Expiry-based cleanup queries
• users_balance_idx / users_level_xp_idx: Leaderboard queries

Client Setup

• DrizzleClient is a singleton in shared/db/DrizzleClient.ts (postgres-js driver, no prefetch).
• withTransaction utility in bot/lib/db.ts wraps Drizzle transactions and tracks count for graceful shutdown. Accepts optional existing tx for nested calls.
• No soft deletes anywhere. moderationCases uses active: boolean + resolvedAt/resolvedBy for lifecycle, but rows are never deleted.