Initial Setup Guide

This page is the developer-focused follow-up to the main self-hosting guide.

For base installation, environment variables, production service setup, and PostgreSQL setup scripts, start here:

This page focuses on what developers should do differently after base setup is complete.

Current Database Architecture

Vör currently runs mixed backends:

  • SQLite for some legacy modules.
  • PostgreSQL for most modules (economy, moderation, bot-level config, Message Forensics, RPG), namespaced via per-module schemas in the single vor_data_primary database — see core/models/pg_engines.py.

If your local Postgres role/database exists but the bot fails to start with InvalidSchemaNameError: no schema has been selected to create in, the schemas haven’t been created yet — run scripts/create_pg_schemas.sql (see the Self Hosting Guide).

Developer Workflow Setup

After finishing Self Hosting setup:

# from repo root
python -m venv .venv

# Windows
.venv\Scripts\activate
# Linux/macOS
source .venv/bin/activate

pip install -r requirements.txt

Required Developer Checks

Before coding on MessageLogger or forensic models:

  1. Confirm PostgreSQL credentials are set in bot_config/.env (VOR_DATA_PG_*).
  2. Confirm the PostgreSQL database exists (vor_data_primary), the role can connect (vor_db_role), and the economy/moderation/bot/forensics schemas exist (scripts/create_pg_schemas.sql).
  3. Confirm bot startup can create tables without manual SQL migrations.

Local Iteration Tips

Fast Bot Restart Cycle

Use cog reloads where possible for non-model changes:

  • /vor_admin reload_cog MessageLogger

For model / table-definition changes, do a full restart.

Forensics Testing Pattern

Use a dedicated test guild/channel and generate controlled delete bursts to validate:

  • raw delete ingestion
  • incident creation thresholds
  • confidence updates
  • alert routing and permissions

No Data Migration in This Phase

Existing SQLite forensic data is intentionally not migrated. If you need a clean test state, use the purge commands and recreate test data.

Troubleshooting for Developers

PostgreSQL Connection Failures

  • Verify VOR_DATA_PG_HOST, VOR_DATA_PG_PORT, VOR_DATA_PG_DATABASE, VOR_DATA_PG_USER, VOR_DATA_PG_PASSWORD.
  • Confirm PostgreSQL service is running.
  • Confirm firewall/network allows local or remote DB access.

Table Creation or Schema Drift Issues

  • Restart bot after model changes.
  • Check startup logs from DatabaseHandler.setup.
  • If you changed table shape significantly, coordinate a manual migration plan rather than relying on automatic column-add behavior.

Mixed Backend Confusion

  • If an issue is in Message Forensics, inspect PostgreSQL first.
  • If an issue is in older cogs/modules, inspect corresponding SQLite files.

Suggested Next Developer Tasks

  1. Reduce forensic write amplification in MessageLogger under burst load.
  2. Add write serialization / queueing for forensics ingestion path.
  3. Instrument per-path write latency and lock wait metrics for future migration decisions.