# Schema Evolution

> Manage database schema changes while maintaining backwards compatibility. Handle migrations, versioning, and zero-downtime deployments. Use when evolving data models in production systems.

- **Type:** Skill
- **Install:** `agentstack add skill-sethdford-claude-skills-schema-evolution`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [sethdford](https://agentstack.voostack.com/s/sethdford)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [sethdford](https://github.com/sethdford)
- **Source:** https://github.com/sethdford/claude-skills/tree/main/architect/data-architecture/skills/schema-evolution

## Install

```sh
agentstack add skill-sethdford-claude-skills-schema-evolution
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Schema Evolution

Evolve database schemas safely while maintaining backwards compatibility and minimizing downtime.

## Context

You are planning schema changes in production systems. Design migrations that don't break deployed clients or services. Read current schemas, deployment frequency, and rollback requirements.

## Domain Context

Based on production database migration best practices:

- **Backwards Compatibility**: Old code continues working with new schema; new code works with both
- **Forwards Compatibility**: New code can read old data; gracefully handles missing fields
- **Zero-Downtime Deployment**: Database changes don't require application downtime
- **Additive Changes**: Adding columns/tables is safe; dropping/renaming requires care
- **Dual-Write Pattern**: Write to both old and new schema during migration; switch reads

## Instructions

1. **Plan Phase 1 (Additive)**: Add new columns/tables. Code ignores new columns for now. Deploy database changes. All existing code still works.

2. **Plan Phase 2 (Dual Write)**: Update application code to write to both old and new schema. Reads can use either. Let data double-write for period (hours to days).

3. **Plan Phase 3 (Migrate Data)**: Background job migrates existing data to new schema. Backfill new fields from old data via transformation.

4. **Plan Phase 4 (Code Switch)**: Update code to read from new schema, write to both. Gradually shift reads: 10% new, 90% old → 50/50 → 100% new.

5. **Plan Phase 5 (Cleanup)**: Once all code reads new schema, remove old schema if safe. Keep removal as separate deployment after week of monitoring.

## Anti-Patterns

- **Big-Bang Migration**: Deploy schema and code changes simultaneously. Result: downtime, hard rollback. **Guard**: Separate database and application deployments; deploy database first.
- **Dropping Columns Without Wrapping Code**: Assume all code updated. Result: errors in production. **Guard**: Wait 1+ releases before drop; deploy code removal first, schema cleanup second.
- **No Rollback Plan**: Assume migrations succeed. Result: stuck in bad state. **Guard**: Practice rollbacks; keep old schema for period; verify data integrity.
- **Ignoring Hot Data**: Migrate huge table in single pass. Result: locks, downtime. **Guard**: Use online migration tools (pt-online-schema-change, pg-repack); batch smaller tables.

## Further Reading

- _Database Reliability Engineering_ by Laine Campbell and Charity Majors — schema migration strategies
- _PostgreSQL Documentation on ALTER TABLE_ — database-specific migration patterns
- _Zero Downtime Deployments_ — architectural patterns for safe releases

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [sethdford](https://github.com/sethdford)
- **Source:** [sethdford/claude-skills](https://github.com/sethdford/claude-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-sethdford-claude-skills-schema-evolution
- Seller: https://agentstack.voostack.com/s/sethdford
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.