Rules of Mutations

Schema evolution

• Mutation definitions can’t be removed after they were added to your app.
• Mutation schema definitions can be evolved as long as the changes are forward-compatible.
  • That means data encoded with the old schema can be decoded with the new schema.
    • In practice, this means …
      • for structs … - you can add new fields if they have default values or are optional - you can remove fields

Derived mutations

• When using enabledCud on a table definition, LiveStore will automatically generate some mutations for you. This includes a insert, update, and delete mutation.

Other Notes

• Mutations need to be deterministic. This means that the same input will always produce the same output.
• When re-using existing schema definitions for mutation schemas, be careful to also apply the rules of mutations to the schema definitions you are re-using. A more conservative approach is to copy the schema definitions and evolve them separately.

Syncing related

• SQL writes need to be deterministic e.g. have no branching/reading.

Non-persisted mutations

Sometimes it can be useful to not persist mutations but still sync them across clients (e.g. for frequent in-progress updates like position updates during a drag & drop interaction). Calling store.mutate({ persisted: false }, myMutation) will still apply and sync the mutation but won’t persist it in the mutation log and in the sync server.

It’s important that the “final mutation” sets explicit values (and e.g. doesn’t increment an existing value) i.e. shouldn’t care about what the current value is.