Propagation downstream of $ZTWORMHOLE set by trigger logic
Final Release Note
If trigger logic on an originating instance sets the $ZTWORMHOLE intrinsic special variable, that value is propagated in the replication stream to receiving instances. Previously, any value $ZTWORMHOLE value set within a trigger was ignored. Note that use of $ZTWORMHOLE requires some care, as it is intended for specialized use cases. In general, applications should use global variables to propagate updates down a replication stream.
-
As before, if application code sets $ZTWORMHOLE before a trigger is invoked, it is propagated downstream only if trigger logic references it.
-
If there are values are assigned to $ZTWORMHOLE at multiple times in trigger logic, or in both the application and the trigger, the value at the time the trigger completes execution is propagated.
-
Use of this advanced functionality requires a little additional logic in trigger design. A trigger will need to distinguish between running on an originating primary instance, where it would set $ZTWORMHOLE vs. on a replicating secondary instance, where it would use the provided $ZTWORMHOLE. An efficient way to accomplish this is for applications to set different values for the environment variable ydb_sysid on originating and replicating instances, and for the trigger code to check the value of the $SYSTEM intrinsic special variable whose second piece is set at process startup from
$ydb_sysid
.
Description
The purpose of the $ZTWORMHOLE intrinsic special variable is to provide context from a primary instance originating updates to a trigger and thence to a secondary instance receiving and applying updates (e.g., values of selected local variables, since a trigger starts with no local variables, effectively an argumentless NEW). If application code sets a value in $ZTWORMHOLE and a trigger references $ZTWORMHOLE, the value is propagated in the replication stream so that a trigger on the receiving instance can use that context to execute its logic.
However, trigger logic might not just use context, it might also generate context, e.g., a timestamp. In the current implementation, if a trigger sets $ZTWORMHOLE, that value is not propagated in the replication stream; only values set in application code outside triggers are propagated, and that too only if the trigger logic references them. This Issue aims to overcome this limitation.
Draft Release Note
If trigger logic on an originating instance sets the $ZTWORMHOLE intrinsic special variable, that value is propagated in the replication stream to receiving instances. Previously, any value $ZTWORMHOLE value set within a trigger was ignored. Note that use of $ZTWORMHOLE requires some care, as it is intended for specialized use cases. In general, applications should use global variables to propagate updates down a replication stream.
-
As before, if application code sets $ZTWORMHOLE, it is propagated downstream only if trigger logic references it.
-
If there are values are assigned to $ZTWORMHOLE at multiple times in trigger logic, or in both the application and the trigger, the value at the time the trigger completes execution is propagated.
-
If a database update results in the invocation of multiple triggers, more than one of which sets $ZTWORMHOLE, it is indeterminate as to which value is propagated.
-
Use of this advanced functionality requires a little additional logic in trigger design. A trigger will need to distinguish between running on an originating primary instance, where it would set $ZTWORMHOLE vs. on a replicating secondary instance, where it would use the provided $ZTWORMHOLE. An efficient way to accomplish this is for applications to set different values for the environment variable ydb_sysid on originating and replicating instances, and for the trigger code to check the value of the $SYSTEM intrinsic special variable whose second piece is set at process startup from
$ydb_sysid
. [#727 (closed)]