orion/docs/getting-started/database-setup.md

Database Setup Guide

This guide will help new team members set up and understand the database system used in this project.

Quick Setup (New Team Members)

After cloning the repository, follow these steps to get your database ready:

1. Install Dependencies

# Install all dependencies including Alembic
make install-all

2. Set Up Environment

# Copy the example environment file
cp .env.example .env

# Edit .env with your database configuration
# For development, you can use SQLite:
DATABASE_URL=sqlite:///./ecommerce.db

# For PostgreSQL (recommended for production-like development):
# DATABASE_URL=postgresql://username:password@localhost:5432/ecommerce_dev

3. Run Database Migrations

# Apply all migrations to create the database schema
make migrate-up

4. Verify Setup

# Check that everything is working
make verify-setup

5. Start Development

# Start the development server
make dev

Understanding Our Database System

What is Alembic?

Alembic is a database migration tool that helps us:

• Version control our database schema - Every database change is tracked
• Share schema changes with the team - When you pull code, you get database updates too
• Deploy safely - Production deployments include database updates
• Roll back if needed - We can undo problematic database changes

Key Concepts

Migrations: Files that describe how to change the database schema

• Located in alembic/versions/
• Each migration has a unique ID and timestamp
• Migrations run in order to build up the complete schema

Migration Status: Alembic tracks which migrations have been applied

• alembic current - Shows the current migration
• alembic history - Shows all available migrations

Daily Workflow

When You Pull Code

# After pulling changes from git, check for new migrations
make migrate-status

# If there are pending migrations, apply them
make migrate-up

When Working with Models

# After modifying SQLAlchemy models, create a migration
make migrate-create message="add_user_profile_table"

# Review the generated migration file in alembic/versions/
# Then apply it
make migrate-up

Common Scenarios

First Time Setup

make setup  # This handles everything automatically

Database is Out of Sync

# Check current status
make migrate-status

# Apply any missing migrations
make migrate-up

Something Went Wrong

# Create a backup first
make backup-db

# Check what migrations are available
make migrate-status

# If you need to rollback the last migration
make migrate-down

Starting Fresh (Development Only)

# Backup first (just in case)
make backup-db

# Delete database and recreate from scratch
del ecommerce.db  # or drop PostgreSQL database
make migrate-up

Environment-Specific Setup

Development (SQLite)

DATABASE_URL=sqlite:///./ecommerce.db

• Quick setup, no additional software needed
• File-based database, easy to backup/restore
• Good for local development and testing

Development (PostgreSQL)

DATABASE_URL=postgresql://user:password@localhost:5432/ecommerce_dev

• More production-like environment
• Better for testing complex queries
• Required for certain advanced features

Production

DATABASE_URL=postgresql://user:password@production-host:5432/ecommerce_prod

• Always use PostgreSQL in production
• Migrations are applied automatically during deployment

Troubleshooting

"No module named 'models'"

# Make sure you're in the project root and have activated the virtual environment
cd /path/to/project
source venv/bin/activate  # or venv\Scripts\activate on Windows

"Database connection failed"

# Check your DATABASE_URL in .env
# For SQLite, make sure the directory exists and is writable
# For PostgreSQL, ensure the server is running and credentials are correct

"Migration conflicts"

# Check migration status
make migrate-status

# If there are conflicts, contact the team lead
# We may need to merge or reorder migrations

Need Help?

• Check make help-db for database commands
• Use make verify-setup to diagnose issues
• Ask in the team chat if you're stuck

Best Practices

1. Always run migrations after pulling code
2. Never edit migration files after they're committed
3. Test your migrations on a copy of production data
4. Include meaningful messages when creating migrations
5. Review generated migrations before applying them

Next Steps

• Database Schema Documentation - Understand our data model
• Database Migrations Guide - Advanced migration workflows
• API Documentation - Start building features