Skip to content
OpfieldOpfieldOpfield

Set the failover order of a database

PUT
/api/databases/managed/{id}/availability/members/order
curl --request PUT \
  --url https://opfield.example.com/api/databases/managed/550e8400-e29b-41d4-a716-446655440000/availability/members/order \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "memberIds": [ "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0" ] }'

memberIds lists every server of the set once, the preferred one first (400 INVALID_AVAILABILITY_MEMBER_ORDER otherwise). The order decides which copy takes over first when the primary fails and, with failback on (priorityMode), the server the primary moves back to: the first one, once it was eligible for the failback delay. Changing it never moves the primary by itself. The servers, the lease and the relays get the new order in the background (202); an unchanged order changes nothing. Refused while another availability operation runs (409 AVAILABILITY_OPERATION_PENDING). Needs databases:edit. Needs the current plan with multi-node availability (Business).

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
memberIds
required
Array<string>
>= 2 items <= 5 items
Examplegenerated
{
  "memberIds": [
    "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"
  ]
}

Responses

Section titled “Responses”

202

Section titled “202”

Started (or unchanged)

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