Migration Guide: v1 to v2

Migration Required Estimated Time: 1-4 weeks

This comprehensive guide helps you migrate from StratiqX v1 to v2 with minimal disruption.

Important

v2 includes breaking changes. Review this entire guide before starting migration.

📋 Pre-Migration Checklist

Before you begin, ensure you have:

[ ] Backup: Complete backup of v1 data and configuration
[ ] Testing Environment: Staging environment for testing migration
[ ] Rollback Plan: Strategy to rollback if issues occur
[ ] Maintenance Window: Scheduled downtime for production migration
[ ] Team Communication: Informed all stakeholders of migration timeline
[ ] Documentation Review: Read breaking changes document
[ ] API Audit: Identified all v1 API integrations
[ ] Dependencies Check: Verified all third-party integrations

🎯 Migration Overview

High-Level Steps

Preparation (1-3 days) - Review, plan, backup
Staging Migration (1-5 days) - Test in staging environment
Testing & Validation (2-7 days) - Thorough testing
Production Migration (1 day) - Execute production migration
Post-Migration (Ongoing) - Monitor and optimize

Estimated Timeline by Deployment Size

Deployment Size	Users	Estimated Time	Complexity
Small	< 100	1-2 days	Low
Medium	100-1000	1 week	Medium
Large	1000+	2-4 weeks	High
Enterprise	10000+	4-8 weeks	Very High

🔧 Step 1: Preparation

1.1 Environment Setup

Install v2 Dependencies

bash

# Update package.json
npm install vitepress@^1.6.3

# Install v2-specific dependencies
npm install @stratiqx/sdk-v2
npm install @stratiqx/cli-v2

Environment Variables

bash

# v1 naming
STRATIQX_API_KEY=xxx
STRATIQX_ENV=production

# v2 naming (updated)
STRATIQX_V2_API_KEY=xxx
STRATIQX_V2_ENVIRONMENT=production
STRATIQX_V2_REGION=us-east-1  # New in v2

1.2 Data Backup

Backup Script

bash

#!/bin/bash
# backup-v1.sh

# Backup database
pg_dump stratiqx_v1 > backup_$(date +%Y%m%d).sql

# Backup configuration
cp -r /etc/stratiqx /backup/config_$(date +%Y%m%d)/

# Backup uploaded files
tar -czf uploads_$(date +%Y%m%d).tar.gz /var/stratiqx/uploads/

# Verify backups
sha256sum backup_$(date +%Y%m%d).sql > checksums.txt

1.3 Dependency Audit

Check Current Integrations

javascript

// audit-integrations.js
const integrations = {
  payments: ['stripe'],
  auth: ['oauth2'],
  storage: ['s3'],
  email: ['sendgrid'],
  analytics: ['ga4']
};

// Verify v2 compatibility
integrations.forEach(type => {
  console.log(`Checking ${type} compatibility with v2...`);
  // Check compatibility
});

🚀 Step 2: Staging Migration

2.1 Database Migration

Run Migration Scripts

bash

# Install migration tool
npm install -g @stratiqx/migrate

# Check migration status
stratiqx-migrate status

# Run migrations
stratiqx-migrate up --to=v2.0.0

# If issues occur, rollback
stratiqx-migrate down --to=v1.0.0

Database Schema Changes

sql

-- Example migration SQL
ALTER TABLE users ADD COLUMN profile_v2 JSONB;
ALTER TABLE workflows ADD COLUMN execution_mode VARCHAR(50);
CREATE INDEX idx_workflows_v2 ON workflows(execution_mode, created_at);

-- Migrate data
UPDATE users SET profile_v2 = jsonb_build_object(
  'preferences', profile,
  'settings', settings
);

2.2 Configuration Migration

v1 Configuration

yaml

# config.v1.yaml
api:
  version: "v1"
  endpoint: "https://api.stratiqx.com/v1"
  
auth:
  type: "oauth2"
  
workflows:
  engine: "legacy"

v2 Configuration

yaml

# config.v2.yaml
api:
  version: "v2"
  endpoints:
    rest: "https://api.stratiqx.com/v2"
    graphql: "https://api.stratiqx.com/graphql"
  
auth:
  type: "oauth2.1"
  providers:
    - type: "internal"
    - type: "saml"
  
workflows:
  engine: "v2"
  features:
    parallel: true
    retry: true

Migration Script

javascript

// migrate-config.js
const v1Config = require('./config.v1.yaml');

const v2Config = {
  api: {
    version: 'v2',
    endpoints: {
      rest: v1Config.api.endpoint.replace('/v1', '/v2'),
      graphql: v1Config.api.endpoint.replace('/v1', '/graphql')
    }
  },
  auth: {
    type: 'oauth2.1',
    // Map v1 settings to v2
    ...migrateAuthConfig(v1Config.auth)
  },
  workflows: {
    engine: 'v2',
    features: {
      parallel: true,
      retry: true
    }
  }
};

fs.writeFileSync('config.v2.yaml', yaml.dump(v2Config));

2.3 API Integration Updates

v1 API Calls

javascript

// v1 API usage
const axios = require('axios');

const response = await axios.get('https://api.stratiqx.com/v1/reports', {
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  }
});

v2 API Calls

javascript

// v2 API usage
import { StratiqxClient } from '@stratiqx/sdk-v2';

const client = new StratiqxClient({
  apiKey: process.env.STRATIQX_V2_API_KEY,
  region: 'us-east-1'
});

// REST API
const reports = await client.reports.list();

// Or GraphQL
const result = await client.graphql.query({
  query: `
    query GetReports {
      reports {
        id
        title
        status
      }
    }
  `
});

🧪 Step 3: Testing & Validation

3.1 Functional Testing

Test Checklist

[ ] Authentication and authorization
[ ] User management
[ ] Workflow creation and execution
[ ] Report generation
[ ] API integrations
[ ] Payment processing
[ ] Email notifications
[ ] File uploads/downloads
[ ] Search functionality
[ ] Analytics tracking

Automated Test Suite

javascript

// tests/migration.test.js
describe('v2 Migration Tests', () => {
  test('User authentication works', async () => {
    const user = await client.auth.login(credentials);
    expect(user).toBeDefined();
    expect(user.version).toBe('v2');
  });

  test('Workflows execute correctly', async () => {
    const workflow = await client.workflows.execute(workflowId);
    expect(workflow.status).toBe('completed');
  });

  test('API v2 endpoints respond', async () => {
    const response = await client.reports.list();
    expect(response.data).toBeInstanceOf(Array);
  });
});

3.2 Performance Testing

Load Testing

javascript

// load-test.js
import http from 'k6/http';
import { check, sleep } from 'k6';

export let options = {
  stages: [
    { duration: '5m', target: 100 },  // Ramp up
    { duration: '10m', target: 100 }, // Stay at 100 users
    { duration: '5m', target: 0 },    // Ramp down
  ],
};

export default function () {
  let response = http.get('https://api.stratiqx.com/v2/reports');
  check(response, {
    'status is 200': (r) => r.status === 200,
    'response time < 500ms': (r) => r.timings.duration < 500,
  });
  sleep(1);
}

3.3 Data Integrity Verification

Verification Script

javascript

// verify-data.js
const v1Data = await fetchV1Data();
const v2Data = await fetchV2Data();

// Compare critical data
const comparison = {
  users: compareUsers(v1Data.users, v2Data.users),
  workflows: compareWorkflows(v1Data.workflows, v2Data.workflows),
  reports: compareReports(v1Data.reports, v2Data.reports)
};

if (comparison.users.mismatches > 0) {
  console.error('User data mismatch detected!');
  process.exit(1);
}

console.log('Data integrity verified ✓');

📦 Step 4: Production Migration

4.1 Pre-Migration Steps

Maintenance Notice

markdown

🔧 Scheduled Maintenance

StratiqX will be undergoing a major upgrade to v2.

**Start:** October 20, 2025 - 2:00 AM UTC
**Duration:** 2-4 hours
**Impact:** Platform will be unavailable

What's New in v2:
- Enhanced AI capabilities
- 50% faster performance
- Modern UI with dark mode
- GraphQL API support

Thank you for your patience!

Final Checklist

[ ] Maintenance notice published (48 hours in advance)
[ ] All stakeholders notified
[ ] Backups verified and tested
[ ] Rollback procedure documented
[ ] Support team briefed
[ ] Monitoring alerts configured
[ ] Database migration scripts tested

4.2 Migration Execution

Migration Runbook

bash

#!/bin/bash
# production-migration.sh

set -e  # Exit on error

echo "Starting StratiqX v1 to v2 migration..."

# 1. Enable maintenance mode
echo "Enabling maintenance mode..."
stratiqx-cli maintenance:enable

# 2. Backup production
echo "Creating production backup..."
./backup-production.sh

# 3. Stop v1 services
echo "Stopping v1 services..."
systemctl stop stratiqx-v1

# 4. Run database migrations
echo "Running database migrations..."
stratiqx-migrate up --to=v2.0.0

# 5. Deploy v2 application
echo "Deploying v2 application..."
./deploy-v2.sh

# 6. Start v2 services
echo "Starting v2 services..."
systemctl start stratiqx-v2

# 7. Verify health
echo "Checking v2 health..."
./health-check.sh

# 8. Disable maintenance mode
echo "Disabling maintenance mode..."
stratiqx-cli maintenance:disable

echo "Migration completed successfully!"

4.3 Health Checks

Post-Migration Verification

javascript

// health-check.js
const checks = {
  api: async () => {
    const response = await fetch('https://api.stratiqx.com/v2/health');
    return response.status === 200;
  },
  
  database: async () => {
    const result = await db.query('SELECT 1');
    return result.rows.length === 1;
  },
  
  auth: async () => {
    const token = await getAuthToken();
    return token !== null;
  },
  
  workflows: async () => {
    const test = await executeTestWorkflow();
    return test.status === 'completed';
  }
};

// Run all checks
for (const [name, check] of Object.entries(checks)) {
  const result = await check();
  console.log(`${name}: ${result ? '✓' : '✗'}`);
}

🔍 Step 5: Post-Migration

5.1 Monitoring

Key Metrics to Monitor

API response times
Error rates
Database performance
Memory usage
CPU utilization
Active user sessions
Workflow execution success rate

Monitoring Dashboard

javascript

// Setup monitoring alerts
const alerts = {
  errorRate: {
    threshold: 0.05,  // 5% error rate
    action: 'page_oncall'
  },
  responseTime: {
    threshold: 1000,  // 1 second
    action: 'notify_team'
  },
  cpuUsage: {
    threshold: 80,    // 80% CPU
    action: 'scale_up'
  }
};

5.2 User Communication

Post-Migration Announcement

markdown

✅ StratiqX v2 is Live!

We've successfully upgraded to v2. Here's what you need to know:

**What's New:**
- Faster performance (50% improvement)
- Modern UI with dark mode
- Enhanced AI capabilities
- New GraphQL API

**Action Required:**
- Update your API integrations: [Migration Guide](/v2/api-migration.md)
- Review new features: [What's New](/v2/whats-new.md)
- Report any issues: support@stratiqx.ai

**Resources:**
- [v2 Documentation](/v2/)
- [Video Tutorial](https://youtu.be/xxx)
- [FAQ](/v2/faq.md)

5.3 Rollback Plan

If Issues Arise

bash

#!/bin/bash
# rollback-to-v1.sh

echo "Rolling back to v1..."

# 1. Enable maintenance
stratiqx-cli maintenance:enable

# 2. Stop v2 services
systemctl stop stratiqx-v2

# 3. Restore v1 database
pg_restore -d stratiqx backup_$(date +%Y%m%d).sql

# 4. Start v1 services
systemctl start stratiqx-v1

# 5. Verify health
./health-check-v1.sh

# 6. Disable maintenance
stratiqx-cli maintenance:disable

echo "Rollback completed"

🎓 Training & Resources

Documentation

Support

Email: support@stratiqx.ai
Chat: Available in dashboard
Community: GitHub Discussions
Emergency: On-call support for enterprise customers

💡 Tips & Best Practices

Pro Tips

Test Thoroughly: Never skip staging migration
Monitor Closely: Watch metrics for 48 hours post-migration
Communicate Often: Keep users informed throughout process
Have Rollback Ready: Always have a tested rollback plan
Document Issues: Track all issues for future reference

📞 Getting Help

Migration Support

Enterprise customers: Priority migration assistance
Business tier: Email support
Community: Forum and GitHub discussions

Escalation Path

Check documentation
Search community forum
Email support
Escalate to migration team (enterprise only)

Need Help?

If you encounter issues during migration, contact our support team immediately.
Enterprise customers can reach on-call support 24/7.

Last Updated: October 14, 2025
Migration Tool Version: 2.0.0

Migration Guide: v1 to v2 ​

📋 Pre-Migration Checklist ​

🎯 Migration Overview ​

High-Level Steps ​

Estimated Timeline by Deployment Size ​

🔧 Step 1: Preparation ​

1.1 Environment Setup ​

1.2 Data Backup ​

1.3 Dependency Audit ​

🚀 Step 2: Staging Migration ​

2.1 Database Migration ​

2.2 Configuration Migration ​

2.3 API Integration Updates ​

🧪 Step 3: Testing & Validation ​

3.1 Functional Testing ​

3.2 Performance Testing ​

3.3 Data Integrity Verification ​

📦 Step 4: Production Migration ​

4.1 Pre-Migration Steps ​

4.2 Migration Execution ​

4.3 Health Checks ​

🔍 Step 5: Post-Migration ​

5.1 Monitoring ​

5.2 User Communication ​

5.3 Rollback Plan ​

🎓 Training & Resources ​

Documentation ​

Support ​

💡 Tips & Best Practices ​

📞 Getting Help ​

Migration Guide: v1 to v2

📋 Pre-Migration Checklist

🎯 Migration Overview

High-Level Steps

Estimated Timeline by Deployment Size

🔧 Step 1: Preparation

1.1 Environment Setup

1.2 Data Backup

1.3 Dependency Audit

🚀 Step 2: Staging Migration

2.1 Database Migration

2.2 Configuration Migration

2.3 API Integration Updates

🧪 Step 3: Testing & Validation

3.1 Functional Testing

3.2 Performance Testing

3.3 Data Integrity Verification

📦 Step 4: Production Migration

4.1 Pre-Migration Steps

4.2 Migration Execution

4.3 Health Checks

🔍 Step 5: Post-Migration

5.1 Monitoring

5.2 User Communication

5.3 Rollback Plan

🎓 Training & Resources

Documentation

Support

💡 Tips & Best Practices

📞 Getting Help