Update a physical replication stream

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 <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "failover_at": "2006-01-03T15:04:05Z",
  "status": "FAILING_OVER"
}
'

200

{
  "activation_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"
}

{
  "code": 123,
  "details": [
    {
      "@type": "<string>"
    }
  ],
  "message": "<string>"
}

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: during an update request, status 'REPLICATING' is allowed to transition to 'FAILING_OVER' or 'CANCELED'. Other status transitions are not supported.
• 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: during an update request, status 'REPLICATING' is allowed to transition to 'FAILING_OVER' or 'CANCELED'. Other status transitions are not supported.
• 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 will be present when a replication stream is in the REPLICATING state.

replication_lag_seconds · integer<int32>

replication_lag_seconds is the replication lag (current time minus replicated time) in seconds. This field will be present when a replication stream is in the REPLICATING state.

retained_time · string<date-time>

retained_time is the timestamp indicating the lower bound that the replication stream can failover to. This field will be present when a replication stream is in the REPLICATING state.