orion/docs/getting-started/database-quick-reference.md

Database Quick Reference Card

Quick reference for common database operations. See DATABASE_SETUP_GUIDE.md for detailed instructions.

---

🚀 Quick Start (New Developer)

# 1. Clone and setup
git clone <orion-repo>
cd orion-repo
python -m venv venv
venv\Scripts\activate  # Windows
pip install -r requirements.txt

# 2. Initialize database
alembic upgrade head
python scripts/seed_database.py

# 3. Start server
python -m uvicorn app.main:app --reload

# 4. Login
# http://localhost:8000/admin/login
# Username: admin | Password: admin123

---

🔄 Reset Database (Clean Slate)

Windows:

.\scripts\reset_database.ps1

Linux/Mac:

./scripts/reset_database.sh

Manual:

# 1. Delete migrations
Remove-Item alembic\versions\*.py -Exclude __init__.py

# 2. Delete database
Remove-Item orion.db

# 3. Regenerate
alembic revision --autogenerate -m "Initial migration"
alembic upgrade head
python scripts/seed_database.py

---

📝 Creating Migrations

# After modifying models in models/database/

# 1. Generate migration
alembic revision --autogenerate -m "Add field to store_themes"

# 2. Review the file
# Check: alembic/versions/<id>_add_field_to_store_themes.py

# 3. Apply migration
alembic upgrade head

---

🔍 Checking Status

# Current migration version
alembic current

# Migration history
alembic history --verbose

# List all tables
python -c "import sqlite3; conn = sqlite3.connect('orion.db'); cursor = conn.cursor(); cursor.execute('SELECT name FROM sqlite_master WHERE type=\"table\" ORDER BY name;'); [print(t[0]) for t in cursor.fetchall()]"

# Check specific table
python -c "import sqlite3; conn = sqlite3.connect('orion.db'); cursor = conn.cursor(); cursor.execute('PRAGMA table_info(store_themes)'); [print(col) for col in cursor.fetchall()]"

---

⬆️ Upgrading Database

# Upgrade to latest
alembic upgrade head

# Upgrade one version
alembic upgrade +1

# Upgrade to specific revision
alembic upgrade <revision_id>

---

⬇️ Rolling Back

# Downgrade one version
alembic downgrade -1

# Downgrade to specific revision
alembic downgrade <revision_id>

# Downgrade to empty database
alembic downgrade base

---

🌱 Seeding Data

# Seed development data
python scripts/seed_database.py

# Manual seed (Python shell)
python
>>> from scripts.seed_database import seed_database
>>> seed_database()

---

🐛 Common Fixes

"No such table" Error

# Check model imported in alembic/env.py
# Then regenerate:
alembic revision --autogenerate -m "Add missing table"
alembic upgrade head

"Database locked"

# Stop server
taskkill /F /IM python.exe  # Windows
pkill python                # Linux/Mac

# Try again
alembic upgrade head

"Target database not up to date"

alembic stamp head
alembic upgrade head

"Multiple head revisions"

alembic merge heads -m "Merge migrations"
alembic upgrade head

---

📦 Adding New Models

Checklist:

# 1. Create model file
# models/database/my_model.py

# 2. Import in alembic/env.py
# from models.database.my_model import MyModel

# 3. Generate migration
alembic revision --autogenerate -m "Add MyModel table"

# 4. Review migration file
# alembic/versions/<id>_add_mymodel_table.py

# 5. Apply migration
alembic upgrade head

# 6. Test
python -c "from models.database.my_model import MyModel; print('✓ Import works')"

---

🔗 Important Files

├── alembic/
│   ├── env.py              ← Import ALL models here!
│   └── versions/           ← Migration files
├── app/core/
│   └── database.py         ← Database connection
├── models/database/        ← SQLAlchemy models
├── scripts/
│   ├── seed_database.py    ← Seed script
│   └── reset_database.ps1  ← Reset script
├── alembic.ini             ← Alembic config
└── orion.db            ← SQLite database

---

🆘 Getting Help

1. Check full guide: docs/DATABASE_SETUP_GUIDE.md
2. Check Alembic docs: https://alembic.sqlalchemy.org/
3. Ask team lead

---

⚠️ Important Notes

• ✅ Always review migrations before applying
• ✅ Test on local database first
• ✅ Keep migrations in version control
• ✅ Backup before destructive operations
• ❌ Never edit applied migrations
• ❌ Never delete migration files

---

Last Updated: 2025-10-27