Skip to content
OpfieldOpfieldOpfield

Make a copy of a database primary

POST
/api/databases/managed/{id}/availability/make-primary
curl --request POST \
  --url https://opfield.example.com/api/databases/managed/550e8400-e29b-41d4-a716-446655440000/availability/make-primary \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "memberId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "acceptDataLoss": true }'

A planned switch (the primary serves and the copy is eligible) loses nothing. When the primary is gone or no copy is eligible, the switch can lose recent writes: it is refused with 409 AVAILABILITY_LOSSY_PROMOTION and the estimate (details.lossBytes) unless the body has acceptDataLoss: true. A replicated pair without automatic failover switches as planned only while its primary reports: the primary steps down and confirms it before the copy is promoted (the operation fails and promotes nothing without that confirmation), and the copy must stream within the lag bound (409 AVAILABILITY_COPY_NOT_STREAMING unless acceptDataLoss). A primary that does not report is waited for until it was last seen 45 s ago (409 AVAILABILITY_PRIMARY_RECENTLY_SEEN with the seconds left). A member running another database cluster than the primary is never made primary (409 AVAILABILITY_OTHER_CLUSTER). A second switch while one runs is refused (409 AVAILABILITY_OPERATION_PENDING). A member whose server does not report is refused with 409 AVAILABILITY_MEMBER_NOT_CONNECTED (details.memberId, details.nodeId, details.lastReportedAt). Needs databases:edit. Keeps working on an existing set after the license grace period.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string
>= 1 characters
Example
550e8400-e29b-41d4-a716-446655440000

Request Bodyrequired

Section titled “Request Bodyrequired”

JSON request body

Media typeapplication/json
object
memberId
required
string format: uuid
acceptDataLoss
boolean
Examplegenerated
{
  "memberId": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0",
  "acceptDataLoss": true
}

Responses

Section titled “Responses”

202

Section titled “202”

Started

Media typeapplication/json
object
data
required
object
setId
required
string format: uuid
mode
required

Automatic | manual. manual: a replicated pair without automatic failover (no witness host); make a copy primary by hand

string
state
required

Converting | healthy | degraded | no_failover | failing_over | closing | error | paused (the resource is paused)

string
stateReason
required
object
code
required
string
message
string
since
string
durability
required

Synchronous | asynchronous

string
durabilitySource
required

Auto | admin

string
lossWindowText
required

What an unplanned failover can lose with this durability

string
maxLagBytes
required
number
syncDegradeAfterSeconds
required
number
priorityMode
required
boolean
failbackDelaySeconds
required
number
rttP50Ms
required
number | null
rttMeasuredAt
required
string | null
primaryMemberId
required
string | null format: uuid
primarySince
required
string | null
primaryGeneration
required
number
members
required
Array<object>
object
id
required
string format: uuid
nodeId
required
string format: uuid
nodeName
required
string | null
priority
required

Failover preference: higher first, then the older member. members lists the servers in this order, which PUT availability/members/order sets

integer
role
required

Primary | copy | rebuilding | fenced | unknown

string
previousPrimary
required

It still reports itself primary but lost the role in a failover (role shows unknown until it reports)

boolean
eligible
required

Whether this copy may take over now

boolean
eligibilityReason
required
string | null
lagBytes
required
number | null
lagSeconds
required
number | null
syncState
required

Sync | async | none

string
status
required

Creating | ready | error | removing

string
desiredState
required

Member | removing

string
publishedPort
required
integer | null
lastError
required
string | null
lastReportedAt
required
string | null
reporting
required

The member reported recently

boolean
voters
required
Array<string>
witnesses
required
Array<object>
object
id
required
string format: uuid
purpose
required

Lease | keeper

string
hostKind
required

Relay | node

string
relayInstanceId
required
string | null format: uuid
nodeId
required
string | null format: uuid
role
required

Active | standby

string
status
required
string
missingForAutomatic
required
string | null
canLose
required

Servers the set can lose now and keep its primary role

number | null
lease
required
object
mode
required
string
degraded
required
boolean
reason
required
string | null
joint
required
boolean
holderNodeId
required
string | null
policyLeaseHours
required

How long failover keeps working while Opfield is down (the relay policy lease)

number | null
operation
required
object
id
required
string
kind
required
string
step
required
string
startedAt
required
string
lastError
required
string | null
connection
required
object
multiHostUri
required
string | null
hosts
required
Array<object>
object
memberId
required
string
host
required
string
port
required
number
changesBlocked
required

Set when the license no longer covers changes: turning on, adding servers, settings and the failover order are refused; everything else keeps working

string | null
Example
{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Example resource"
  }
}

400

Section titled “400”

Bad request

Media typeapplication/json
object
code
required

Error code

string
message
required

Human-readable error message

string
details

Additional error details

Example
{
  "code": "VALIDATION_ERROR",
  "message": "Request validation failed",
  "details": [
    {
      "path": [
        "name"
      ],
      "message": "Required"
    }
  ]
}

401

Section titled “401”

Authentication required

Media typeapplication/json
object
code
required

Error code

string
message
required

Human-readable error message

string
details

Additional error details

Example
{
  "code": "UNAUTHORIZED",
  "message": "Authentication required"
}

403

Section titled “403”

Forbidden

Media typeapplication/json
object
code
required

Error code

string
message
required

Human-readable error message

string
details

Additional error details

Example
{
  "code": "FORBIDDEN",
  "message": "Insufficient permissions"
}

404

Section titled “404”

Not found

Media typeapplication/json
object
code
required

Error code

string
message
required

Human-readable error message

string
details

Additional error details

Example
{
  "code": "NOT_FOUND",
  "message": "Resource not found"
}

409

Section titled “409”

Conflict

Media typeapplication/json
object
code
required

Error code

string
message
required

Human-readable error message

string
details

Additional error details

Example
{
  "code": "CONFLICT",
  "message": "Resource already exists"
}

422

Section titled “422”

Unprocessable entity

Media typeapplication/json
object
code
required

Error code

string
message
required

Human-readable error message

string
details

Additional error details

Example
{
  "code": "UNPROCESSABLE_ENTITY",
  "message": "Request could not be processed"
}

500

Section titled “500”

Internal server error

Media typeapplication/json
object
code
required

Error code

string
message
required

Human-readable error message

string
details

Additional error details

Example
{
  "code": "INTERNAL_ERROR",
  "message": "Internal server error"
}