Update a physical replication stream

Only two status values are accepted. FAILING_OVER starts a failover; send it once the stream reports a replicated_time. CANCELED cancels a stream that has not completed or been canceled. During a failover, it is refused unless the stream has no replicated_time or replication has paused or errored. Other values return InvalidArgument. During a failover, send failover_at alone to reschedule it.

Can be used by the following roles assigned at the organization, folder or cluster scope:

• CLUSTER_ADMIN

PATCH /api/v1/physical-replication-streams/{id}

cURL

cURL

curl --request PATCH \
  --url https://cockroachlabs.cloud/api/v1/physical-replication-streams/{id} \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --json '{"failover_at":"2006-01-03T15:04:05Z","status":"FAILING_OVER"}'

200

{
  "activated_at": "2006-01-03T15:04:15Z",
  "created_at": "2006-01-02T15:04:05Z",
  "failover_at": "2006-01-03T15:04:05Z",
  "id": "00000000-0000-0000-0000-000000000001",
  "primary_cluster_id": "00000000-0000-0000-0000-000000000002",
  "replicated_time": "2006-01-03T15:04:04Z",
  "retained_time": "2006-01-02T15:04:06Z",
  "standby_cluster_id": "00000000-0000-0000-0000-000000000003",
  "status": "COMPLETED"
}

PREVIEW

This endpoint is in Preview and subject to change. Refer to the API support policy for more details.

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

id · string · required

id is the ID of the replication stream to update.

Body

application/json

spec contains the information that is being updated for the given replication stream.

failover_at · string<date-time>

failover_at is the crdb system time at which failover occurs. If the user sets the status to 'FAILING_OVER' but omits failover_at, the failover time will default to the latest consistent replicated time. Otherwise, the user can pick a time up to one hour in the future to schedule a failover, or a time in the past to restore the cluster to a recent state. If the time is in the past, the API will make a best-effort attempt to validate that the time is not earlier than the retained time. In this case, if the retained time is updated in between validation and failover execution and the failover time becomes invalid, the stream will failover to the retained time. failover_at is not required when updating the status to 'CANCELED'.

status · enum<string>

status describes the desired status of the replication stream.

• STARTING: signifies that a stream is starting
• REPLICATING: signifies that the standby is receiving the primary's changes. Failover is available once the stream reports a 'replicated_time'.
• FAILING_OVER: used to trigger a failover, or to signify that a failover is occurring.
• COMPLETED: signifies that a failover is complete.
• CANCELED: signifies that a stream is canceled.

Available options: STARTING, REPLICATING, FAILING_OVER, COMPLETED, CANCELED

Response

200

application/json

A successful response.

created_at · string<date-time> · required

created_at is the timestamp at which the replication stream was created.

id · string · required

id is the UUID of the replication stream.

primary_cluster_id · string · required

primary_cluster_id is the ID of the cluster that is being replicated.

standby_cluster_id · string · required

standby_cluster_id is the ID of the standby cluster that data is being replicated to.

status · enum<string> · required

status describes the desired status of the replication stream.

• STARTING: signifies that a stream is starting
• REPLICATING: signifies that the standby is receiving the primary's changes. Failover is available once the stream reports a 'replicated_time'.
• FAILING_OVER: used to trigger a failover, or to signify that a failover is occurring.
• COMPLETED: signifies that a failover is complete.
• CANCELED: signifies that a stream is canceled.

Available options: STARTING, REPLICATING, FAILING_OVER, COMPLETED, CANCELED

activated_at · string<date-time>

activated_at is the crdb system time at which failover is finalized. This may differ from the time for which failover was requested. This field will be present when a replication stream is in the COMPLETED state.

canceled_at · string<date-time>

canceled_at is the timestamp at which the replication stream was canceled.

failover_at · string<date-time>

failover_at is the time for which failover is requested. If the user sets the status to 'FAILING_OVER' but omits failover_at, the failover time will default to the latest consistent replicated time. Otherwise, the user can pick a time up to one hour in the future to schedule a failover, or a time in the past to restore the cluster to a recent state. This field will be present if the user has requested failover at a future time.

replicated_time · string<date-time>

replicated_time is the timestamp indicating the point up to which data has been replicated. The window between replicated_time and the actual time is known as replication lag. This field is absent until the standby has copied the primary's existing data. Failover is available only once it is present.

replication_lag_seconds · integer<int32>

replication_lag_seconds is the replication lag (current time minus replicated time) in seconds. This field is present whenever replicated_time is.

retained_time · string<date-time>

retained_time is the timestamp indicating the lower bound that the replication stream can failover to. This field is absent until the standby reports it.