Backward compatibility
When you change your schema, it’s important you keep it compatible with previous versions of the schema, so that old snapshots can be loaded. Schemalang supports backward compatibility by default.
When you’ve made a change to your schema, you can use the C++, C# or Java SDKs to update a snapshot to the new schema.
Making changes to schema
These are the kinds changes to the schema you can make and still maintain backward compatibility:
- Rename a field or component
- Remove a field
- Add a new
option
,list
ormap
field - Convert between collection and non-collection types
- Add a new non-collection field
- Replace a field or group of fields with a different representation
Rename a field or component
You can rename fields or components as you like without risking breaking anything, because snapshots only store field and component IDs, not their names. (You’ll still need to update the worker code to use the new names.)
Remove a field
Fields can be removed without breaking anything, because unknown fields are ignored when reading a snapshot.
Add a new option
, list
or map
field
You can add generic collection fields without breaking snapshots, because they can be empty. When a snapshot is loaded, all entities will have an empty data structure for the new field.
If the field needs to be populated with some initial data, do this with C++, C# or Java SDK before loading the snapshot.
Convert between collection and non-collection types
You can change types between an option<T>
field containing a value, a list<T>
field containing
single element, and a singular T
field, as long as you migrate the snapshot using the
C++, C#, or
Java SDK first.
(This works because the snapshot data formats for three types are identical.) You need to
make sure that every entity has exactly one value for the field.
Similarly, you can replace an empty option
with an empty list
, and vice versa.
Furthermore, you can change a map<K, V>
field to a list<T>
field (and vice versa), where T
is
defined as:
type T {
K key = 1;
V value = 2;
}
Add a new non-collection field
Adding a field that isn’t a collection is trickier, as the data must be present for each entity in the snapshot. Adding a non-collection field without making sure the data is present will break existing snapshots.
To add a new non-collection field:
- Add an
option<T>
field. - Migrate the snapshot using the C++, C# or Java SDK to fill in the value for every entity.
- Replace the
option<T>
field with a bareT
field.
Replace a field or group of fields with a different representation
You can’t directly change the type of a field or a group of fields (for example converting an integer into a floating-point value) without breaking snapshots.
You’ll need to: