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)

```bash
# 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:**
```powershell
.\scripts\reset_database.ps1
```

**Linux/Mac:**
```bash
./scripts/reset_database.sh
```

**Manual:**
```bash
# 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

```bash
# 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

```bash
# 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

```bash
# Upgrade to latest
alembic upgrade head

# Upgrade one version
alembic upgrade +1

# Upgrade to specific revision
alembic upgrade <revision_id>
```

---

## ⬇️ Rolling Back

```bash
# Downgrade one version
alembic downgrade -1

# Downgrade to specific revision
alembic downgrade <revision_id>

# Downgrade to empty database
alembic downgrade base
```

---

## 🌱 Seeding Data

```bash
# 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
```bash
# Check model imported in alembic/env.py
# Then regenerate:
alembic revision --autogenerate -m "Add missing table"
alembic upgrade head
```

### "Database locked"
```bash
# Stop server
taskkill /F /IM python.exe  # Windows
pkill python                # Linux/Mac

# Try again
alembic upgrade head
```

### "Target database not up to date"
```bash
alembic stamp head
alembic upgrade head
```

### "Multiple head revisions"
```bash
alembic merge heads -m "Merge migrations"
alembic upgrade head
```

---

## 📦 Adding New Models

**Checklist:**

```bash
# 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