Multi-region operations

An entity’s primary region accepts its writes. Its origin records where it was created. The project’s primary region is separate: it is where project resources replicate from and, in pinned-region mode, where entities accept writes.

Reads can be served locally from replicated state. A local read can therefore lag behind a write accepted elsewhere. If an operation requires the latest state, use a handler routed to the entity’s primary region rather than assuming its nearest replica is current.

In request-region mode, the entity’s primary can move to the region receiving a write. The new primary must catch up before accepting it, and all regions must be reachable for that transition. Later writes in that region avoid another transfer.

In pinned-region mode, entities use the project’s primary region. Writes arriving elsewhere are forwarded there. Changing the primary or handling a regional outage is an operator action.

Replicated writes are another option for Event Sourced Entities: regions update independently using conflict-free replicated data types. That requires state that can be merged and accepts eventual consistency.

Replication resumes from recorded progress after an interruption. A surviving region can serve only the writes it has received. Failover can lose writes that never reached a surviving replica; returning regions can also contain conflicting changes that must be resolved.

Replication filters constrain where entity data is copied. They help enforce residency requirements, but do not replace choosing appropriate project regions or following the supported primary-transition procedure.