Migration Guide - Open Source Site Tracking

Overview

Migration is a critical process that requires careful planning and execution. This guide covers various migration scenarios to help you transition smoothly between versions, databases, and platforms.

Version Migration

Upgrade Path

From Version	To Version	Migration Type	Notes
0.6.x	0.7.x	Minor	Database migration required
0.7.x	0.8.x	Minor	Configuration update required
0.8.x	0.9.x	Minor	API changes
0.9.x	1.0.x	Major	Breaking changes, full migration required

Pre-Migration Checklist

Before You Begin

Backup Data: Create complete backup of database and files
Test Environment: Set up staging environment for testing
Review Changes: Read release notes and breaking changes
Dependencies: Update system dependencies if required
Documentation: Review updated documentation
Rollback Plan: Prepare rollback strategy

Migration Process

Step-by-Step Migration

1Backup Current System

# Backup database
pg_dump site_tracking > backup_$(date +%Y%m%d).sql
# Backup application files
tar -czf app_backup_$(date +%Y%m%d).tar.gz /path/to/app
# Backup configuration
cp .env .env.backup

2Update Application

# Pull latest version
git pull origin main
# Update dependencies
pip install -r requirements.txt
npm install
# Update configuration if needed

3Run Database Migration

# Run database migrations
python manage.py migrate
# Or using Alembic
alembic upgrade head

4Verify Migration

# Check application health
curl http://localhost:8000/health
# Test key functionality
python -c "from app.models import User; print('Models OK')"

5Update Frontend

# Build frontend
npm run build
# Restart services
docker-compose restart

Database Migration

SQLite to PostgreSQL

Migration Steps

1Export SQLite Data

# Export data from SQLite
python scripts/export_sqlite.py --output data.json

2Setup PostgreSQL

# Create PostgreSQL database
createdb site_tracking
# Create user
createuser site_tracking_user
psql -c "ALTER USER site_tracking_user PASSWORD 'password';"
psql -c "GRANT ALL PRIVILEGES ON DATABASE site_tracking TO site_tracking_user;"

3Import Data

# Import data to PostgreSQL
python scripts/import_postgres.py --input data.json

4Update Configuration

# Update .env file
DATABASE_URL=postgresql://site_tracking_user:password@localhost:5432/site_tracking

MySQL to PostgreSQL

Migration Script

# Export from MySQL
mysqldump -u username -p site_tracking > mysql_backup.sql
# Convert to PostgreSQL format
python scripts/mysql_to_postgres.py mysql_backup.sql postgres_data.sql
# Import to PostgreSQL
psql -U postgres -d site_tracking < postgres_data.sql

Database Schema Migration

# Migration example
from alembic import op
import sqlalchemy as sa
def upgrade():
    # Add new columns
    op.add_column('users', sa.Column('profile_image', sa.String(255)))
    op.add_column('projects', sa.Column('is_public', sa.Boolean(), default=False))
    
    # Create new tables
    op.create_table('user_sessions',
        sa.Column('id', sa.Integer(), primary_key=True),
        sa.Column('user_id', sa.Integer(), sa.ForeignKey('users.id')),
        sa.Column('session_token', sa.String(255)),
        sa.Column('expires_at', sa.DateTime())
    )
def downgrade():
    # Remove new columns
    op.drop_column('projects', 'is_public')
    op.drop_column('users', 'profile_image')
    
    # Drop new tables
    op.drop_table('user_sessions')

Platform Migration

Google Analytics Migration

Export from Google Analytics

# Export data using Google Analytics API
python scripts/export_ga.py --property-id GA_PROPERTY_ID --output ga_data.json

Import to Site Tracking

# Import Google Analytics data
python scripts/import_ga.py --input ga_data.json --project-id PROJECT_ID

Update Tracking Code

Mixpanel Migration

Export from Mixpanel

# Export Mixpanel data
python scripts/export_mixpanel.py --api-key MIXPANEL_API_KEY --output mixpanel_data.json

Import to Site Tracking

# Import Mixpanel data
python scripts/import_mixpanel.py --input mixpanel_data.json --project-id PROJECT_ID

Update Tracking Code

// Replace Mixpanel tracking
// OLD
mixpanel.track('Button Click', {button: 'signup'});
// NEW
SiteTracking.track('button-click', {button: 'signup'});

Data Import

CSV Import

CSV Format

# Example CSV format
date,page_url,user_id,session_id,event_type,properties
2024-01-15,/homepage,user123,session456,page_view,"{}"
2024-01-15,/about,user123,session456,page_view,"{}"
2024-01-15,/contact,user123,session456,page_view,"{}"

Import Script

# Import CSV data
python scripts/import_csv.py --file analytics_data.csv --project-id PROJECT_ID

JSON Import

JSON Format

# Example JSON format
{
  "events": [
    {
      "date": "2024-01-15T10:30:00Z",
      "page_url": "/homepage",
      "user_id": "user123",
      "session_id": "session456",
      "event_type": "page_view",
      "properties": {}
    }
  ]
}

Import Script

# Import JSON data
python scripts/import_json.py --file analytics_data.json --project-id PROJECT_ID

Export Migration

Data Export

Export Options

CSV Export: For spreadsheet applications
JSON Export: For programmatic use
SQL Export: For database migration
API Export: For real-time data

Export Commands

# Export to CSV
python scripts/export_csv.py --project-id PROJECT_ID --output analytics.csv
# Export to JSON
python scripts/export_json.py --project-id PROJECT_ID --output analytics.json
# Export to SQL
python scripts/export_sql.py --project-id PROJECT_ID --output analytics.sql

Export API

# Export via API
curl -X GET "http://localhost:8000/api/v1/projects/PROJECT_ID/export?format=csv" \
     -H "Authorization: Bearer YOUR_TOKEN"
# Export with date range
curl -X GET "http://localhost:8000/api/v1/projects/PROJECT_ID/export?format=json&start_date=2024-01-01&end_date=2024-01-31" \
     -H "Authorization: Bearer YOUR_TOKEN"

Troubleshooting

Common Migration Issues

Database Connection Issues

# Check database connectivity
psql -h localhost -U username -d database
# Check connection string
echo $DATABASE_URL
# Test connection from application
python -c "from app.database import get_db; print('Database OK')"

Data Integrity Issues

# Validate data integrity
python scripts/validate_data.py --project-id PROJECT_ID
# Check for missing data
python scripts/check_missing_data.py --project-id PROJECT_ID

Performance Issues

# Monitor migration performance
python scripts/monitor_migration.py --project-id PROJECT_ID
# Optimize database
python scripts/optimize_database.py

Rollback Procedures

Rollback Steps

Stop application services
Restore database from backup
Restore application files
Restore configuration
Restart services
Verify functionality

# Rollback database
psql -U postgres -d site_tracking < backup_20240115.sql
# Rollback application
git checkout previous_version_tag
docker-compose restart

Migration Best Practices

Plan Ahead: Plan migrations well in advance
Test Thoroughly: Test in staging environment
Backup Everything: Complete backups before migration
Monitor Progress: Monitor migration progress closely
Document Changes: Document all migration changes
Communicate: Inform stakeholders about migration

Getting Help

Documentation: Check full documentation
Issues: Report migration issues on GitHub
Discussions: Ask questions in GitHub Discussions
Support: Contact support for enterprise migrations