# 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
```bash
# Install all dependencies including Alembic
make install-all
```

### 2. Set Up Environment
```bash
# 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
```bash
# Apply all migrations to create the database schema
make migrate-up
```

### 4. Verify Setup
```bash
# Check that everything is working
make verify-setup
```

### 5. Start Development
```bash
# 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
```bash
# 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
```bash
# 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
```bash
make setup  # This handles everything automatically
```

### Database is Out of Sync
```bash
# Check current status
make migrate-status

# Apply any missing migrations
make migrate-up
```

### Something Went Wrong
```bash
# 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)
```bash
# 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)
```env
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)
```env
DATABASE_URL=postgresql://user:password@localhost:5432/ecommerce_dev
```
- More production-like environment
- Better for testing complex queries
- Required for certain advanced features

### Production
```env
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'"
```bash
# 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"
```bash
# 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"
```bash
# 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 Setup Guide](DATABASE_SETUP_GUIDE.md) - Complete database setup guide
- [Database Migrations Guide](../development/database-migrations.md) - Advanced migration workflows
- [API Documentation](../api/index.md) - Start building features