---
title: "Apply database upgrade"
method: POST
path: "/v1/databases/{database_id}/upgrade"
tags: ["Database"]
---

# Apply database upgrade

`POST /v1/databases/{database_id}/upgrade`

Applies a minor-version upgrade to a database. The target image must be a stable manifest entry in the same Postgres major / Spock major bucket as the current version and strictly newer. Container pull and restart happen asynchronously; this endpoint returns once redeployment is triggered.

## Path parameters

- `database_id` string, required

## Request body

- ApplyUpgradeRequest
  - `image` string, required — Full container image reference of the upgrade target. Must match the image field of a stable manifest entry in the same Postgres major / Spock major bucket as the current version and be strictly newer.

## Response `200`

OK response.

- ApplyUpgradeResponse
  - `database` Database, required
    - `available_upgrades` AvailableUpgrade[] — Newer stable image versions available in the same Postgres major / Spock major bucket. Present only when ?include=available_upgrades is set.
      - `image` string, required — Full container image reference for the upgrade candidate.
      - `postgres_version` string, required — Postgres version of the upgrade candidate.
      - `spock_version` string, required — Spock major version of the upgrade candidate.
    - `created_at` string, date-time, required — The time that the database was created.
    - `id` string, required — Unique identifier for the database.
    - `instances` Instance[] — All of the instances in the database.
      - `connection_info` InstanceConnectionInfo — Connection information for a pgEdge instance.
        - `addresses` string[] — The addresses of the host that's running this instance.
        - `port` integer — The host port that Postgres is listening on for this instance.
      - `created_at` string, date-time, required — The time that the instance was created.
      - `error` string — An error message if the instance is in an error state.
      - `host_id` string, required — The ID of the host this instance is running on.
      - `id` string, required — Unique identifier for the instance.
      - `node_name` string, required — The Spock node name for this instance.
      - `postgres` InstancePostgresStatus — Postgres status information for a pgEdge instance.
        - `patroni_paused` boolean — True if Patroni is paused for this instance.
        - `patroni_state` string
        - `pending_restart` boolean — True if this instance has a pending restart from a configuration change.
        - `role` string
        - `version` string — The version of Postgres for this instance.
      - `spock` InstanceSpockStatus — Spock status information for a pgEdge instance.
        - `read_only` string — The current spock.readonly setting.
        - `subscriptions` InstanceSubscription[] — Status information for this instance's Spock subscriptions.
          - `name` string, required — The name of the subscription.
          - `provider_node` string, required — The Spock node name of the provider for this subscription.
          - `status` string, required — The current status of the subscription.
        - `version` string — The version of Spock for this instance.
      - `state` 'creating' | 'modifying' | 'deleting' | 'backing_up' | 'available' | 'degraded' | 'failed' | 'stopped' | 'unknown', required
      - `status_updated_at` string, date-time — The time that the instance status information was last updated.
      - `updated_at` string, date-time, required — The time that the instance was last modified.
    - `service_instances` ServiceInstance[] — Service instances running alongside this database.
      - `created_at` string, date-time, required — The time that the service instance was created.
      - `database_id` string, required — The ID of the database this service belongs to.
      - `error` string — An error message if the service instance is in an error state.
      - `host_id` string, required — The ID of the host this service instance is running on.
      - `service_id` string, required — The service ID from the DatabaseSpec.
      - `service_instance_id` string, required — Unique identifier for the service instance.
      - `state` 'creating' | 'running' | 'failed' | 'deleting', required — Current state of the service instance.
      - `status` ServiceInstanceStatus — Runtime status information for a service instance.
        - `addresses` string[] — The addresses of the host that's running this service instance.
        - `container_id` string — The Docker container ID.
        - `health_check` HealthCheckResult — Health check result for a service instance.
          - `checked_at` string, date-time, required — The time this health check was performed.
          - `message` string — Optional message about the health status.
          - `status` 'healthy' | 'unhealthy' | 'unknown', required — The health status.
        - `image_version` string — The container image version currently running.
        - `last_health_at` string, date-time — The time of the last health check attempt.
        - `ports` PortMapping[] — Port mappings for this service instance.
          - `container_port` integer — The port number inside the container.
          - `host_port` integer — The port number on the host (if port-forwarded).
          - `name` string, required — The name of the port (e.g., 'http', 'web-client').
        - `service_ready` boolean — Whether the service is ready to accept requests.
      - `updated_at` string, date-time, required — The time that the service instance was last updated.
    - `spec` DatabaseSpec
      - `backup_config` BackupConfigSpec
        - `repositories` BackupRepositorySpec[], required — The repositories for this backup configuration.
          - `azure_account` string — The Azure account name for this repository. Only applies when type = 'azure'.
          - `azure_container` string — The Azure container name for this repository. Only applies when type = 'azure'.
          - `azure_endpoint` string — The optional Azure endpoint for this repository. Only applies when type = 'azure'.
          - `azure_key` string — The Azure storage account access key to use for this repository. This field will be excluded from the response of all endpoints. It can also be omitted from update requests to keep the current value.
          - `base_path` string — The base path within the repository to store backups. Required for type = 'posix' and 'cifs'.
          - `custom_options` object — Additional options to apply to this repository.
          - `gcs_bucket` string — The GCS bucket name for this repository. Only applies when type = 'gcs'.
          - `gcs_endpoint` string — The optional GCS endpoint for this repository. Only applies when type = 'gcs'.
          - `gcs_key` string — Optional base64-encoded private key data. If omitted, pgbackrest will use the service account attached to the instance profile. This field will be excluded from the response of all endpoints. It can also be omitted from update requests to keep the current value.
          - `id` string — The unique identifier of this repository.
          - `retention_full` integer — The count of full backups to retain or the time to retain full backups.
          - `retention_full_type` 'time' | 'count' — The type of measure used for retention_full.
          - `s3_bucket` string — The S3 bucket name for this repository. Only applies when type = 's3'.
          - `s3_endpoint` string — The optional S3 endpoint for this repository. Only applies when type = 's3'.
          - `s3_key` string — An optional AWS access key ID to use for this repository. If not provided, pgbackrest will use the default credential provider chain. This field will be excluded from the response of all endpoints. It can also be omitted from update requests to keep the current value.
          - `s3_key_secret` string — The corresponding secret for the AWS access key ID in s3_key. This field will be excluded from the response of all endpoints. It can also be omitted from update requests to keep the current value.
          - `s3_region` string — The region of the S3 bucket for this repository. Only applies when type = 's3'.
          - `type` 's3' | 'gcs' | 'azure' | 'posix' | 'cifs', required — The type of this repository.
        - `schedules` BackupScheduleSpec[] — The schedules for this backup configuration.
          - `cron_expression` string, required — The cron expression for this schedule.
          - `id` string, required — The unique identifier for this backup schedule.
          - `type` 'full' | 'incr', required — The type of backup to take on this schedule.
      - `cpus` string — The number of CPUs to allocate for the database and to use for tuning Postgres. Defaults to the number of available CPUs on the host. Can include an SI suffix, e.g. '500m' for 500 millicpus. Whether this limit is enforced depends on the orchestrator.
      - `database_name` string, required — The name of the Postgres database.
      - `database_users` DatabaseUserSpec[] — The users to create for this database.
        - `attributes` string[] — The attributes to assign to this database user.
        - `db_owner` boolean — If true, this user will be granted database ownership.
        - `password` string — The password for this database user. This field will be excluded from the response of all endpoints. It can also be omitted from update requests to keep the current value.
        - `roles` string[] — The roles to assign to this database user.
        - `username` string, required — The username for this database user.
      - `memory` string — The amount of memory in SI or IEC notation to allocate for the database and to use for tuning Postgres. Defaults to the total available memory on the host. Whether this limit is enforced depends on the orchestrator.
      - `nodes` DatabaseNodeSpec[], required — The Spock nodes for this database.
        - `backup_config` BackupConfigSpec
          - `repositories` BackupRepositorySpec[], required — The repositories for this backup configuration.
            - `azure_account` string — The Azure account name for this repository. Only applies when type = 'azure'.
            - `azure_container` string — The Azure container name for this repository. Only applies when type = 'azure'.
            - `azure_endpoint` string — The optional Azure endpoint for this repository. Only applies when type = 'azure'.
            - `azure_key` string — The Azure storage account access key to use for this repository. This field will be excluded from the response of all endpoints. It can also be omitted from update requests to keep the current value.
            - `base_path` string — The base path within the repository to store backups. Required for type = 'posix' and 'cifs'.
            - `custom_options` object — Additional options to apply to this repository.
            - `gcs_bucket` string — The GCS bucket name for this repository. Only applies when type = 'gcs'.
            - `gcs_endpoint` string — The optional GCS endpoint for this repository. Only applies when type = 'gcs'.
            - `gcs_key` string — Optional base64-encoded private key data. If omitted, pgbackrest will use the service account attached to the instance profile. This field will be excluded from the response of all endpoints. It can also be omitted from update requests to keep the current value.
            - `id` string — The unique identifier of this repository.
            - `retention_full` integer — The count of full backups to retain or the time to retain full backups.
            - `retention_full_type` 'time' | 'count' — The type of measure used for retention_full.
            - `s3_bucket` string — The S3 bucket name for this repository. Only applies when type = 's3'.
            - `s3_endpoint` string — The optional S3 endpoint for this repository. Only applies when type = 's3'.
            - `s3_key` string — An optional AWS access key ID to use for this repository. If not provided, pgbackrest will use the default credential provider chain. This field will be excluded from the response of all endpoints. It can also be omitted from update requests to keep the current value.
            - `s3_key_secret` string — The corresponding secret for the AWS access key ID in s3_key. This field will be excluded from the response of all endpoints. It can also be omitted from update requests to keep the current value.
            - `s3_region` string — The region of the S3 bucket for this repository. Only applies when type = 's3'.
            - `type` 's3' | 'gcs' | 'azure' | 'posix' | 'cifs', required — The type of this repository.
          - `schedules` BackupScheduleSpec[] — The schedules for this backup configuration.
            - `cron_expression` string, required — The cron expression for this schedule.
            - `id` string, required — The unique identifier for this backup schedule.
            - `type` 'full' | 'incr', required — The type of backup to take on this schedule.
        - `cpus` string — The number of CPUs to allocate for the database on this node and to use for tuning Postgres. It can include the SI suffix 'm', e.g. '500m' for 500 millicpus. Cannot allocate units smaller than 1m. Defaults to the number of available CPUs on the host if 0 or unspecified. Cannot allocate more CPUs than are available on the host. Whether this limit is enforced depends on the orchestrator.
        - `host_ids` string[], required — The IDs of the hosts that should run this node. When multiple hosts are specified, one host will chosen as a primary, and the others will be read replicas.
        - `memory` string — The amount of memory in SI or IEC notation to allocate for the database on this node and to use for tuning Postgres. Defaults to the total available memory on the host. Whether this limit is enforced depends on the orchestrator.
        - `name` string, required — The name of the database node.
        - `orchestrator_opts` OrchestratorOpts — Options specific to the selected orchestrator.
          - `swarm` SwarmOpts — Docker Swarm-specific options.
            - `extra_labels` object — Arbitrary labels to apply to the Docker Swarm service
            - `extra_networks` ExtraNetworkSpec[] — A list of additional Docker Swarm networks to attach containers in this database to.
              - …
            - `extra_volumes` ExtraVolumesSpec[] — A list of extra volumes to mount. Each entry defines a host and container path.
              - …
            - `image` string — User-specified container image override. Bypasses manifest version constraints entirely — the CP will deploy this image without validating it against the version manifest. The CP verifies the image exists in its registry before accepting the spec. Clearing this field causes the CP to fall back to the manifest-resolved image on the next reconcile.
        - `patroni_port` integer — The port used by Patroni for this node. Overrides the Patroni port set in the DatabaseSpec. NOTE: This field is not currently supported for Docker Swarm.
        - `pg_hba_conf` string[] — Additional pg_hba.conf entries for this particular node, one rule per array element. Prepended to the database-level pg_hba_conf entries, so node entries take first-match priority. Entries are inserted between control-plane's system-user rules and its catch-all, and cannot affect control-plane-internal connectivity.
        - `pg_ident_conf` string[] — Additional pg_ident.conf entries for this particular node, one mapping per array element. Prepended to the database-level pg_ident_conf entries.
        - `port` integer — The port used by the Postgres database for this node. Overrides the Postgres port set in the DatabaseSpec.
        - `postgres_version` string — The Postgres version for this node in 'major.minor' format. Overrides the Postgres version set in the DatabaseSpec.
        - `postgresql_conf` object — Additional postgresql.conf settings for this particular node. Will be merged with the settings provided by control-plane.
        - `restore_config` RestoreConfigSpec
          - `repository` RestoreRepositorySpec, required
            - `azure_account` string — The Azure account name for this repository. Only applies when type = 'azure'.
            - `azure_container` string — The Azure container name for this repository. Only applies when type = 'azure'.
            - `azure_endpoint` string — The optional Azure endpoint for this repository. Only applies when type = 'azure'.
            - `azure_key` string — An optional Azure storage account access key to use for this repository. If not provided, pgbackrest will use the VM's managed identity.
            - `base_path` string — The base path within the repository to store backups. Required for type = 'posix' and 'cifs'.
            - `custom_options` object — Additional options to apply to this repository.
            - `gcs_bucket` string — The GCS bucket name for this repository. Only applies when type = 'gcs'.
            - `gcs_endpoint` string — The optional GCS endpoint for this repository. Only applies when type = 'gcs'.
            - `gcs_key` string — Optional base64-encoded private key data. If omitted, pgbackrest will use the service account attached to the instance profile.
            - `id` string — The unique identifier of this repository.
            - `s3_bucket` string — The S3 bucket name for this repository. Only applies when type = 's3'.
            - `s3_endpoint` string — The optional S3 endpoint for this repository. Only applies when type = 's3'.
            - `s3_key` string — An optional AWS access key ID to use for this repository. If not provided, pgbackrest will use the default credential provider chain.
            - `s3_key_secret` string — The corresponding secret for the AWS access key ID in s3_key.
            - `s3_region` string — The region of the S3 bucket for this repository. Only applies when type = 's3'.
            - `type` 's3' | 'gcs' | 'azure' | 'posix' | 'cifs', required — The type of this repository.
          - `restore_options` object — Additional options to use when restoring this database. If omitted, the database will be restored to the latest point in the given repository.
          - `source_database_id` string, required — The ID of the database to restore this database from.
          - `source_database_name` string, required — The name of the database in this repository. The database will be renamed to the database_name in the DatabaseSpec after it's restored.
          - `source_node_name` string, required — The name of the node to restore this database from.
        - `source_node` string — The name of the source node to use for sync. This is typically the node (like 'n1') from which the data will be copied to initialize this new node.
      - `orchestrator_opts` OrchestratorOpts — Options specific to the selected orchestrator.
        - `swarm` SwarmOpts — Docker Swarm-specific options.
          - `extra_labels` object — Arbitrary labels to apply to the Docker Swarm service
          - `extra_networks` ExtraNetworkSpec[] — A list of additional Docker Swarm networks to attach containers in this database to.
            - `aliases` string[] — Optional network-scoped aliases for the container.
            - `driver_opts` object — Optional driver options for the network connection.
            - `id` string, required — The name or ID of the network to connect to.
          - `extra_volumes` ExtraVolumesSpec[] — A list of extra volumes to mount. Each entry defines a host and container path.
            - `destination_path` string, required — The path inside the container where the volume will be mounted.
            - `host_path` string, required — The host path for the volume.
          - `image` string — User-specified container image override. Bypasses manifest version constraints entirely — the CP will deploy this image without validating it against the version manifest. The CP verifies the image exists in its registry before accepting the spec. Clearing this field causes the CP to fall back to the manifest-resolved image on the next reconcile.
      - `patroni_port` integer — The port used by Patroni for this database. If the port is 0, each instance will be assigned a random port. NOTE: This field is not currently supported for Docker Swarm.
      - `pg_hba_conf` string[] — Additional pg_hba.conf entries, one rule per array element. Inserted between control-plane's system-user rules and its catch-all, so they cannot affect control-plane-internal connectivity (Patroni, replication, health checks). Node-level pg_hba_conf entries are prepended to these.
      - `pg_ident_conf` string[] — Additional pg_ident.conf entries, one mapping per array element. Purely additive; control-plane writes no pg_ident entries of its own. The primary use case is cert auth with map= translating certificate CNs to PostgreSQL usernames.
      - `port` integer — The port used by the Postgres database. If the port is 0, each instance will be assigned a random port. If the port is unspecified, the database will not be exposed on any port, dependent on orchestrator support for that feature.
      - `postgres_version` string — The Postgres version in 'major.minor' format.
      - `postgresql_conf` object — Additional postgresql.conf settings. Will be merged with the settings provided by control-plane.
      - `restore_config` RestoreConfigSpec
        - `repository` RestoreRepositorySpec, required
          - `azure_account` string — The Azure account name for this repository. Only applies when type = 'azure'.
          - `azure_container` string — The Azure container name for this repository. Only applies when type = 'azure'.
          - `azure_endpoint` string — The optional Azure endpoint for this repository. Only applies when type = 'azure'.
          - `azure_key` string — An optional Azure storage account access key to use for this repository. If not provided, pgbackrest will use the VM's managed identity.
          - `base_path` string — The base path within the repository to store backups. Required for type = 'posix' and 'cifs'.
          - `custom_options` object — Additional options to apply to this repository.
          - `gcs_bucket` string — The GCS bucket name for this repository. Only applies when type = 'gcs'.
          - `gcs_endpoint` string — The optional GCS endpoint for this repository. Only applies when type = 'gcs'.
          - `gcs_key` string — Optional base64-encoded private key data. If omitted, pgbackrest will use the service account attached to the instance profile.
          - `id` string — The unique identifier of this repository.
          - `s3_bucket` string — The S3 bucket name for this repository. Only applies when type = 's3'.
          - `s3_endpoint` string — The optional S3 endpoint for this repository. Only applies when type = 's3'.
          - `s3_key` string — An optional AWS access key ID to use for this repository. If not provided, pgbackrest will use the default credential provider chain.
          - `s3_key_secret` string — The corresponding secret for the AWS access key ID in s3_key.
          - `s3_region` string — The region of the S3 bucket for this repository. Only applies when type = 's3'.
          - `type` 's3' | 'gcs' | 'azure' | 'posix' | 'cifs', required — The type of this repository.
        - `restore_options` object — Additional options to use when restoring this database. If omitted, the database will be restored to the latest point in the given repository.
        - `source_database_id` string, required — The ID of the database to restore this database from.
        - `source_database_name` string, required — The name of the database in this repository. The database will be renamed to the database_name in the DatabaseSpec after it's restored.
        - `source_node_name` string, required — The name of the node to restore this database from.
      - `scripts` DatabaseScripts
        - `post_database_create` string[] — The `post_database_create` script runs once on each primary instance of each node after the application database is created for the first time. Each element of the array is a single SQL statement. These statements run within a transaction in the application database after Spock is initialized, but before subscriptions are created.
        - `post_init` string[] — The `post_init` script runs on each primary instance of each node after the instance is created for the first time. Each element of the array is single SQL statement. These statements run within a transaction in the `postgres` database before the users are created, so this feature can be used to create nologin roles that can be assigned to the database users via their `roles` field.
      - `services` ServiceSpec[] — Service instances to run alongside the database (e.g., MCP servers).
        - `config` object — Service-specific configuration. For MCP services, this includes llm_provider, llm_model, and provider-specific API keys.
        - `connect_as` string, required — Username of the database_users entry this service connects as. The user must exist in database_users and have appropriate roles for the service's needs.
        - `cpus` string — The number of CPUs to allocate for this service. It can include the SI suffix 'm', e.g. '500m' for 500 millicpus. Defaults to container defaults if unspecified.
        - `database_connection` DatabaseConnection — Controls how the service connects to the database. When omitted, all nodes are included with the local node first and target_session_attrs is derived from the service config.
          - `target_nodes` string[] — Optional ordered list of database node names. When set, the service's database connection includes only the listed nodes in the specified order.
          - `target_session_attrs` 'primary' | 'prefer-standby' | 'standby' | 'read-write' | 'any' — Optional libpq target_session_attrs value. When set, overrides the default derived from the service config. Valid values: primary, prefer-standby, standby, read-write, any.
        - `host_ids` string[], required — The IDs of the hosts that should run this service. One service instance will be created per host.
        - `memory` string — The amount of memory in SI or IEC notation to allocate for this service. Defaults to container defaults if unspecified.
        - `orchestrator_opts` OrchestratorOpts — Options specific to the selected orchestrator.
          - `swarm` SwarmOpts — Docker Swarm-specific options.
            - `extra_labels` object — Arbitrary labels to apply to the Docker Swarm service
            - `extra_networks` ExtraNetworkSpec[] — A list of additional Docker Swarm networks to attach containers in this database to.
              - …
            - `extra_volumes` ExtraVolumesSpec[] — A list of extra volumes to mount. Each entry defines a host and container path.
              - …
            - `image` string — User-specified container image override. Bypasses manifest version constraints entirely — the CP will deploy this image without validating it against the version manifest. The CP verifies the image exists in its registry before accepting the spec. Clearing this field causes the CP to fall back to the manifest-resolved image on the next reconcile.
        - `port` integer — The port to publish the service on the host. If 0, Docker assigns a random port. If unspecified, no port is published and the service is not accessible from outside the Docker network.
        - `service_id` string, required — The unique identifier for this service.
        - `service_type` 'mcp' | 'postgrest' | 'rag', required — The type of service to run.
        - `version` string, required — The version of the service (e.g., '1.0.0', '14.5') or the literal 'latest'.
      - `spock_version` string — The major version of the Spock extension.
    - `state` 'creating' | 'modifying' | 'available' | 'deleting' | 'degraded' | 'failed' | 'restoring' | 'unknown', required — Current state of the database.
    - `tenant_id` string — Unique identifier for the database's owner.
    - `updated_at` string, date-time, required — The time that the database was last updated.
  - `task` Task, required
    - `completed_at` string, date-time — The time when the task was completed.
    - `created_at` string, date-time, required — The time when the task was created.
    - `database_id` string — The database ID of the task.
    - `entity_id` string, required — The entity ID (database_id or host_id) that this task belongs to.
    - `error` string — The error message if the task failed.
    - `host_id` string — The ID of the host that the task is running on.
    - `instance_id` string — The ID of the instance that the task is operating on.
    - `node_name` string — The name of the node that the task is operating on.
    - `parent_id` string, uuid — The parent task ID of the task.
    - `scope` 'database' | 'host', required — The scope of the task (database or host).
    - `status` 'pending' | 'running' | 'completed' | 'canceled' | 'canceling' | 'failed' | 'unknown', required — The status of the task.
    - `task_id` string, uuid, required — The unique ID of the task.
    - `type` string, required — The type of the task.

## Other responses

- `400` — Bad Request response.
- `404` — Not Found response.
- `409` — Conflict response.
- `500` — Internal Server Error response.
- `default` — Unexpected error response

---

[API](https://skmtc.net/pgedge/apis/pgedge-control-plane-v1-api.md) · [All operations](https://skmtc.net/pgedge/apis/pgedge-control-plane-v1-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/pgedge/pgedge-control-plane-v1-api/versions/29a68546f34c/schema)