# Migrating Code

> Safe code migrations with backward compatibility and reversibility. Use when upgrading dependencies, changing database schemas, API versioning, or transitioning between technologies. Use when this capability is needed.

- Skill: `tomevault-io/migrating-code` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/migrating-code`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/migrating-code/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/migrating-code

---


# Migrating Code

## Core Principles

1. **Never break production** - Backward compatible until fully rolled out
2. **Small, reversible steps** - Each step independently deployable
3. **Test at every stage** - Before, during, and after
4. **Have rollback ready** - Always

## Migration Checklist

```
- [ ] Pre-Migration: Read changelog, identify breaking changes, ensure test coverage
- [ ] During: Small steps, test each, monitor errors, rollback ready
- [ ] Post: Verify tests, check metrics, remove scaffolding, update docs
```

## Database Schema

### Safe Patterns

| Operation | Pattern |
|-----------|---------|
| Add column | Add nullable first → backfill → add constraints |
| Remove column | Stop writes → deploy code that doesn't read → drop column |
| Rename column | Add new → dual-write → backfill → switch reads → drop old |
| Change type | New column → dual-write → migrate in batches → switch → drop |

**Never:** Add NOT NULL without defaults to tables with data.

## API Migrations

### Deprecation Process

1. Add deprecation warnings to old endpoints
2. Document migration path
3. Set and communicate sunset date
4. Monitor usage
5. Remove after usage drops

```json
{
  "data": {},
  "_warnings": [{
    "code": "DEPRECATED_ENDPOINT",
    "message": "Use /api/v2/users instead",
    "sunset": "2025-06-01"
  }]
}
```

## Framework Upgrades

1. **Upgrade to latest minor first** - Get deprecation warnings
2. **Fix warnings** - Before major upgrade
3. **One major at a time** - Don't batch
4. **Test after each step**

### Adapter Pattern for Library Swaps

```typescript
// Wrap library usage
// lib/date.ts
import moment from 'moment';
export const formatDate = (date: Date, format: string) =>
  moment(date).format(format);

// Migration: just change the adapter
import { format } from 'date-fns';
export const formatDate = (date: Date, fmt: string) =>
  format(date, fmt);
```

## Gradual Rollout

Use feature flags:
```typescript
if (featureFlags.useNewSystem) {
  return newService.process(order);
} else {
  return legacyService.process(order);
}
```

Roll out: 1% → 10% → 50% → 100% → remove flag

## Common Pitfalls

**Avoid:**
- Big bang migrations
- No rollback plans
- Skipping dual-write phase
- Single large data transactions
- Removing old code before new is proven

**Do:**
- Small, reversible steps
- Test rollback procedures
- Batch large data migrations
- Keep old paths until new verified

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/rileyhilliard) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-11 -->