Merge pull request #29 from datastax/telling-the-cdc-story

Add clarifications about schema-compatibility-strategy and table updates.

Author: ddieruf

modules/use-cases-architectures/pages/change-data-capture/index.adoc

@@ -46,7 +46,7 @@ KeyValue offers an interesting way to encode a message called “Separated”. T
 
 In the context of CDC there are a few schema configurations of note. All of these are specific to the namespace where the event and data topics are logically located.
 
-- *schema-compatibility-strategy*: this setting is for producers, it directs the Broker how to handle new schemes introduced to existing topics. In CDC this is relevant when you change a table’s design. For example if a new column is added, the schema is changed to include that new value. This configuration decides if the namespace will allow this. CDC uses a strategy of “BACKWARD_TRANSITIVE”. This means adding new optional fields and the removal of fields are both allowed. Learn more about the different types of strategies in the https://pulsar.apache.org/docs/next/schema-understand/#schema-compatibility-check-strategy[pulsar docs^]{external-link-icon}.
+- *schema-compatibility-strategy*: this setting is for producers, it directs the Broker how to handle new schemes introduced to existing topics. In CDC this is relevant when you change a table’s design. For example if a new column is added, the schema is changed to include that new value. The chosen schema-compatibility-strategy decides if the namespace will allow this. You have the option of choosing what strategy is used. The default is "BACKWARD_TRANSITIVE" and is highly recommended. Using this strategy means adding new optional fields and the removal of fields are both allowed. Learn more about the different types of strategies in the https://pulsar.apache.org/docs/next/schema-understand/#schema-compatibility-check-strategy[pulsar docs^]{external-link-icon}.
 
 - *allow-auto-update-schema*: given the compatibility strategy this setting is a flag deciding if an update to the schema is generally allowed. CDC sets this to ‘true’, so changes in a table’s design can automatically propagate to the topic.
 

modules/use-cases-architectures/pages/change-data-capture/table-schema-evolution.adoc

@@ -50,6 +50,8 @@ Altering a table column includes renaming a column or changing a column’s type
 
 While technically updating columns is possible when CDC is enabled, it is not recommended. Instead, changes to a Cassandra table should be additive only. If you are familiar with data migrations, this concept is the same. If you need to change the name or type of table column, add a new column. The resulting event messages will have a reference to both columns, and you can handle this migration downstream.
 
+Note that this recommendation assumes a schema-compatibility-strategy of BACKWARD_TRANSITIVE. If you are using a different strategy, table updates will be handled differently.
+
 == Removing a table column
 
 Removing a table column is a simple command in CQL. The resulting CDC data messages will simply not include that data anymore.