Migrating from Yearning v3 to v4
Public Beta Migration Caution
Yearning v4.0 is currently in Public Beta. Always rehearse the full preflight -> dry-run -> apply -> verify workflow against a cloned copy of your v3 MySQL database before planning any production cutover.
Yearning v4 moves metadata persistence from legacy MySQL to a versioned PostgreSQL domain schema using an explicit downtime cutover pipeline (Preflight -> Dry-Run -> Admin Mapping Confirmation -> Apply -> Verify).
Non-Negotiable Migration Rules
- Zero Active Legacy Work: Stop Yearning v3 and close all active tickets before migration (
5001 MIGRATION_ACTIVE_WORK_EXISTSblocks otherwise). - Never Resume a Failed Target: If
migrate applyfails or receivesSIGTERMtwice, the target database is invalid (exit code5rejects retries). Destroy the target PostgreSQL database, recreate an empty database, and re-run cleanly. - Exact
deployment_idMatch:encryption.deployment_idinmigration-config.jsonmust match the targetkeyring.jsondeployment_idcharacter-for-character so AES-256-GCM AAD verification succeeds at runtime. - Automatic Legacy
SecretKeyRe-Encryption: Configure optionalsource.legacy_secret_key(environmentor 0600filereference, never CLI args) pointing to v3's 16-charGeneral.SecretKeyto decrypt legacy AES-128-CBC datasource passwords and re-seal them into v4 AES-256-GCM envelopes.
Six-Step Cutover Procedure
Once verify reports all_passed=true, shut down the --migration-mode process (or scale down yearning-migration-review in Kubernetes) and start the production yearning serve control plane.