Skip to content

Update database API Reference

PATCH
/tenants/{tenant}/databases/{name}
 
curl --request PATCH \
  --url https://api.kupe.cloud/api/v1/tenants/acme/databases/orders-db \
  --header 'Authorization: <Authorization>' \
  --header 'Content-Type: application/json' \
  --header 'If-Match: 582019' \
  --data '{ "backup": { "retention": 7, "schedule": "Daily" }, "deletionProtection": false, "highAvailability": true, "resources": { "cpu": "500m", "memory": "1Gi", "storage": "10Gi" }, "version": "18" }'

Update a managed database with JSON merge-patch semantics. Only version, resources, highAvailability, deletionProtection and backup can change; at least one is required.

Authorizations

Section titled “ Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “ Path Parameters ”
tenant
required
string

Tenant name

name
required
string

Database name

Header Parameters

Section titled “ Header Parameters ”
If-Match
string

ETag for optimistic locking

Request Body

Section titled “ Request Body ”

Fields to update (at least one required)

Media type application/json
object
backup

Backup settings to change. Omitted fields keep their value. Shortening retention deletes the backups that fall outside the new window.

object
retention

How far back the backups reach, in days: 7 to 35. Default 7.

integer
Example 
7
schedule

How many full backups are kept within the retention period. Daily keeps one for every day. DailyThenWeekly keeps one for each of the last 7 days and one a week before that. The points you can recover to are the same either way; recovering to an older point takes longer. Default Daily.

string
Allowed values: Daily DailyThenWeekly
Example 
Daily
deletionProtection

Turn deletion protection on or off.

boolean
Example 
false
highAvailability

Turn high availability on or off.

boolean
Example 
true
resources

Resources to change. Omitted fields keep their value; storage grows only.

object
cpu

CPU in cores or millicores, without a unit: “500m”, “2” or “0.5”. At most 20 characters.

string
Example 
500m
memory

Memory with a unit suffix (Ki, Mi, Gi, Ti, Pi, Ei or k, M, G, T, P, E): “1Gi”, “512Mi”. At most 20 characters.

string
Example 
1Gi
storage

Storage with a unit suffix, as for memory: “10Gi”. Grows only. At most 20 characters.

string
Example 
10Gi
version

Engine major version. Must equal the current version: major version upgrades are not available yet.

string
Example 
18

Responses

Section titled “ Responses ”

200

Section titled “ 200 ”

Updated database

Media type application/json
object
backup

Backup settings. Null when the database has never set them: it keeps the defaults, 7 days and Daily.

object
retention

How far back the backups reach, in days. Absent when never set: the default, 7, applies.

integer
schedule

How many full backups are kept within the retention period: Daily keeps one for every day, DailyThenWeekly one for each of the last 7 days and one a week before that.

string
Allowed values: Daily DailyThenWeekly
createdAt
string
deletionProtection
boolean
engine
string
generation

Generation increments on every spec change; compare with status.observedGeneration.

integer
highAvailability
boolean
name
string
resourceVersion
string
resources
object
cpu

CPU in cores or millicores, without a unit: “500m”, “2” or “0.5”. At most 20 characters.

string
memory

Memory with a unit suffix (Ki, Mi, Gi, Ti, Pi, Ei or k, M, G, T, P, E): “1Gi”, “512Mi”. At most 20 characters.

string
storage

Storage with a unit suffix, as for memory: “10Gi”. Grows only. At most 20 characters.

string
status
object
backupSizeBytes

Bytes every full backup and all WAL kept for the database take up in storage, manual backups included. 0 until measured.

integer
conditions

Conditions include CredentialsRotating: True (reason RotationPending) while a requested rotation is not yet applied.

Array<object>
object
key
additional properties
currentVersion

CurrentVersion is the full engine version running.

string
instancesDesired
integer
instancesReady
integer
lastBackupAt

When the newest full backup finished (RFC 3339). Empty until the first backup completes.

string
phase
string
Allowed values: Pending Provisioning Running Upgrading Degraded Terminating
previousVersion

PreviousVersion is set while a major upgrade is in progress.

string
recoveryWindow

The oldest and newest points you can recover the database to. Null until the backups report them.

object
earliest

The oldest point you can recover to (RFC 3339).

string
latest

The newest point you can recover to: the newest WAL saved (RFC 3339).

string
rotations

Rotations is the credential rotation state of each role. Wait for a rotation by polling until rotations.{role}.appliedAt equals the requestedAt the rotate-credentials call returned and delivered is true. If requestedAt moves to another token first, a newer rotation replaced it: wait for that one instead.

object
owner
object
appliedAt

AppliedAt is the token of the last rotation the database applied: the new password is in effect in PostgreSQL. The bound credentials Secrets follow it (see Delivered).

string
delivered

Delivered is true once the requested rotation is applied and every binding of the role carries the new password in the credentials Secret of every namespace it lists (true for a role never rotated). The copy into the cluster follows within seconds and is not observed, so a workload restarted the moment this turns true can, rarely, still mount the previous password for a few seconds.

boolean
pending

Pending is true while RequestedAt differs from AppliedAt: the old password still logs in.

boolean
requestedAt

RequestedAt is the token of the last rotation requested; empty if none ever was.

string
readonly
object
appliedAt

AppliedAt is the token of the last rotation the database applied: the new password is in effect in PostgreSQL. The bound credentials Secrets follow it (see Delivered).

string
delivered

Delivered is true once the requested rotation is applied and every binding of the role carries the new password in the credentials Secret of every namespace it lists (true for a role never rotated). The copy into the cluster follows within seconds and is not observed, so a workload restarted the moment this turns true can, rarely, still mount the previous password for a few seconds.

boolean
pending

Pending is true while RequestedAt differs from AppliedAt: the old password still logs in.

boolean
requestedAt

RequestedAt is the token of the last rotation requested; empty if none ever was.

string
readwrite
object
appliedAt

AppliedAt is the token of the last rotation the database applied: the new password is in effect in PostgreSQL. The bound credentials Secrets follow it (see Delivered).

string
delivered

Delivered is true once the requested rotation is applied and every binding of the role carries the new password in the credentials Secret of every namespace it lists (true for a role never rotated). The copy into the cluster follows within seconds and is not observed, so a workload restarted the moment this turns true can, rarely, still mount the previous password for a few seconds.

boolean
pending

Pending is true while RequestedAt differs from AppliedAt: the old password still logs in.

boolean
requestedAt

RequestedAt is the token of the last rotation requested; empty if none ever was.

string
version
string
Example 
{
  "backup": {
    "retention": 7,
    "schedule": "Daily"
  },
  "createdAt": "2026-10-09T10:00:00Z",
  "deletionProtection": true,
  "engine": "postgres",
  "generation": 3,
  "highAvailability": false,
  "name": "orders-db",
  "resourceVersion": "582019",
  "resources": {
    "cpu": "500m",
    "memory": "1Gi",
    "storage": "10Gi"
  },
  "status": {
    "backupSizeBytes": 5368709120,
    "currentVersion": "18.6",
    "instancesDesired": 1,
    "instancesReady": 1,
    "lastBackupAt": "2026-10-21T03:17:00Z",
    "phase": "Pending",
    "previousVersion": "",
    "recoveryWindow": {
      "earliest": "2026-10-14T03:17:00Z",
      "latest": "2026-10-21T09:00:00Z"
    },
    "rotations": {
      "owner": {
        "appliedAt": "2026-10-09T12:00:00.123456789Z",
        "delivered": true,
        "pending": false,
        "requestedAt": "2026-10-09T12:00:00.123456789Z"
      },
      "readonly": {
        "appliedAt": "2026-10-09T12:00:00.123456789Z",
        "delivered": true,
        "pending": false,
        "requestedAt": "2026-10-09T12:00:00.123456789Z"
      },
      "readwrite": {
        "appliedAt": "2026-10-09T12:00:00.123456789Z",
        "delivered": true,
        "pending": false,
        "requestedAt": "2026-10-09T12:00:00.123456789Z"
      }
    }
  },
  "version": "18"
}

Headers

Section titled “ Headers ”
ETag
string

New resource version

400

Section titled “ 400 ”

Validation error, a storage shrink (code storage_shrink_unsupported), a version change (code major_upgrade_unavailable), a backup retention outside the platform’s range (code DATABASE_BACKUP_RETENTION_OUT_OF_RANGE), or backup settings while the platform does not offer backups (code backups_unavailable)

Media type application/json
object
code
string
error
string
field
string
message
string
severity
string
Example generated 
{
  "code": "example",
  "error": "example",
  "field": "example",
  "message": "example",
  "severity": "example"
}

401

Section titled “ 401 ”

Missing or invalid authentication

Media type application/json
object
code
string
error
string
field
string
message
string
severity
string
Example generated 
{
  "code": "example",
  "error": "example",
  "field": "example",
  "message": "example",
  "severity": "example"
}

403

Section titled “ 403 ”

Admin access required

Media type application/json
object
code
string
error
string
field
string
message
string
severity
string
Example generated 
{
  "code": "example",
  "error": "example",
  "field": "example",
  "message": "example",
  "severity": "example"
}

404

Section titled “ 404 ”

Database not found, or databases are switched off and the patch sets more than deletionProtection (code databases_unavailable)

Media type application/json
object
code
string
error
string
field
string
message
string
severity
string
Example generated 
{
  "code": "example",
  "error": "example",
  "field": "example",
  "message": "example",
  "severity": "example"
}

409

Section titled “ 409 ”

The database is being deleted (code terminating); a change that grows it while the tenant is suspended, awaiting a payment method or being deleted (codes tenant_suspended, payment_setup_required, tenant_terminating); or the database kept changing while it was being updated

Media type application/json
object
code
string
error
string
field
string
message
string
severity
string
Example generated 
{
  "code": "example",
  "error": "example",
  "field": "example",
  "message": "example",
  "severity": "example"
}

412

Section titled “ 412 ”

ETag mismatch

Media type application/json
object
code
string
error
string
field
string
message
string
severity
string
Example generated 
{
  "code": "example",
  "error": "example",
  "field": "example",
  "message": "example",
  "severity": "example"
}

429

Section titled “ 429 ”

Rate limit exceeded

Media type application/json
object
code
string
error
string
field
string
message
string
severity
string
Example generated 
{
  "code": "example",
  "error": "example",
  "field": "example",
  "message": "example",
  "severity": "example"
}