aurorabot/shared/db/AGENTS.md

Database layer

Aurora uses Drizzle ORM with PostgreSQL. Docker Compose currently runs PostgreSQL 17.

Schema modules

• users.ts
• inventory.ts
• economy.ts
• quests.ts
• moderation.ts
• feature-flags.ts
• guild-settings.ts
• game-settings.ts

shared/db/schema/index.ts re-exports the full schema surface.

Numeric conventions

• Discord IDs, balances, XP, quantities, and transaction amounts are stored as bigint
• many API responses serialize those bigint values to strings
• JSON config blobs inside game_settings use strings for values that become bigint at runtime, for example:
  • economy.daily.amount
  • economy.daily.streakBonus
  • economy.daily.weeklyBonus
  • economy.transfers.minAmount
  • inventory.maxStackSize
  • trivia.entryFee

Important tables

• users
• classes
• transactions
• item_transactions
• items
• inventory
• quests
• user_quests
• user_timers
• moderation_cases
• lootdrops
• feature_flags
• feature_flag_access
• guild_settings
• game_settings

Composite keys and constraints

• inventory(userId, itemId)
• userQuests(userId, questId)
• userTimers(userId, type, key)
• inventory.quantity > 0
• items.name is unique
• feature_flags.name is unique

JSON columns

• items.usageData
• users.settings
• userTimers.metadata
• quests.requirements
• quests.rewards
• guildSettings.colorRoleIds
• guildSettings.featureOverrides
• every main section in gameSettings

Relations and deletion behavior

• inventory rows cascade on user/item deletion
• transactions.relatedUserId and item_transactions.relatedUserId use set null
• feature flag access rows cascade when a feature flag is deleted
• moderation cases are not soft-deleted; lifecycle is represented by active, resolvedAt, and resolvedBy

Client setup

• shared/db/DrizzleClient.ts exports the singleton DB client
• bot/lib/db.ts exports withTransaction()
• shared services normally accept an optional existing transaction so nested operations stay atomic