Create a physical replication stream

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

• CLUSTER_ADMIN

POST /api/v1/physical-replication-streams

cURL

cURL

curl --request POST \
  --url https://cockroachlabs.cloud/api/v1/physical-replication-streams \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "primary_cluster_id": "<string>",
  "standby_cluster_id": "<string>"
}
'

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.

Body

application/json

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 cluster that data is being replicated to.

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.