Description
Describe the content issue:
In DataStore's schema update section, it is relevant to include scenarios such as if the app has already made it to production or not. This is especially important for iOS/Android apps since the previous version of the app is still being used by customers.
URL page where content issue is:
https://docs.amplify.aws/lib/datastore/schema-updates/q/platform/ios/
This issue is to capture the sections I'd like to see on the page, building off of the example schema on the page:
enum PostStatus {
ACTIVE
INACTIVE
STAGED # new enum value
}
type Post @model {
id: ID!
title: String!
rating: Int!
status: PostStatus!
}
Schema update scenarios for production released app
The following are breaking changes to your users using the previous version of the app.
Adding a new enum case
enum PostStatus {
ACTIVE
INACTIVE
STAGED # new enum value
}
The previous app will fail to decode new posts where where the status is set to STAGED since the schema local to the previous version of the app does not contain the new enum value.
Adding a required field
type Post @model {
id: ID!
title: String!
rating: Int!
status: PostStatus!
subtitle: String! // new required field
}
The previous app will successfully decode the new post data with subtitle field values but ignored since the local schema does not contain the required field.
The updated app will fail to decode all previously created posts from the previous app, or any data that does not contain subtitle. This will require a backfill of data before launching the new app.
Adding an optional field
type Post @model {
id: ID!
title: String!
rating: Int!
status: PostStatus!
subtitle: String // new optional field
}
The previous app and updated app will successfully continue to decode posts with or without the field since it is an optional field. The previous app's local schema isn't aware of the new optional field, thus dropping any subtitle values that exist on the post data. The updated app will decode to the null subtitle for posts created from previous apps or new posts that do not have a value for the field.
Forward compatibility issue
In the scenarios where a new field is being added to the model and the previous app operates on data created by the new app. When the previous app modifies the new post, the update observed by the new app will create a temporary discrepancy in which the new field is nil.
This is because DataStore creates a GraphQL mutation request for the update from the previous app and specifies what is returned to the new app's subscription to this mutation. Since the previous app's local schema doesn't have the new field, it will cause a mutation response of the new field null. Even if the database contains the new field value, the update from the previous app will cause the new app to reconcile the data observed wth the new field set to null
Best practice / Recommended approaches?
A section describing how to handle forward compatibility for native apps. Force end users to upgade from previous to new app? Force upgrade can be staged out, such as previous app upgrade to new schema without any functionality difference, then upgrade to new functionality.
Backfilling approach
A section describing a typical workflow for backfilling DynamoDB data. This section should include not just the data table but the sync related tables if it is necessary to achieve a successful 'backfill" in the context of a DataStoe enabled backend.