database

Create database

Creates a new Managed Database instance. New databases are started by default. An initial backup is created automatically on startup and the API will be fully functional only after this backup has been created. The creation might take a while. Note that different databases have different properties that can be passed on creation. For PostgreSQL and MySQL, select the plan with the plan_compute, plan_node_count, plan_storage_gib and plan_backups fields; the plan name field is deprecated for these engines.

post/1.3/database

Request

  • Base URL: https://api.upcloud.com
  • URL: https://api.upcloud.com/1.3/database
  • Auth: HTTP bearer

Request body

hostname_prefixstring required

Hostname prefix for the service nodes.

titlestring required

Human-readable title for the service.

type'mysql' | 'pg' | 'opensearch' | 'valkey' required

The type of service.

zonestring required

Zone where the service is created.

set_service_uuidstring uuid

Optional UUID to assign to the created service.

planstring

Deprecated: prefer the plan_* selection fields (plan_compute, plan_node_count, plan_storage_gib, plan_backups) for PostgreSQL and MySQL. The plan name remains supported, and required for engines without componentised plans. For componentised (rdb.*) plans the storage segment is the desired TOTAL storage per node: any total reachable from a catalog plan's included storage in the plan's storage steps (within its cap) is a valid plan name, e.g. rdb.standard.2x-2CPU-8GB-120GB-regular selects the 80GB catalog plan with a 40GB dynamic top-up.

plan_computestring

Plan selection: compute shape combining family, CPU and memory as one token, as listed in the plan catalog components. PostgreSQL and MySQL only.

plan_node_countinteger

Plan selection: number of nodes.

plan_storage_gibinteger

Plan selection: desired TOTAL storage per node in GiB. Resolution picks the plan whose included storage matches, or tops the closest plan up with dynamic additional storage within the allowed limits. Mutually exclusive with additional_disk_space_gib.

plan_backups'mini' | 'regular' | 'extended'

Plan selection: backup tier. PostgreSQL and MySQL tiered plans only.

additional_disk_space_gibinteger

Additional disk space in GiB. Legacy plans only: componentised (rdb.*) plans set storage as a total via plan_storage_gib or the plan name.

termination_protectionboolean

When enabled, the service cannot be deleted until termination protection is disabled.

Example request

{
  "hostname_prefix": "doc-api-unique-prefix",
  "plan": "1x1xCPU-2GB-25GB",
  "additional_disk_space_gib": 10,
  "title": "my-managed-database",
  "type": "mysql",
  "zone": "de-fra1",
  "maintenance": {
    "dow": "sunday",
    "time": "05:00:00"
  },
  "termination_protection": false,
  "properties": {
    "automatic_utility_network_ip_filter": true,
    "version": "8",
    "ip_filter": []
  },
  "networks": [
    {
      "name": "example-network-1",
      "type": "private",
      "family": "IPv4",
      "uuid": "03631160-d57a-4926-ad48-a2f828229dcb"
    },
    {
      "name": "example-network-2",
      "type": "private",
      "family": "IPv4",
      "uuid": "03631160-d57a-4926-ad48-a2f828229dcb"
    }
  ],
  "labels": [
    {
      "key": "env",
      "value": "staging"
    },
    {
      "key": "foo",
      "value": "bar"
    }
  ]
}

Response

Created

uuidstring uuid

The unique identifier for the service.

zonestring

The zone where the service is hosted.

namestring

The name of the service.

titlestring

The title of the service.

typestring

The type of the service.

planstring

The plan of the service. For componentised (rdb.*) plans this is the effective plan name: the storage segment shows the total storage per node the service is configured with, and the same name is accepted back on create, modify and clone.

additional_disk_space_gibinteger

The additional disk space allocated to the service in GiB. Always 0 for componentised (rdb.*) plans, where storage is expressed only as the total in the plan name and in plan_components.

statestring

The current state of the service.

state_errorobject

A map of errors related to the service state.

poweredboolean

Indicates whether the service is powered on.

termination_protectionboolean

Indicates whether termination protection is enabled for the service.

node_countinteger

The number of nodes in the service.

create_timestring date-time

The time when the service was created.

update_timestring date-time

The time when the service was last updated.

service_uristring uri

The URI for accessing the service.

service_uri_paramsobject

A map of connection parameters for the service.

metadataobject

A map of metadata key-value pairs for the service.

propertiesobject

A map of additional properties for the service.

Example response

{
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "zone": "fi-hel1",
  "name": "my-db",
  "title": "My Database Service",
  "type": "pg",
  "plan": "1x1xCPU-2GB-25GB",
  "plan_components": {
    "compute": {
      "family": "standard",
      "node_count": 2,
      "cpu": 4,
      "memory_gb": 8
    },
    "storage": {
      "included_gib": 100,
      "dynamic_storage_supported": true
    },
    "backups": {
      "name": "regular",
      "retention_days": 15
    }
  },
  "additional_disk_space_gib": 10,
  "state": "running",
  "state_error": {
    "init": "failed"
  },
  "powered": true,
  "node_count": 1,
  "create_time": "2023-10-01T12:00:00Z",
  "update_time": "2023-10-10T12:00:00Z",
  "service_uri": "postgres://upadmin:example-prefix-project@pg-2x2xcpu-4gb-50gb-de-fra1-example-prefix-project.db.upclouddatabases.com:11550/defaultdb?sslmode=require",
  "service_uri_params": {
    "dbname": "defaultdb",
    "host": "pg-2x2xcpu-4gb-50gb-de-fra1-example-prefix-project.db.upclouddatabases.com",
    "password": "example-prefix-project",
    "port": "11550",
    "ssl_mode": "require",
    "user": "upadmin"
  },
  "maintenance": {
    "dow": "Monday",
    "time": "02:00:00",
    "pending_updates": [
      {
        "deadline": "2022-01-21T12:21:00Z",
        "description": "description related to the update",
        "start_after": "2022-01-21T12:21:00Z",
        "start_at": "2022-10-21T12:21:00Z"
      }
    ]
  },
  "metadata": {
    "owner": "team-databases"
  },
  "properties": {
    "public_access": false
  },
  "networks": [
    {
      "uuid": "123e4567-e89b-12d3-a456-426614174000",
      "name": "example-private-network",
      "family": "IPv4",
      "type": "private",
      "create_time": "2025-08-01T10:40:04.140473Z",
      "update_time": "2025-08-01T10:40:04.140473Z"
    }
  ],
  "node_states": [
    {
      "name": "node-1",
      "role": "master",
      "state": "running",
      "progress_updates": [
        {
          "completed": false,
          "current": 45,
          "max": 100,
          "min": 0,
          "phase": "prepare",
          "unit": "bytes_uncompressed"
        }
      ]
    }
  ],
  "labels": [
    {
      "key": "environment",
      "value": "production"
    }
  ],
  "backups": [
    {
      "backup_name": "pg-backup-2024-01-01",
      "backup_time": "2024-01-01T12:00:00Z",
      "data_size": 36413440
    }
  ],
  "components": [
    {
      "component": "pg",
      "host": "pg-2x2xcpu-4gb-50gb-de-fra1-example-prefix-project.db.upclouddatabases.com",
      "port": 1150,
      "route": "dynamic",
      "usage": "replica",
      "ssl": true
    }
  ],
  "connection_pools": [
    {
      "connection_uri": "postgresql://user:password@hostname:5432/dbname",
      "database": "pg-db-1",
      "pool_mode": "session",
      "pool_name": "pool-2",
      "pool_size": 10,
      "username": "updamin"
    }
  ],
  "users": [
    {
      "username": "admin",
      "password": "my-password",
      "authentication": "caching_sha2_password",
      "type": "admin"
    }
  ],
  "databases": [
    {
      "name": "postgres",
      "lc_collate": "en_US.UTF-8",
      "lc_ctype": "en_US.UTF-8"
    }
  ],
  "acls": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "permission": "read-write",
      "topic": "sensors/temperature",
      "username": "user123"
    }
  ],
  "service_integrations": [
    {
      "uuid": "123e4567-e89b-12d3-a456-426614174000",
      "type": "rsyslog",
      "source_name": "my-database",
      "source_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "destination_name": "my-rsyslog-server",
      "destination_uuid": "123e4567-e89b-12d3-a456-426614174000",
      "state": "active",
      "state_error": [],
      "node_states": [
        {
          "name": "node-1",
          "status": "running",
          "errors": [
            "some error"
          ],
          "likely_error_cause": null
        }
      ],
      "properties": {
        "key1": "value1",
        "key2": 2,
        "key3": true
      }
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.