Fail the database instance over to its standby.
curl --request POST \ --url https://stratum.example.com/v1/projects/example/db/instances/example/actions/failover \ --header 'Authorization: Bearer <token>'A planned switchover of a Multi-AZ instance: the
instance goes failing-over; the reconciler stops the primary cleanly
(the fence), promotes the standby, moves the endpoint address to it and
swaps the members — seconds, one client reconnect — then rebuilds the
old primary’s side as the new standby (multiAZStatus degraded until
it streams again, then synced). reboot {failover: true} is the same
operation. Cedar-gated on db:FailoverDBInstance. 400 on a single-AZ
instance; 409 unless the instance is available and its pair synced
(a standby that is not synced may lack commits and is never promoted on
request), or while a backup is open on the engine. A failover already in
flight is idempotent.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Responses
Section titled “Responses”Accepted — the instance is failing-over.
A Stratum Database instance. The customer sees the resource and its endpoint; the engine VMs live in the operator sibling project p-system-db and are never listed here.
object
db-…
arn:stratum:db:<region>:<projectId>:db-instance/<id>
Unique among the project’s live instances; also the DNS label’s base.
The exact major.minor running (16.4); a create may ask for "16" and gets the latest published minor.
db.<family>.<size> from GET /v1/db/instance-classes.
GiB of the dedicated data volume; grows online, never shrinks.
Storage autoscaling ceiling in GiB; null = off.
Only when multiAZ: building until the standby streams, synced while it streams within the lag threshold (the primary waits for it on every commit), degraded while it is absent or behind (the primary commits asynchronously; the standby is rebuilt) — also right after a failover, until the vacated side is rebuilt.
The customer’s one network knob — security groups on the endpoint port.
The instance’s endpoint in the customer VPC; null until the endpoint address exists.
object
db-<id>.db.<region>.<parentDomain>, resolving to ip inside the VPC; empty until the name is published.
The VPC-internal VIP — an address in the subnet group’s subnet that follows the primary across failover and blue/green.
Where the master password lives — a secret in the customer’s project, readable by whoever the project’s IAM says and by the engine’s service account through the resource policy the service keeps on it. A password the service generated rotates monthly on the secret’s db_master schedule; one given as masterUserPassword at create is never rotated automatically, only by actions/rotate-master-credential or a schedule the customer sets. rotating while a rotation (scheduled, or actions/rotate-master-credential) is in flight.
object
Days, 1..35.
HH:MM-HH:MM UTC.
ddd:HH:MM-ddd:HH:MM UTC.
“Keep me current”: the pending maintenance actions — a
newer minor of the major AND a newer engine image behind the current
version — apply in the maintenance window on their own. Off: they
are listed on pendingMaintenanceActions and wait for an opt-in.
Always false at 2.0.
The RDS vocabulary mapped onto the reconciler’s phases.
The service-owned engine backend in p-system-db (operator view only; null for tenants)..
object
The auto scaling group of engine VMs.
The data volume.
The current primary engine VM.
The engine VM’s address on the backend network.
The Stratum-owned port in the customer’s subnet the engine VM carries as its second interface (as amended).
The network service VIP fronting the endpoint port — endpoint.ip is its address; failover and blue/green re-point it.
The standby member of a Multi-AZ instance — its own VM, data volume and endpoint port; absent on single-AZ.
object
The operator sibling project the engine VMs and the backup bucket live in.
The bucket holding this instance’s snapshots and WAL archive. It is the SERVICE’s bucket, in the sibling project — a tenant cannot open it, which is why it is here and not on the tenant’s view.
The engine state the agent last reported.
The db-agent version the engine VM is running.
Disruptive changes waiting for the maintenance window:
instanceClass, engineVersion, multiAZ, plus applyImmediately
while the customer asked for them now. Readable until the reconciler
has applied them — the row’s own fields flip when the replacement
engine reports from the target, never before. Empty ({}) when
nothing is pending.
object
What the operator’s catalog holds that this instance does not run
yet: a newer minor of its major, a newer image behind its
version. Empty when the instance is current. Applied in the
maintenance window with autoMinorVersionUpgrade, or on an opt-in.
One thing the operator’s engine catalog holds that this instance does
not run yet. Observed by the reconciler every pass on
a live engine; applied in the maintenance window when
autoMinorVersionUpgrade is on or the customer opted in
(actions/apply-pending-maintenance).
object
db-upgrade — a newer published minor of the instance’s major;
system-update — a newer engine image behind its current version
(OS and agent updates, a rebuilt engine).
The db-upgrade target minor.
The system-update image (operator view only).
The customer’s opt-in on this action, when any.
Whether the action applies in the next maintenance window without further action.
The engine’s word on its parameter group: pending-reboot
when a static parameter changed and waits for a restart — the next
maintenance window, a reboot, or a modify with applyImmediately.
Absent until the engine has reported.
The blue/green deployment this instance belongs to, whichever side it is on; absent when it has none. A client can tell from a LIST — with no call per row — that the shape-changing actions (modify, delete, credential rotation) are refused while a deployment is live.
Which copy this is: blue the customer’s own instance a live
deployment deploys FROM, green the copy being built, old the
retained former blue after a switchover. Absent with blueGreenId.
The deployment’s status, so a list can say one is running without a second call.
Why the engine did NOT apply its parameter group — a
shared_preload_libraries entry whose library the running engine
image does not carry. The engine keeps serving the configuration it
has; parameterApplyStatus is failed while this is set.
The curated extensions the service keeps in this instance’s
databases. The master role is never superuser, so an
untrusted extension — pg_stat_statements and the rest of
GET /v1/db/engine-versions’ supportedExtensions — is created by
the service, in every database and in template1 so a new database
inherits it. A TRUSTED extension (pg_trgm, citext, pgcrypto…)
is not listed here: the master role creates those itself. Removing
one drops it, unless something depends on it.
The engine’s word on extensions: in-sync once every one exists
everywhere it belongs, applying while it does not, failed with
extensionApplyError when the engine refused one. Absent until the
engine has reported.
The engine’s own words for an extension it would not create or drop (most often a drop something depends on).
How far the continuous WAL archive reaches — the newest point a point-in-time restore can target. Null until the first segment is archived.
object
Example
{ "engine": "postgres", "multiAZStatus": "synced", "masterUserSecret": { "status": "creating" }, "status": "creating", "pendingMaintenanceActions": [ { "action": "db-upgrade", "optInStatus": "immediate" } ], "parameterApplyStatus": "in-sync", "blueGreenRole": "blue", "extensionApplyStatus": "in-sync"}Bad request.
object
The findings of a rejected IAM policy document (custom and resource policies).
One finding of a rejected IAM policy document. A rejection lists every finding, so the author fixes the document in one round trip.
object
The finding, e.g. INVALID_DOCUMENT, UNKNOWN_ACTION, ACTION_NOT_APPLICABLE.
Index of the statement at fault; -1 for the document as a whole.
The offending action, where one is at fault (ACTION_NOT_APPLICABLE).
Field errors, for codes that carry them: each problem at its field
(see FieldError). Documented on the responses that set it, e.g.
approveNodeJoin’s INVALID_INPUT and JOIN_APPROVAL_REFUSED.
Absent otherwise.
One field’s problem, the stage-2 installer API’s shape.
field is the field’s path, message what is wrong with it.
object
The field’s path, e.g. links[0].interface, disks[1].confirm,
mgmt.address or role; empty for the whole request.
Structured facts about the refusal, for codes that carry them. The
shape is fixed per code and documented on the response that answers
it, e.g. IMAGE_POOL_MISMATCH (see ImagePoolMismatchDetails) and
IMAGE_IN_USE. Absent for codes that carry none.
object
Example
{ "issues": [ { "code": "ACTION_NOT_APPLICABLE", "action": "compute:CreateVpc" } ]}Authenticated but not authorized.
object
The findings of a rejected IAM policy document (custom and resource policies).
One finding of a rejected IAM policy document. A rejection lists every finding, so the author fixes the document in one round trip.
object
The finding, e.g. INVALID_DOCUMENT, UNKNOWN_ACTION, ACTION_NOT_APPLICABLE.
Index of the statement at fault; -1 for the document as a whole.
The offending action, where one is at fault (ACTION_NOT_APPLICABLE).
Field errors, for codes that carry them: each problem at its field
(see FieldError). Documented on the responses that set it, e.g.
approveNodeJoin’s INVALID_INPUT and JOIN_APPROVAL_REFUSED.
Absent otherwise.
One field’s problem, the stage-2 installer API’s shape.
field is the field’s path, message what is wrong with it.
object
The field’s path, e.g. links[0].interface, disks[1].confirm,
mgmt.address or role; empty for the whole request.
Structured facts about the refusal, for codes that carry them. The
shape is fixed per code and documented on the response that answers
it, e.g. IMAGE_POOL_MISMATCH (see ImagePoolMismatchDetails) and
IMAGE_IN_USE. Absent for codes that carry none.
object
Example
{ "issues": [ { "code": "ACTION_NOT_APPLICABLE", "action": "compute:CreateVpc" } ]}Resource not found.
object
The findings of a rejected IAM policy document (custom and resource policies).
One finding of a rejected IAM policy document. A rejection lists every finding, so the author fixes the document in one round trip.
object
The finding, e.g. INVALID_DOCUMENT, UNKNOWN_ACTION, ACTION_NOT_APPLICABLE.
Index of the statement at fault; -1 for the document as a whole.
The offending action, where one is at fault (ACTION_NOT_APPLICABLE).
Field errors, for codes that carry them: each problem at its field
(see FieldError). Documented on the responses that set it, e.g.
approveNodeJoin’s INVALID_INPUT and JOIN_APPROVAL_REFUSED.
Absent otherwise.
One field’s problem, the stage-2 installer API’s shape.
field is the field’s path, message what is wrong with it.
object
The field’s path, e.g. links[0].interface, disks[1].confirm,
mgmt.address or role; empty for the whole request.
Structured facts about the refusal, for codes that carry them. The
shape is fixed per code and documented on the response that answers
it, e.g. IMAGE_POOL_MISMATCH (see ImagePoolMismatchDetails) and
IMAGE_IN_USE. Absent for codes that carry none.
object
Example
{ "issues": [ { "code": "ACTION_NOT_APPLICABLE", "action": "compute:CreateVpc" } ]}Conflicting state.
object
The findings of a rejected IAM policy document (custom and resource policies).
One finding of a rejected IAM policy document. A rejection lists every finding, so the author fixes the document in one round trip.
object
The finding, e.g. INVALID_DOCUMENT, UNKNOWN_ACTION, ACTION_NOT_APPLICABLE.
Index of the statement at fault; -1 for the document as a whole.
The offending action, where one is at fault (ACTION_NOT_APPLICABLE).
Field errors, for codes that carry them: each problem at its field
(see FieldError). Documented on the responses that set it, e.g.
approveNodeJoin’s INVALID_INPUT and JOIN_APPROVAL_REFUSED.
Absent otherwise.
One field’s problem, the stage-2 installer API’s shape.
field is the field’s path, message what is wrong with it.
object
The field’s path, e.g. links[0].interface, disks[1].confirm,
mgmt.address or role; empty for the whole request.
Structured facts about the refusal, for codes that carry them. The
shape is fixed per code and documented on the response that answers
it, e.g. IMAGE_POOL_MISMATCH (see ImagePoolMismatchDetails) and
IMAGE_IN_USE. Absent for codes that carry none.
object
Example
{ "issues": [ { "code": "ACTION_NOT_APPLICABLE", "action": "compute:CreateVpc" } ]}