Create a database instance.
curl --request POST \ --url https://stratum.example.com/v1/projects/example/db/instances \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "name": "example", "engine": "postgres", "engineVersion": "example", "instanceClass": "example", "allocatedStorage": 1, "maxAllocatedStorage": 1, "storageClass": "example", "multiAZ": false, "availabilityZone": "example", "dbSubnetGroupName": "example", "dbParameterGroupName": "example", "vpcSecurityGroupIds": [ "example" ], "masterUsername": "example", "masterUserPassword": "example", "backupRetentionPeriod": 7, "preferredBackupWindow": "example", "preferredMaintenanceWindow": "example", "autoMinorVersionUpgrade": true, "deletionProtection": false, "publiclyAccessible": false, "extensions": [ "example" ], "tags": { "additionalProperty": "example" } }'Records the desired state and returns 202 with the
row in creating; the db reconciler (ScopeLeader, 30 s) builds the
engine VM in the operator sibling project p-system-db, the data volume,
the endpoint in the customer VPC and the master secret, then flips the
row to available. The subnet group and parameter group must exist in
the project; engineVersion must be published (GET /v1/db/engine-versions);
instanceClass must be an active class. Counted against
db.instances.count and db.storage_bytes. publiclyAccessible: true is
refused at 2.0. Cedar-gated on db:CreateDBInstance.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Request Bodyrequired
Section titled “Request Bodyrequired”object
16 (latest published minor) or an exact 16.4 from GET /v1/db/engine-versions.
GiB.
One of the operator’s tiers; the default class when omitted.
Placement preference for the primary; must be one of the subnet group’s AZs.
Defaults to default.postgres<major>.
postgres and the pg_ prefix are the engine’s and refused.
Optional. Omitted: the service generates the password into
the instance’s master secret and rotates it monthly on a db_master
schedule it keeps on that secret. Given: the password is yours and is
never rotated automatically (the RDS model) — it changes only when you
change it: actions/rotate-master-credential rotates it once, and a
schedule you set on the secret (stratumctl secrets rotation set <secret-id> --type db_master --target <db-instance-id> --cron '0 3 1 * *')
rotates it on yours. 8–128 printable ASCII characters without /,
@, " or a space. Never returned.
Refused when true at 2.0.
The curated extensions the service creates in every database of this
instance (supportedExtensions on the engine version): the
untrusted ones the master role cannot create itself. An extension
that needs a shared_preload_libraries entry the parameter group
does not carry is refused here.
object
Responses
Section titled “Responses”Accepted — the instance is creating.
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" } ]}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" } ]}Request rate limit exceeded. The API-boundary throttle caps request throughput per principal and per project; code is RATE_LIMITED (distinct from the quota engine’s QUOTA_EXCEEDED). The Retry-After header carries the seconds to wait. Applies to any authenticated endpoint — it is enforced by middleware, not per-path.
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" } ]}Headers
Section titled “Headers”Seconds to wait before retrying.
Upstream temporarily unavailable (driver / scheduler / dependency).
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" } ]}