-
Notifications
You must be signed in to change notification settings - Fork 18
Open
Description
Summary
Decouple the DocumentDB extension image update from the schema update (ALTER EXTENSION documentdb UPDATE) to enable safe rollback. The binary (image) should always be one version ahead of the schema, following the pgmongo safety-gap pattern.
Details
Background:
- pgmongo follows the safety-gap pattern: binary is always one version ahead of schema version. This ensures rollback safety because the older binary can still read the current schema.
- Current PR Add DocumentDB upgrade support with configurable PostgresImage and ImageVolume extensions #208 couples image update with schema update: when the extension image is updated,
ALTER EXTENSION documentdb UPDATEruns automatically in the same reconciliation cycle. - This is not safe for rollback: if a user rolls back to an older image, the schema may already be at the newer version, causing incompatibility.
Problem with Current Approach:
Upgrade: Image 0.109 → 0.110, then ALTER EXTENSION → Schema 0.110
Rollback: Image 0.110 → 0.109... but Schema is still 0.110!
Result: Old binary cannot read new schema → FAILURE
Safety-Gap Pattern:
Upgrade Phase 1: Image 0.109 → 0.110 (schema stays at 0.109)
- Binary 0.110 can read schema 0.109 ✓
- Rollback to 0.109 is safe (schema still 0.109) ✓
Upgrade Phase 2: ALTER EXTENSION → Schema 0.110 (user-triggered or delayed)
- Binary 0.110 reads schema 0.110 ✓
- Rollback now blocked (schema already updated)
Implementation Approach:
-
Decouple image update from schema update:
- Image update happens when
spec.documentDBVersionorspec.documentDBImagechanges - Schema update (
ALTER EXTENSION) is triggered separately
- Image update happens when
-
Add
spec.schemaVersionfield (optional):spec: documentDBVersion: "0.110.0" # Controls image version schemaVersion: "0.110.0" # Controls schema version (must be <= documentDBVersion)
-
Alternative: Auto-delay schema update:
- Update image immediately
- Delay
ALTER EXTENSIONby N minutes/hours or until explicit trigger - Add status condition showing "schema update pending"
-
Block rollback when schema is ahead:
- If
status.schemaVersion > requested imageVersion, block the change - Require backup or explicit override annotation
- If
Status Fields:
status:
documentDBVersion: "0.110.0" # Current image version
schemaVersion: "0.109.0" # Current schema version (may lag behind)
schemaUpdatePending: true # Schema can be updated to match imageFiles to Modify:
api/preview/documentdb_types.go- AddSchemaVersionto spec and statusinternal/controller/documentdb_controller.go- Decouple upgrade logicinternal/controller/upgrade_logic.go- Separate image vs schema update paths- CRD manifests - Add new fields
Acceptance Criteria:
- Image update and schema update are separate operations
- Binary version is always >= schema version
- Rollback is safe when schema hasn't been updated yet
- Rollback is blocked when schema is ahead of target image version
- Status shows both image version and schema version
- User can trigger schema update explicitly (or auto-delay with configurable time)
- E2E tests verify rollback safety
Reactions are currently unavailable
Metadata
Metadata
Assignees
Labels
No labels