---
name: velcrafting/persistence-layer-change
source: https://app.decimal.ai/s/velcrafting-persistence-layer-change@1/SKILL.md
source_sha256: 5323d994062d
---

# Skill: backend/persistence-layer-change

## Purpose
Change persistence safely by managing:
- schema changes (tables/columns/indexes)
- migrations
- updated read/write paths
- compatibility and rollout strategy

This skill is responsible for preventing data loss and breaking changes.

---

## Inputs
- Desired schema change (add/alter/remove)
- Backward compatibility needs:
  - can deploy in one step or requires multi-step rollout
- Data access layers involved (ORM/query builder/raw SQL)
- Repo profile (preferred): `<repo>/REPO_PROFILE.json`

---

## Outputs
- Migration(s) or schema change artifact(s)
- Updated data access code to use new schema
- Tests updated or added
- Notes on rollout if multi-step needed (in comments or docs if repo standard)

---

## Non-goals
- Business logic changes unrelated to the schema
- Endpoint wiring (unless required for compilation)
- Rewriting the persistence layer wholesale

---

## Workflow
1) Identify existing migration mechanism and conventions.
2) Choose safe change strategy:
   - additive change first (preferred)
   - dual-write or backfill if required
   - destructive change only with explicit migration plan
3) Implement migration with deterministic up/down behavior when supported.
4) Update data access paths:
   - reads tolerate both states during rollout if needed
   - writes remain consistent
5) Add/adjust indexes carefully (avoid accidental perf regressions).
6) Add tests:
   - migration applies
   - reads/writes work
7) Run required validations from profile.

---

## Checks
- Migration applies cleanly in a fresh environment (as supported by repo)
- No destructive change without explicit plan
- Tests pass (and cover at least one new access path)
- Typecheck/lint pass if configured
- Performance hazards considered (indexes, N+1, full scans)

---

## Failure modes
- Migration framework missing → stop and recommend establishing it before change.
- Destructive change requested → require staged plan and rollback notes.
- Unknown production constraints → recommend conservative additive migration first.

---

## Telemetry
Log:
- skill: `backend/persistence-layer-change`
- migration_type: `additive | staged | destructive`
- artifacts_written: migration file(s)
- files_touched
- outcome: `success | partial | blocked`