Skip to main content
When services interact with persistent data stores, they rely on database schemas to structure their reads and writes. As your system evolves, you’ll need to modify these schemas to support new features or optimize performance. The challenge? A poorly executed schema migration can trigger catastrophic failures—from permanent data loss to multi-hour outages that damage customer trust. Ryvn addresses this challenge by providing automated safety guarantees for schema migrations. The system validates migration paths through two integration points:
  1. Release metadata declarations that specify which schema versions each release can handle
  2. Readiness monitoring where Ryvn tracks migration completion through service readiness checks
Looking for automated service-to-service compatibility validation? See our guide on Service Dependency Constraints.

​
Multi-Release Migration Example

Consider a service foo that needs to transition from schema V1 to V2. Rather than attempting this in a single risky release, we’ll spread the migration across multiple versions, each with carefully defined schema compatibility: 
0.1.0: Supports V1 exclusively
0.2.0: Backward-compatible with V1, adds V2 support
0.3.0: Performs the actual migration from V1 to V2
0.4.0: V2-only release, eliminates V1 support
Each release declares its schema compatibility in the release metadata: 
# 0.2.0 release metadata
migrations:
  - version: 1
  - version: 2

# 0.3.0 release metadata
migrations:
  - version: 1
  - version: 2

# 0.4.0 release metadata
migrations:
  - version: 2
Beyond these metadata declarations, the running service must signal migration completion through its readiness checks. The Ryvn Agent monitors service readiness and reports this state to the Ryvn Control Plane. The service should remain not ready during migration—foo reports as not ready while release 0.3.0 migrates all data to V2, then becomes ready once the migration completes.

​
Ryvn’s Orchestration Logic

When evaluating whether to deploy a new release of foo, Ryvn’s orchestration engine validates schema compatibility by asking:
Does the candidate release’s supported schema versions include the schema version currently reported by the service?
This constraint enforcement delivers two critical guarantees:

​
Guarantee 1: Migration-Capable Version Deployed First

The service must transition through a version capable of executing the migration before advancing to versions that lack backward compatibility. Example: An environment runs 0.1.0 with schema V1 when release 0.4.0 becomes available. Ryvn prevents an upgrade to 0.4.0 since 0.4.0 exclusively supports V2. The service must first upgrade to 0.3.0 to perform the migration to V2.

​
Guarantee 2: Migration Must Complete Before Further Upgrades

After deploying a migration-capable release, the service must signal completion before Ryvn permits further version advancement. Example: An environment runs 0.3.0, currently executing the V1→V2 migration, while release 0.4.0 awaits deployment. Ryvn blocks the upgrade to 0.4.0 until foo reports its current schema as V2.

​
Safe Rollbacks

These constraints protect rollback operations as well. Consider discovering a critical defect in releases 0.3.0 and 0.4.0 that necessitates reverting to an earlier version. Example: An environment runs 0.4.0 with schema V2. Ryvn evaluates potential rollback targets:
  • 0.3.0 supports V2 ✓ (allowed)
  • 0.2.0 supports V2 ✓ (allowed)
  • 0.1.0 only supports V1 ✗ (rejected—incompatible with V2 data)
Ryvn permits rolling back to 0.2.0 since this release can read V2 data, but blocks any attempt to revert to 0.1.0.

​
Schema Version Tracking

Ryvn tracks schema migration progress by monitoring your service’s readiness status. When a migration is in progress, your service should report as not ready until the migration completes. Once the service becomes ready, Ryvn knows it has successfully migrated to the target schema version declared in its release metadata.
If you have more complex migration requirements beyond readiness-based tracking, contact our support team to discuss your use case.

​
Benefits

Automated schema migration constraints prevent entire categories of operational failures: Traditional approaches without automation force teams to:
  • Manually track migration progress and control deployment timing
  • Accept the risk of data corruption from out-of-sequence deployments
  • Deal with prolonged outages when migrations execute out of order
  • Face reputational damage from avoidable incidents
Ryvn’s constraint system provides:
  • Automatic verification that migration-capable releases deploy before breaking changes
  • Enforcement that prevents upgrades until migrations fully complete
  • Rollback validation ensuring compatibility with the current schema version
  • Elimination of manual oversight and deployment coordination

​
Best Practices

Multi-release approach is mandatory: Avoid direct transitions from single-schema releases (e.g., V1-only to V2-only). Instead, deploy intermediate releases that handle both schema versions during the transition period. Design for idempotency: Build migration logic that safely handles repeated execution. Implement checks to detect already-migrated data before attempting transformations. Validate rollback paths: Test in pre-production environments that transition releases correctly handle both schemas, migrations execute to completion, and services can roll back while reading migrated data.