Add Alembic migration system for database schema versioning

- Introduced `alembic.ini` for Alembic configuration, enabling structured database migrations.
- Created `database/migrations/env.py` to manage migration environment and database URL retrieval.
- Added migration script template `database/migrations/script.py.mako` for generating migration scripts.
- Updated `.gitignore` to exclude migration versions from version control.
- Enhanced `setup.md` documentation to include details on the migration system and commands for managing migrations.

docs/setup.md

@@ -101,7 +101,76 @@ dashboard_postgres   timescale/timescaledb:latest-pg15   "docker-entrypoint.s…
 dashboard_redis      redis:7-alpine                      "docker-entrypoint.s…"   redis      X minutes ago    Up X minutes (healthy)   0.0.0.0:6379->6379/tcp
 ```
 
-### 3. Verify Database Schema
+### 3. Database Migration System
+
+The project uses **Alembic** for database schema versioning and migrations. This allows for safe, trackable database schema changes.
+
+#### Understanding Migration vs Direct Schema
+
+The project supports two approaches for database setup:
+
+1. **Direct Schema (Default)**: Uses `database/init/schema_clean.sql` for automatic Docker initialization
+2. **Migration System**: Uses Alembic for versioned schema changes and updates
+
+#### Migration Commands
+
+**Check migration status:**
+```powershell
+uv run alembic current
+```
+
+**View migration history:**
+```powershell
+uv run alembic history --verbose
+```
+
+**Upgrade to latest migration:**
+```powershell
+uv run alembic upgrade head
+```
+
+**Downgrade to previous migration:**
+```powershell
+uv run alembic downgrade -1
+```
+
+**Create new migration (for development):**
+```powershell
+# Auto-generate migration from model changes
+uv run alembic revision --autogenerate -m "Description of changes"
+
+# Create empty migration for custom changes
+uv run alembic revision -m "Description of changes"
+```
+
+#### Migration Files Location
+
+- **Configuration**: `alembic.ini`
+- **Environment**: `database/migrations/env.py`
+- **Versions**: `database/migrations/versions/`
+
+#### When to Use Migrations
+
+**Use Direct Schema (recommended for new setups):**
+- Fresh installations
+- Development environments
+- When you want automatic schema setup with Docker
+
+**Use Migrations (recommended for updates):**
+- Updating existing databases
+- Production schema changes
+- When you need to track schema history
+- Rolling back database changes
+
+#### Migration Best Practices
+
+1. **Always backup before migrations in production**
+2. **Test migrations on a copy of production data first**
+3. **Review auto-generated migrations before applying**
+4. **Use descriptive migration messages**
+5. **Never edit migration files after they've been applied**
+
+### 4. Verify Database Schema
 
 The database schema is automatically initialized when containers start. You can verify it worked:
 
@@ -111,7 +180,7 @@ docker exec dashboard_postgres psql -U dashboard -d dashboard -c "\dt"
 
 Expected output should show tables: `bots`, `bot_performance`, `market_data`, `raw_trades`, `signals`, `supported_exchanges`, `supported_timeframes`, `trades`
 
-### 4. Test Database Initialization Script (Optional)
+### 5. Test Database Initialization Script (Optional)
 
 You can also test the database initialization using the Python script:
 
@@ -367,6 +436,52 @@ rm -rf .venv
 uv sync
 ```
 
+#### 6. Migration Issues
+
+**Error**: `alembic.util.exc.CommandError: Target database is not up to date`
+
+**Solution**:
+```powershell
+# Check current migration status
+uv run alembic current
+
+# Upgrade to latest migration
+uv run alembic upgrade head
+
+# If migrations are out of sync, stamp current version
+uv run alembic stamp head
+```
+
+**Error**: `ModuleNotFoundError: No module named 'database'`
+
+**Solution**:
+- Ensure you're running commands from the project root directory
+- Verify the virtual environment is activated: `uv run <command>`
+
+**Error**: Migration revision conflicts
+
+**Solution**:
+```powershell
+# Check migration history
+uv run alembic history --verbose
+
+# Merge conflicting migrations
+uv run alembic merge -m "Merge conflicting revisions" <revision1> <revision2>
+```
+
+**Error**: Database already has tables but no migration history
+
+**Solution**:
+```powershell
+# Mark current schema as the initial migration
+uv run alembic stamp head
+
+# Or start fresh with migrations
+docker-compose down -v
+docker-compose up -d
+uv run alembic upgrade head
+```
+
 ### Log Files
 
 View service logs:
@@ -426,6 +541,6 @@ If you encounter issues not covered in this guide:
 
 ---
 
-**Last Updated**: 2024-05-30  
+**Last Updated**: 2025-05-30  
 **Version**: 1.0  
-**Tested On**: Windows 11, Docker Desktop 4.x 
+**Tested On**: Windows 11, Docker Desktop 4.x