# Development Workflow with PocketBase Migrations

## Scenario: Dev A Adds New Migration, Dev B Updates

### Dev A's Actions
1. Makes schema changes in Admin UI
2. Creates migration

   ./pocketbase migrate create

3. Commits and pushes

   git add pb_migrations/
   git commit -m "Add new user fields"
   git push

### Dev B's Update Process

1. **Before Pulling**

   # Check if PocketBase is running
   # If yes, stop it before proceeding

2. **Pull New Changes**

   git pull

3. **Apply New Migrations**

   ./pocketbase migrate up

4. **Restart PocketBase**

   ./pocketbase serve

#### What Happens to Dev B's Existing Data?
- Existing data remains intact
- New fields will be added as defined in migration
- Existing records will have null/default values for new fields
- Removed fields will be dropped (if any)
- Relations will be established as empty/null

## Common Scenarios and Solutions

### 1. Schema Conflicts

// Dev B has different schema than migration
// Solution: Always apply migrations in order
./pocketbase migrate up

### 2. Data Migration Needed
If new fields require specific data:

// pb_migrations/1234567890_add_user_profile.js
migrate((db) => {
    // Add new fields
    const collection = db.collection('users');
    collection.schema.push({
        name: 'profile_completed',
        type: 'bool',
        default: false
    });

    // Update existing records if needed
    const dao = new Dao(db);
    dao.findCollection('users').recordRules = {};
    const records = dao.findRecordsByFilter('users', 'created >= "2020-01-01"');
    
    records.forEach(record => {
        record.profile_completed = record.name && record.email ? true : false;
        dao.saveRecord(record);
    });

    return Collection.update(db, [collection]);
});

### 3. Breaking Changes
When migrations include breaking changes:

1. **Communicate with Team**
- Announce major schema changes
- Document required actions
- Set timeline for updates

2. **Consider Data Backup**

   # Before pulling breaking changes
   cp -r pb_data pb_data_backup

## Best Practices for Team Workflow

### 1. Communication
- Announce schema changes in team chat
- Document migration purpose
- Warn about breaking changes

### 2. Migration Organization

pb_migrations/
  ├── 1234567890_init.js
  ├── 1234567891_add_user_profile.js
  └── 1234567892_update_post_schema.js

### 3. Testing Migrations

# Test migration locally first
./pocketbase migrate up
# Verify data integrity
# Test application functionality

### 4. Version Control

# Good commit messages
git commit -m "Add user profile fields with data migration"

# Include migration details in commit body
git commit -m "Add user profile fields" -m "
- Adds profile_completed boolean
- Migrates existing data
- Required for feature X
"

## Emergency Fixes

### If Migration Fails
1. **Stop PocketBase**
2. **Restore from Backup**

   cp -r pb_data_backup pb_data

3. **Review Migration Logs**
4. **Fix and Retry**

### If Data Loss Occurs
1. **Stop Application**
2. **Restore Backup**
3. **Review Migration**
4. **Apply Fixed Migration**

## Development Tips

1. **Regular Backups**

   # Script to backup before migrations
   cp -r pb_data "pb_data_backup_$(date +%Y%m%d)"

2. **Test Data Script**

   // scripts/seed-dev-data.js
   // Create script to regenerate test data

3. **Local Development**
- Keep test data minimal
- Use seed scripts for consistent data
- Regular testing of migrations

## Workflow Checklist

### Before Creating Migration
- [ ] Backup existing data
- [ ] Test changes in Admin UI
- [ ] Document changes

### After Pulling Migration
- [ ] Review migration files
- [ ] Backup existing data
- [ ] Apply migrations
- [ ] Test functionality
- [ ] Verify data integrity

Remember: The key to smooth team development is clear communication and careful testing of migrations before sharing them with the team.