193 lines
4.8 KiB
Markdown
193 lines
4.8 KiB
Markdown
# 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 Schema Documentation](../development/database-schema.md) - Understand our data model
|
|
- [Database Migrations Guide](../development/database-migrations.md) - Advanced migration workflows
|
|
- [API Documentation](../api/index.md) - Start building features
|