persistence-layer-change_skill

Overview

This skill implements schema and migration changes and updates data access patterns safely to avoid data loss and runtime breakage. It produces migration artifacts, updates read/write code paths, and adds tests and rollout notes when multi-step deployments are required. The goal is deterministic, reversible changes with conservative rollout strategies.

How this skill works

The skill inspects the repository to find the migration framework, ORM or raw SQL usage, and any repository profile that defines validations. It chooses a safe change strategy (additive-first, dual-write/backfill, or staged destructive change), generates migrations with deterministic up/down behavior, and updates data access logic so reads and writes remain compatible during rollout. Finally it adds or updates tests and reports validations and telemetry.

When to use it

• Adding, renaming, or removing columns or tables
• Introducing or changing indexes that affect query plans
• Refactoring read/write code to use a new schema layout
• Performing backfills or dual-write rollouts for large datasets
• When you must ensure zero-downtime or reversible schema changes

Best practices

• Prefer additive changes first (new columns/tables/indexes) to preserve compatibility
• Plan destructive changes as staged rollouts with explicit backfill and rollback steps
• Ensure migrations are deterministic with clear up and down behavior when supported
• Make reads tolerant of both old and new shapes during rollout; keep writes consistent
• Add tests that apply migrations on a fresh environment and exercise the new access paths
• Validate typechecks, lints, and performance implications (indexes, N+1, full scans)

Example use cases

• Add a nullable column, backfill values in a background job, then make it non-nullable in a later deployment
• Introduce a new indexed lookup table and switch reads to join with it while keeping legacy reads until rollout completes
• Split a large table into two for performance and implement dual-write plus a consumer verifying data parity before cutover
• Rename a column by adding a new column, updating accessors, backfilling, and then dropping the old column in a final migration