AWS aurora-dsql: Document CDC envelope versioning and minor-version compatibility policy
Summary
Adds a new "CDC envelope versioning" section describing how the CDC JSON envelope format may evolve (new fields, new enum values) and advises applications to check `source.version` and tolerate additive backward-compatible changes; also renames the `source.version` field description from "CDC source metadata format version" to "CDC envelope format version" and links it to the new section.
Security assessment
The added content is a schema/versioning compatibility policy for the CDC record envelope (field additions, new enum values) with no mention of authentication, encryption, credentials, access control, or a specific vulnerability. The only downstream-safety implication (ignore unknown fields, tolerate unknown enum values) is general robustness guidance, not security documentation.
Evidence
To keep your applications working as the CDC record format evolves, check the `source.version` field before processing a record. Aurora DSQL increments the minor version when it makes an additive, backward-compatible change to the CDC record structure.
Diff
diff --git a/aurora-dsql/latest/userguide/cdc-record-format.md b/aurora-dsql/latest/userguide/cdc-record-format.md index 67a629992..0e8690316 100644 --- a//aurora-dsql/latest/userguide/cdc-record-format.md +++ b//aurora-dsql/latest/userguide/cdc-record-format.md @@ -7 +7 @@ -How records map to Amazon KinesisPrimary key in the payloadRecord payloadPayload fieldsFormat detailsWrite-set compactionOversized recordsData type serializationSchema evolution in CDC records +CDC envelope versioningHow records map to Amazon KinesisPrimary key in the payloadRecord payloadPayload fieldsFormat detailsWrite-set compactionOversized recordsData type serializationSchema evolution in CDC records @@ -12,0 +13,6 @@ Aurora DSQL CDC delivers each change as a JSON record. The record uses an envelo +## CDC envelope versioning + +For CDC streams created on or after October 1, 2026, Aurora DSQL can evolve the CDC record format according to the following versioning policy. Streams created before October 1, 2026, continue to use the original envelope format. + +To keep your applications working as the CDC record format evolves, check the `source.version` field before processing a record. Aurora DSQL increments the minor version when it makes an additive, backward-compatible change to the CDC record structure. This includes adding new fields to the record structure or adding new values to enum fields. To stay compatible with new minor versions of the record structure, your applications should ignore new fields. Applications should tolerate unrecognized enum values. + @@ -47 +53 @@ A delete on this table produces a payload where `"before": {"order_id": 1001, "i -The payload uses the following JSON envelope format. +The following examples show the JSON envelope fields available in the current version. @@ -130 +136 @@ Field | Description -`source.version` | The CDC source metadata format version. The current version is `1.0`. +`source.version` | The CDC envelope format version. The current version is `1.0`. For information about compatible changes between versions, see CDC envelope versioning.