Managed Databases

A Managed Database is a database-as-a-service which lets customers use a database without the need to set up a server or the database software. The database configuration defines its high-availability, resources, database software version and security parameters.

The Managed Database API allows you to manage the database instances of supported well-known open source database software. Managed Databases are available in every UpCloud zone. The API requests and responses payload are in JSON format only.

Managed Database states

The service state indicates the current status.

State Description
running Service is running.
poweroff Service is stopped.
rebuilding Service is being created.
rebalancing Service is being upgraded or migrated.

Available databases

MySQL

MySQL is the world’s most popular enterprise-grade open-source relational database management system. Managed Databases utilise MySQL Community Edition which is supported by a huge and active community of open source developers.

PostgreSQL

PostgreSQL, also known as Postgres, is a free and open-source relational database management system emphasizing extensibility and SQL compliance.

Supported extensions

address_standardizer hstore pgrouting postgres_fdw fuzzystrmatch
address_standardizer_data_us intagg pgrowlocks promscale pg_trgm
aiven_extras intarray pgstattuple rum uuid-ossp
bloom isn plcoffee sslinfo postgis_topology postgis_sfcgal
btree_gin ltree plls tablefunc postgis_tiger_geocoder pg_stat_statements
btree_gist pg_buffercache plperl timescale_analytics earthdistance
chkpass pg_cron plpgsql timescaledb pgcrypto hll unit
citext pg_partman plv8 tsearch2 postgis_raster
cube pg_prometheus postgis tsm_system_rows pg_similarity
dblink pg_repack postgis_legacy unaccent dict_int

List Managed Database types

Returns a list of available database types. Contains available plans, zones, database versions supported and the configuration properties for each database.

Request

GET /1.3/database/service-types HTTP/1.1

Normal response

HTTP/1.1 200 OK
{
  "mysql": {
    "name": "mysql",
    "description": "MySQL - Relational Database Management System",
    "latest_available_version": "8.0.26",
    "service_plans": [
      {
        "backup_config": {
          "interval": 24,
          "max_count": 2,
          "recovery_mode": "pitr"
        },
        "node_count": 1,
        "zones": {
          "zone": [
            {
              "name": "es-mad1"
            },
            {
              "name": "pl-waw1"
            },
            {
              "name": "us-sjo1"
            }
            ... more zones ...
          ]
        },
        "plan": "1x1xCPU-2GB-25GB",
        "core_number": 1,
        "storage_size": 25600,
        "memory_amount": 2048
      }
      ... more plans ...
    ],
    "properties": {
      "admin_password": {
        "createOnly": true,
        "example": "z66o9QXqKM",
        "maxLength": 256,
        "minLength": 8,
        "pattern": "^[a-zA-Z0-9-_]+$",
        "title": "Custom password for admin user. Defaults to random string. This must be set only when a new service is being created.",
        "type": ["string", "null"],
        "user_error": "Must consist of alpha-numeric characters, underscores or dashes"
      },
      "admin_username": {
        "createOnly": true,
        "example": "upadmin",
        "maxLength": 64,
        "pattern": "^[_A-Za-z0-9][-._A-Za-z0-9]{0,63}$",
        "title": "Custom username for admin user. This must be set only when a new service is being created.",
        "type": ["string", "null"],
        "user_error": "Must consist of alpha-numeric characters, dots, underscores or dashes, may not start with dash or dot, max 64 characters"
      },
      "public_access": {
        "default": false,
        "title": "Public Access",
        "type": "boolean",
        "description": "Allow access to the service from the public Internet"
      },
      "sql_mode": {
        "example": "ANSI,TRADITIONAL",
        "maxLength": 1024,
        "pattern": "^[A-Z_]*(,[A-Z_]+)*$",
        "title": "sql_mode",
        "type": "string",
        "user_error": "Must be uppercase alphabetic characters, underscores and commas",
        "description": "Global SQL mode. Set to empty to use MySQL server defaults. When creating a new service and not setting this field UpCloud default SQL mode (strict, SQL standard compliant) will be assigned."
      },
      "sql_require_primary_key": {
        "example": true,
        "title": "sql_require_primary_key",
        "type": "boolean",
        "description": "Require primary key to be defined for new tables or old tables modified with ALTER TABLE and fail if missing. It is recommended to always have primary keys because various functionality may break if any large table is missing them."
      },
      "version": {
        "title": "MySQL major version",
        "type": ["string", "null"],
        "enum": ["8"]
      }
      ... more configurations properties ...
    }
  },
  "pg": {
    "name": "pg",
    "description": "PostgreSQL - Object-Relational Database Management System",
    "latest_available_version": "13.5",
    "service_plans": [
      {
        "backup_config": {
          "interval": 24,
          "max_count": 3,
          "recovery_mode": "pitr"
        },
        "node_count": 1,
        "zones": {
          "zone": [
            {
              "name": "au-syd1"
            },
            {
              "name": "de-fra1"
            },
            {
              "name": "fi-hel2"
            },
            {
              "name": "nl-ams1"
            }
            ... more zones ...
          ]
        },
        "plan": "1x1xCPU-2GB-25GB",
        "core_number": 1,
        "storage_size": 25600,
        "memory_amount": 2048
      }
      ... more plans ...
    ],
    "properties": {
      "admin_password": {
        "createOnly": true,
        "example": "z66o9QXqKM",
        "maxLength": 256,
        "minLength": 8,
        "pattern": "^[a-zA-Z0-9-_]+$",
        "title": "Custom password for admin user. Defaults to random string. This must be set only when a new service is being created.",
        "type": ["string", "null"],
        "user_error": "Must consist of alpha-numeric characters, underscores or dashes"
      },
      "admin_username": {
        "createOnly": true,
        "example": "upadmin",
        "maxLength": 64,
        "pattern": "^[_A-Za-z0-9][-._A-Za-z0-9]{0,63}$",
        "title": "Custom username for admin user. This must be set only when a new service is being created.",
        "type": ["string", "null"],
        "user_error": "Must consist of alpha-numeric characters, dots, underscores or dashes, may not start with dash or dot, max 64 characters"
      },
      "automatic_utility_network_ip_filter": {
        "default": true,
        "title": "Automatic utility network IP Filter",
        "type": "boolean",
        "description": "Automatically allow connections from servers in the utility network within the same zone"
      },
      "public_access": {
        "default": false,
        "title": "Public Access",
        "type": "boolean",
        "description": "Allow access to the service from the public Internet"
      },
      "track_functions": {
        "title": "track_functions",
        "type": "string",
        "description": "Enables tracking of function call counts and time used.",
        "enum": ["all", "pl", "none"]
      },
      "version": {
        "title": "PostgreSQL major version",
        "type": ["string", "null"],
        "enum": ["12", "13"]
      },
      "work_mem": {
        "example": 4,
        "title": "work_mem",
        "type": "integer",
        "description": "Sets the maximum amount of memory to be used by a query operation (such as a sort or hash table) before writing to temporary disk files, in MB. Default is 1MB + 0.075% of total RAM (up to 32MB).",
        "minimum": 1,
        "maximum": 1024
      }
      ... more configurations properties ...
    }
  }
}

Get Managed Database type details

Returns database type details by given {database_type}. Contains available plans, zones, database versions supported and configuration properties.

Request

GET /1.3/database/service-types/{database_type} HTTP/1.1

Normal response

HTTP/1.1 200 OK
{
  "mysql": {
    "name": "mysql",
    "description": "MySQL - Relational Database Management System",
    "latest_available_version": "8.0.26",
    "service_plans": [
      {
        "backup_config": {
          "interval": 24,
          "max_count": 2,
          "recovery_mode": "pitr"
        },
        "node_count": 1,
        "zones": {
          "zone": [
            {
              "name": "es-mad1"
            },
            {
              "name": "pl-waw1"
            },
            {
              "name": "us-sjo1"
            }
            ... more zones ...
          ]
        },
        "plan": "1x1xCPU-2GB-25GB",
        "core_number": 1,
        "storage_size": 25600,
        "memory_amount": 2048
      }
      ... more plans ...
    ],
    "properties": {
      "admin_password": {
        "createOnly": true,
        "example": "z66o9QXqKM",
        "maxLength": 256,
        "minLength": 8,
        "pattern": "^[a-zA-Z0-9-_]+$",
        "title": "Custom password for admin user. Defaults to random string. This must be set only when a new service is being created.",
        "type": ["string", "null"],
        "user_error": "Must consist of alpha-numeric characters, underscores or dashes"
      },
      "admin_username": {
        "createOnly": true,
        "example": "upadmin",
        "maxLength": 64,
        "pattern": "^[_A-Za-z0-9][-._A-Za-z0-9]{0,63}$",
        "title": "Custom username for admin user. This must be set only when a new service is being created.",
        "type": ["string", "null"],
        "user_error": "Must consist of alpha-numeric characters, dots, underscores or dashes, may not start with dash or dot, max 64 characters"
      },
      "public_access": {
        "default": false,
        "title": "Public Access",
        "type": "boolean",
        "description": "Allow access to the service from the public Internet"
      },
      "sql_mode": {
        "example": "ANSI,TRADITIONAL",
        "maxLength": 1024,
        "pattern": "^[A-Z_]*(,[A-Z_]+)*$",
        "title": "sql_mode",
        "type": "string",
        "user_error": "Must be uppercase alphabetic characters, underscores and commas",
        "description": "Global SQL mode. Set to empty to use MySQL server defaults. When creating a new service and not setting this field UpCloud default SQL mode (strict, SQL standard compliant) will be assigned."
      },
      "sql_require_primary_key": {
        "example": true,
        "title": "sql_require_primary_key",
        "type": "boolean",
        "description": "Require primary key to be defined for new tables or old tables modified with ALTER TABLE and fail if missing. It is recommended to always have primary keys because various functionality may break if any large table is missing them."
      },
      "version": {
        "title": "MySQL major version",
        "type": ["string", "null"],
        "enum": ["8"]
      }
      ... more configurations properties ...
    }
  }
}

Get Managed Databases certificate authority (CA)

Returns the CA certificate. Every customer main account has a private Certificate Authority (CA) that signs certificates for internal use. Managed Database service types, such as PostgreSQL, use it for external connections. To access these services, you must download and configure the certificate on your browser or client.

Request

GET /1.3/database/certificate HTTP/1.1

Normal response

HTTP/1.1 200 OK
{
  "certificate": "-----BEGIN CERTIFICATE-----\naxxxxxxxxxxxxx+tkP9Uh9+PxxxxxcNAQEM\nBQAwOjE4MDYGA1UEAwwvZWYzMTc1xxxxxxxxxx0YjM2OWIz\nM2RkIFByb2plY3QgQ0EwHhcNMjEwMzMwMDgxNDU0WhcNMzEwMzI4MDgxNDU0WjA6\nMTgwNgYDVQQDDC9lZjMxNzU1NC1lNzYzLTQ5ZjUtODI4Ni1lZDRiMzY5YjMzZGQg\nUHJvamVjdCBDQTCCAaIwDQYJKoZIhvcNAQEBBQxxxxggGBAK1Vh4GR\nlfxPZ3Icw8E1WlS5+9rADOdrstYtL3oiHBqzljmjvKf1Vuu0LLHtszWrCElOvoZ4\nzhg6+yVIB9YcvTZJNU0BNlIilF0rafn/40pFjeKrtxxxxxxxxxxy48Hnk\nMAiqoRyJ6hGRpYmKVip2sbMEtI+X9xQahlhlTMLo9082gS2hI5nvmhDqRiOlly28\ntwr2I/nbsIao8pIE19bdptKVqrv9x+O51O2JK7NlyjxnJVaHS9Tv6z1gG0GZgzYW\nkram1U8oTu72cjvGhMIBhgz7AlQ74PMtAub/eH4hipGU4LDZQiZ+9kCT+FCD9uAq\nIq+ALiLPHTCaGiKTJYoerutgrmrz1HZp6RmxRc8Wk7MdPp8OHqSXUnewKSGlzEl3\nhlJ5UMOVQ+tSDffAuvA6phUS0mmm1xxxxxxxxxxxxxxxMcrVE8AjbF5nkieOV0r6hIwIDAQAB\noz8wPTAdBgNVHQ4EFxxxxgQUHTUNeVDpSFx8fjq9xxxxxxxxFDnqn8xY0iAwDwYDVR0TBAgwBgEB\n/wIBADALBgNxxxxxxxxxxLtt8qOjsbvS\nYZtePpqZjx7NkmFdScc0LOBj6oXFetcJlhLQKzrguQDi/trt29sxjZZ5zLnQufnE\ns8IYtbclhDbF0qGG15oP8tYVRXfzKLHF4HfuMrdiyqzF/q6Qy0fVIiFWD7t1it8V\nPLqlk9oFDL7xUnsZOfYcqv8Ct+aWE7L73gJVgUkDHP+gkdGTWKYm4zzYTLfqh1Iu\nyivOjn+KSyjjtsJsOGUDZBkh215OMKPp4JpWQpgQeK6kjTnwuMwEYYFyhfu/z5wU\nwN7z7Ad39fyGmQzkGbFXtP0te4MFElOVSkiHaB4T4lTM6690st6+uIhFI1Qo/oAY\n30ybOpOTLF7FZxwY5Z+BTW27hytyECLkG3b4iKIqKsRIvlFkwKP8cfKjq7ImSbBG\nOJ8JBcraffygrLznbJ2979Y9yN+n+8wW0xxxxxxxxxxov24snxDmm6fAMoO1\nxBM7c2KZA5ZoZDefcz9e28r7xxxx==\n-----END CERTIFICATE-----\n"
}

List Managed Databases

Returns a list of all available Managed Database services. Depending on their database type, Managed Databases services will have different details.

Request

GET /1.3/database HTTP/1.1

Normal response

HTTP/1.1 200 OK
[
  {
    "backups": [
      {
        "backup_time": "2022-01-06T12:36:06.739000Z",
        "data_size": 36464640
      },
      {
        "backup_time": "2022-01-07T12:36:06.261000Z",
        "data_size": 36413440
      }
      ... more backups based on your plan ...
    ],
    "components": [
      {
        "component": "pg",
        "host": "pg-2x2xcpu-4gb-50gb-de-fra1-example-prefix-project.db.upclouddatabases.com",
        "port": 11550,
        "route": "dynamic",
        "usage": "primary"
      },
      {
        "component": "pg",
        "host": "replica-pg-2x2xcpu-4gb-50gb-de-fra1-example-prefix-project.db.upclouddatabases.com",
        "port": 11550,
        "route": "dynamic",
        "usage": "replica"
      },
      {
        "component": "pg",
        "host": "public-pg-2x2xcpu-4gb-50gb-de-fra1-example-prefix-project.db.upclouddatabases.com",
        "port": 11550,
        "route": "public",
        "usage": "primary"
      },
      {
        "component": "pg",
        "host": "public-replica-pg-2x2xcpu-4gb-50gb-de-fra1-example-prefix-project.db.upclouddatabases.com",
        "port": 11550,
        "route": "public",
        "usage": "replica"
      },
      {
        "component": "pgbouncer",
        "host": "pg-2x2xcpu-4gb-50gb-de-fra1-example-prefix-project.db.upclouddatabases.com",
        "port": 11551,
        "route": "dynamic",
        "usage": "primary"
      },
      {
        "component": "pgbouncer",
        "host": "replica-pg-2x2xcpu-4gb-50gb-de-fra1-example-prefix-project.db.upclouddatabases.com",
        "port": 11551,
        "route": "dynamic",
        "usage": "replica"
      },
      {
        "component": "pgbouncer",
        "host": "public-pg-2x2xcpu-4gb-50gb-de-fra1-example-prefix-project.db.upclouddatabases.com",
        "port": 11551,
        "route": "public",
        "usage": "primary"
      },
      {
        "component": "pgbouncer",
        "host": "public-replica-pg-2x2xcpu-4gb-50gb-de-fra1-example-prefix-project.db.upclouddatabases.com",
        "port": 11551,
        "route": "public",
        "usage": "replica"
      }
    ],
    "connection_pools": [
      {
        "connection_uri": "postgres://upadmin:[email protected]x-project.db.upclouddatabases.com:11551/pool-1?sslmode=require",
        "database": "defaultdb",
        "pool_mode": "session",
        "pool_name": "pool-1",
        "pool_size": 50,
        "username": "upadmin"
      }
    ],
    "create_time": "2022-01-04T09:36:14Z",
    "maintenance": {
      "dow": "sunday",
      "time": "05:00:00"
    },
    "name": "pg-2x2xcpu-4gb-50gb-de-fra1",
    "node_count": 2,
    "node_states": [
      {
        "name": "pg-2x2xcpu-4gb-50gb-de-fra1-1",
        "role": "master",
        "state": "running"
      },
      {
        "name": "pg-2x2xcpu-4gb-50gb-de-fra1-2",
        "role": "standby",
        "state": "running"
      }
    ],
    "plan": "2x2xCPU-4GB-50GB",
    "powered": true,
    "properties": {
      "automatic_utility_network_ip_filter": false,
      "ip_filter": ["0.0.0.0/0"],
      "public_access": true,
      "version": "13"
    },
    "uuid": "09d9d824-8b3e-4a57-a9b3-77ec51fd5c84",
    "state": "running",
    "title": "pg-2x2xcpu-4gb-50gb-de-fra1",
    "type": "pg",
    "update_time": "2022-01-04T09:36:24Z",
    "service_uri": "postgres://upadmin:[email protected]x-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"
    },
    "users": [
      {
        "username": "upadmin",
        "type": "primary"
      }
    ],
    "zone": "de-fra1"
  }
]

Get Managed Database details

Returns details of a Managed Database service by its {uuid}.

Request

GET /1.3/database/{uuid} HTTP/1.1

Normal response

HTTP/1.1 200 OK
{
  "backups": [
   {
    "backup_time": "2022-01-06T12:36:06.739000Z",
    "data_size": 36464640
   },
   {
    "backup_time": "2022-01-07T12:36:06.261000Z",
    "data_size": 36413440
   }
   ... more backups based on your plan ...
  ],
  "components": [
   {
    "component": "pg",
    "host": "pg-2x2xcpu-4gb-50gb-de-fra1-example-prefix-project.db.upclouddatabases.com",
    "port": 11550,
    "route": "dynamic",
    "usage": "primary"
   },
   {
    "component": "pg",
    "host": "replica-pg-2x2xcpu-4gb-50gb-de-fra1-example-prefix-project.db.upclouddatabases.com",
    "port": 11550,
    "route": "dynamic",
    "usage": "replica"
   },
   {
    "component": "pg",
    "host": "public-pg-2x2xcpu-4gb-50gb-de-fra1-example-prefix-project.db.upclouddatabases.com",
    "port": 11550,
    "route": "public",
    "usage": "primary"
   },
   {
    "component": "pg",
    "host": "public-replica-pg-2x2xcpu-4gb-50gb-de-fra1-example-prefix-project.db.upclouddatabases.com",
    "port": 11550,
    "route": "public",
    "usage": "replica"
   },
   {
    "component": "pgbouncer",
    "host": "pg-2x2xcpu-4gb-50gb-de-fra1-example-prefix-project.db.upclouddatabases.com",
    "port": 11551,
    "route": "dynamic",
    "usage": "primary"
   },
   {
    "component": "pgbouncer",
    "host": "replica-pg-2x2xcpu-4gb-50gb-de-fra1-example-prefix-project.db.upclouddatabases.com",
    "port": 11551,
    "route": "dynamic",
    "usage": "replica"
   },
   {
    "component": "pgbouncer",
    "host": "public-pg-2x2xcpu-4gb-50gb-de-fra1-example-prefix-project.db.upclouddatabases.com",
    "port": 11551,
    "route": "public",
    "usage": "primary"
   },
   {
    "component": "pgbouncer",
    "host": "public-replica-pg-2x2xcpu-4gb-50gb-de-fra1-example-prefix-project.db.upclouddatabases.com",
    "port": 11551,
    "route": "public",
    "usage": "replica"
   }
  ],
  "connection_pools": [
   {
    "connection_uri": "postgres://upadmin:[email protected]x-project.db.upclouddatabases.com:11551/pool-1?sslmode=require",
    "database": "defaultdb",
    "pool_mode": "session",
    "pool_name": "pool-1",
    "pool_size": 50,
    "username": "upadmin"
   }
  ],
  "create_time": "2022-01-04T09:36:14Z",
  "maintenance": {
   "dow": "sunday",
   "time": "05:00:00"
  },
  "name": "pg-2x2xcpu-4gb-50gb-de-fra1",
  "node_count": 2,
  "node_states": [
   {
    "name": "pg-2x2xcpu-4gb-50gb-de-fra1-1",
    "role": "master",
    "state": "running"
   },
   {
    "name": "pg-2x2xcpu-4gb-50gb-de-fra1-2",
    "role": "standby",
    "state": "running"
   }
  ],
  "plan": "2x2xCPU-4GB-50GB",
  "powered": true,
  "properties": {
   "automatic_utility_network_ip_filter": false,
   "ip_filter": [
    "0.0.0.0/0"
   ],
   "public_access": true,
   "version": "13"
  },
  "uuid": "09d9d824-8b3e-4a57-a9b3-77ec51fd5c84",
  "state": "running",
  "title": "pg-2x2xcpu-4gb-50gb-de-fra1",
  "type": "pg",
  "update_time": "2022-01-04T09:36:24Z",
  "service_uri": "postgres://upadmin:[email protected]x-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"
  },
  "users": [
   {
    "username": "upadmin",
    "type": "primary"
   }
  ],
  "zone": "de-fra1"
}

Get Managed Database versions

Returns available versions of the Managed Database service by its {uuid}.

Request

GET /1.3/database/{uuid}/versions HTTP/1.1

Normal response

HTTP/1.1 200 OK
["10", "11", "12", "13", "14"]

Create Managed 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.

Request

POST /1.3/database HTTP/1.1
{
  "hostname_prefix": "doc-api-unique-prefix",
  "plan": "1x1xCPU-2GB-25GB",
  "title": "my-managed-database",
  "type": "mysql",
  "zone": "de-fra1",
  "maintenance": {
    "dow": "sunday",
    "time": "05:00:00"
  },
  "properties": {
    "automatic_utility_network_ip_filter": true,
    "version": "8",
    "ip_filter": []
    ... more database type-specific configuration properties ...
  }
}

Attributes

Attribute Accepted value Required Description
hostname_prefix 3-30 characters yes Managed Database service unique prefix.
title 3-256 characters yes Managed Database service name.
plan A valid plan identifier yes Plan which the service will have, see service_plans in Managed Database type details.
zone A valid zone identifier yes Zone in which the service will be hosted, e.g. fi-hel1.
type mysql / pg yes Database type for the Managed Database service.
maintenance.dow Full name of weekday in English, lower case ("sunday") no Service automatic maintenance day of the week. Set randomly if not provided.
maintenance.time Time in UTC of automatic maintenance HH:MM:SS no Service automatic maintenance time. Set randomly if not provided.
properties database type-specific 'createOnly' properties yes Service type-specific 'createOnly' configurations, see properties in Managed Database type details.

Normal response

HTTP/1.1 200 OK

Error responses

HTTP status Error code Description
409 Conflict SERVICE_EXISTS A service with the supplied {hostname_prefix} already exists.
400 Bad Request VALIDATION_ERROR Must provide a {zone}, {plan}, {type} and {hostname_prefix}.
400 Bad Request VALIDATION_ERROR Service {hostname_prefix} is too short, min length is 3 character.
400 Bad Request VALIDATION_ERROR Service {hostname_prefix} is too long, max length is 30 character.
400 Bad Request VALIDATION_ERROR Unrecognized service {type} / {plan} / {zone}.
400 Bad Request SERVICE_ERROR Invalid {property} : Invalid input for {property_key} : {property_value} is not {expected_value}.

Modify Managed Database

Modifies Managed Database service details by its {uuid} including upgrading plans, migration to other zones and database type-specific configurations.

Request

PATCH /1.3/database HTTP/1.1
{
  "title": "my-managed-database",
  "powered": true,
  "plan": "1x1xCPU-2GB-25GB",
  "zone": "de-fra1",
  "maintenance": {
    "dow": "sunday",
    "time": "12:00:00"
  },
  "properties": {
    "automatic_utility_network_ip_filter": true,
    "version": "8",
    "ip_filter": []
    ... more properties ...
  }
}

Attributes

Attribute Accepted value Required Description
title 3-256 characters no Managed Database service name.
powered true / false no Power on/off the Managed Database service.
plan A valid plan identifier no Plan to which the service will be upgraded, see service_plans in Managed Database type details.
zone A valid zone identifier no Zone to which the service will be migrated, e.g. fi-hel1.
maintenance.dow Full name of weekday in English, lower case ("sunday") no Service automatic maintenance day of the week.
maintenance.time Time in UTC of automatic maintenance HH:MM:SS no Service automatic maintenance time.
properties database type-specific properties no Service type-specific configurations, see properties in Managed Database type details.

Error responses

HTTP status Error code Description
409 Conflict SERVICE_EXISTS A service with the supplied {hostname_prefix} already exists.
400 Bad Request VALIDATION_ERROR Must provide a {zone}, {plan}, {type} and {hostname_prefix}.
400 Bad Request VALIDATION_ERROR Service {hostname_prefix} is too short, min length is 3 character.
400 Bad Request VALIDATION_ERROR Service {hostname_prefix} is too long, max length is 30 character.
400 Bad Request VALIDATION_ERROR Unrecognized service {type} / {plan} / {zone}.
400 Bad Request SERVICE_ERROR Invalid {property} : Invalid input for {property_key} : {property_value} is not {expected_value}.

Delete Managed Database

Deletes a specified Managed Database. All data will be erased and lost, including backups. If the service is not powered off, it will be powered off before deletion.

The state of the service can be anything.

Request

DELETE /1.3/database/{uuid} HTTP/1.1

Normal response

HTTP/1.1 204 No Content

Error responses

HTTP status Error code Description
404 Not Found SERVICE_NOT_FOUND Service not found.

Upgrade Managed Database (PostgreSQL)

Upgrades your PostgreSQL Managed Database service database to a newer major version. Downgrades are not permitted.

Request

POST /1.3/database/{uuid}/upgrade HTTP/1.1
{
  "target_version": "version_number"
}

Attributes

Attribute Accepted value Required Description
target_version version number as a string yes Targeted major version number for the upgrade. Check available versions from Get Managed Database versions.

Normal response

HTTP/1.1 200 OK

Error responses

HTTP status Error code Description
400 Bad Request SERVICE_ERROR PostgreSQL major version downgrade is not possible.

Clone Managed Database

Creates a clone of a Managed Database service based on its {uuid}. It is possible to change location, plans and use the point in time feature to clone your service at a specific time using your backups.

Request

POST /1.3/database/{uuid}/clone HTTP/1.1
{
  "title": "new-title",
  "hostname_prefix": "new-hostname-prefix",
  "clone_time": "2022-01-21T12:21:00Z",
  "plan": "1x1xCPU-2GB-25GB",
  "zone": "fi-hel1",
  "maintenance": {
    "dow": "sunday",
    "time": "12:00:00"
  },
  "properties": {
    "automatic_utility_network_ip_filter": false,
    "version": "13",
    "public_access": true,
    "ip_filter": ["0.0.0.0/0"]
  }
}

Attributes

Attribute Accepted value Default value Required Description
title 3-256 characters yes New title for the cloned service.
hostname_prefix 3-30 characters yes New unique hostname prefix for cloned service.
clone_time timestamp in RFC 3339 format (UTC) ( "2006-01-02T15:04:05Z" ) Latest point in time no Create a clone of your database service data from your backups at the selected point in time.
plan A valid plan identifier Inherited from the cloned service no Change the plan which the cloned service will have, see service_plans in Managed Database type details.
zone A valid zone identifier Inherited from the cloned service no Change the zone in which the cloned service will be hosted, e.g. fi-hel2.
maintenance.dow Full name of weekday in English, lower case ("sunday") Inherited from the cloned service no Service automatic maintenance day of the week.
maintenance.time Time in UTC of automatic maintenance HH:MM:SS Inherited from the cloned service no Service automatic maintenance time.
properties database type-specific 'createOnly' properties Inherited from the cloned service no Service type-specific 'createOnly' configurations, see properties in Managed Database type details.

Normal response

HTTP/1.1 200 OK

Error responses

HTTP status Error code Description
409 Conflict SERVICE_EXISTS A service with the supplied {hostname_prefix} already exists.
400 Bad Request VALIDATION_ERROR Must provide a {zone}, {plan}, {type} and {hostname_prefix}.
400 Bad Request VALIDATION_ERROR Service {hostname_prefix} is too short, min length is 3 character.
400 Bad Request VALIDATION_ERROR Service {hostname_prefix} is too long, max length is 30 character.
400 Bad Request VALIDATION_ERROR Unrecognized service {type} / {plan} / {zone}.
400 Bad Request SERVICE_ERROR Invalid {property} : Invalid input for {property_key} : {property_value} is not {expected_value}.
400 Bad Request SERVICE_ERROR {clone_time} is beyond the range of oldest available backup available
400 Bad Request INVALID_REQUEST Invalid {clone_time} Could not decode posted data.

List logs

Returns Managed Database service system-level logs by its {uuid} and optional query parameters {limit}, {offset} and {order}.

Request

GET /1.3/database/{uuid}/logs?limit={limit}&offset={offset}&order={order} HTTP/1.1

Query parameters

Attribute Accepted value Default value Required Description
limit 1-500 100 no Number of entries to receive at most.
offset 1-128 characters no Opaque offset identifier.
order desc / asc desc no Sort order for the logs.

Normal response

HTTP/1.1 200 OK
{
  "first_log_offset": "1642770443687",
  "offset": "1642770443687",
  "logs": [
    {
      "hostname": "api-doc-hostname",
      "msg": "[10-1] pid=3328089,user=postgres,db=defaultdb,app=[unknown],client=[local] LOG:  connection authorized: user=postgres database=defaultdb",
      "time": "2022-01-21T13:07:23.687241Z",
      "service": "postgresql-13.service"
    },
    {
      "hostname": "pg-2x2xcpu-4gb-50gb-de-fra1-2",
      "msg": "[9-1] pid=3328089,user=[unknown],db=[unknown],app=[unknown],client=[local] LOG:  connection received: host=[local]",
      "time": "2022-01-21T13:07:23.685916Z",
      "service": "postgresql-13.service"
    }
  ]
}

List connections

Returns a list of current connection details for your Managed Database service by its {uuid} and optional query parameters {limit}, {offset} and {order}.

Request

GET /1.3/database/{uuid}/connections?limit={limit}&offset={offset}&order={order} HTTP/1.1

Query parameters

Attribute Accepted value Default value Required Description
limit 1-5000 10 no Number of entries to receive at most.
offset >= 0 no Offset for retrieved results based on sort order.
order Connection content variable and sorting order combined with a colon ( "pid:desc" ) query_duration:desc no Order by Connection content variable and sort retrieved results. Limited variables can be used for ordering.

Connection content description

Contains information about the returned connection variables. Some variables are specific to a certain service type and will return empty or null values.

Variable Description
application_name Name of the application that is connected to this service.
backend_start Time when this process was started, i.e., when the client connected to the server.
backend_type Type of current service.
backend_xid Top-level transaction identifier of this service, if any.
backend_xmin The current service's xmin horizon.
client_addr IP address of the client connected to this service. If this field is null, it indicates either that the client is connected via a Unix socket on the server machine or that this is an internal process such as autovacuum.
client_hostname Host name of the connected client, as reported by a reverse DNS lookup of client_addr .
client_port TCP port number that the client is using for communication with this service, or -1 if a Unix socket is used.
datid OID of the database this service is connected to.
datname Name of the database this service is connected to.
pid Process ID of this service.
query Text of this service's most recent query. If state is active this field shows the currently executing query. In all other states, PostgreSQL shows the last query that was executed and MySQL show empty string.
query_duration The active query current duration.
query_start Time when the currently active query was started, or if state is not active, when the last query was started.
state Current overall state of this service: active: The service is executing a query, idle: The service is waiting for a new client command.
state_change Time when the state was last changed.
usename Name of the user logged into this service.
usesysid OID of the user logged into this service.
wait_event Wait event name if service is currently waiting.
wait_event_type The type of event for which the service is waiting, if any; otherwise NULL.
xact_start Time when this process' current transaction was started, or null if no transaction is active.

Normal response

HTTP/1.1 200 OK
[
  {
    "application_name": "client 1.5.14",
    "backend_start": "2022-01-21T13:26:26.682858Z",
    "backend_type": "client backend",
    "backend_xid": null,
    "backend_xmin": null,
    "client_addr": "84.249.198.8",
    "client_hostname": null,
    "client_port": 61264,
    "datid": 16401,
    "datname": "defaultdb",
    "pid": 2065031,
    "query": "SELECT \trel.relname, \trel.relkind, \trel.reltuples, \tcoalesce(rel.relpages,0) + coalesce(toast.relpages,0) AS num_total_pages, \tSUM(ind.relpages) AS index_pages, \tpg_roles.rolname AS owner FROM pg_class rel \tleft join pg_class toast on (toast.oid = rel.reltoastrelid) \tleft join pg_index on (indrelid=rel.oid) \tleft join pg_class ind on (ind.oid = indexrelid) \tjoin pg_namespace on (rel.relnamespace =pg_namespace.oid ) \tleft join pg_roles on ( rel.relowner = pg_roles.oid ) WHERE rel.relkind IN ('r','v','m','f','p') AND nspname = 'public'GROUP BY rel.relname, rel.relkind, rel.reltuples, coalesce(rel.relpages,0) + coalesce(toast.relpages,0), pg_roles.rolname;\n",
    "query_duration": 12225858000,
    "query_start": "2022-01-21T13:26:28.63132Z",
    "state": "idle",
    "state_change": "2022-01-21T13:26:28.63388Z",
    "usename": "upadmin",
    "usesysid": 16400,
    "wait_event": "ClientRead",
    "wait_event_type": "Client",
    "xact_start": null
  }
]

Terminate connection

Terminates a connection or kills a running query for a Managed Database service by its {uuid}, connection {pid} and optional query parameter {terminate}.

Request

DELETE /1.3/database/{uuid}/connections/{pid}?terminate={terminate} HTTP/1.1

Query parameters

Attribute Accepted value Required Description
terminate true / false no Request immediate termination instead of soft cancel.

Normal response

HTTP/1.1 200 OK
{
  "success": true
}

List query statistics

Returns a list of query statistics for the Managed Database service by its {uuid} and optional query parameters {limit}, {offset} and {order}. Query statistics will differ depending on the database type.

Request

GET /1.3/database/{uuid}/query-statistics?limit={limit}&offset={offset}&order={order} HTTP/1.1

Query parameters

Attribute Accepted value Default value Required Description
limit 1-5000 10 no Number of entries to receive at most.
offset >= 0 no Offset for retrieved results based on sort order.
order Query stats content variable and sorting order combined with a colon ( "avg_timer_wait:desc" ) PostgreSQL: calls:desc, MySQL: count_star:desc no Order by Query stats content variable and sort retrieved results.

Query statistics content description

Contains information about the returned query statistics variables. Each Managed Database type has its own statistics that may vary depending on the version.

MySQL

Variable description
avg_timer_wait The average wait time of the summarized timed events, in nanoseconds.
count_star The number of summarized events. This value includes all events, whether timed or nontimed.
digest The statement digest MD5 value as a string of 32 hexadecimal characters, or NULL if the statements_digest consumer is no. For more information about statement digesting.
digest_text The text of the normalized statement digest.
first_seen Timestamps indicating when statements with the given digest value were first seen.
last_seen Timestamps indicating when statements with the given digest value most recently seen.
max_timer_wait The maximum wait time of the summarized timed events, in nanoseconds.
min_timer_wait The minimum wait time of the summarized timed events, in nanoseconds.
quantile_95 The 95th percentile of the statement latency. This percentile is a high estimate, computed from the histogram data collected, in nanoseconds.
quantile_99 Similar to quantile_95 , but for the 99th percentile, in nanoseconds.
quantile_999 Similar to quantile_95 , but for the 99.9th percentile, in nanoseconds.
query_sample_seen A timestamp indicating when the statement in the query_sample_text variable was seen.
query_sample_text A sample SQL statement that produces the digest value in the row. This variable enables applications to access, for a given digest value, a statement actually seen by the server that produces that digest.
query_sample_timer_wait The wait time for the sample statement in the query_sample_text variable, in nanoseconds.
schema_name The name of the schema.
sum_created_tmp_disk_tables The sum of internal on-disk temporary tables created by the server while executing statements.
sum_created_tmp_tables The sum of internal temporary tables created by the server while executing statements.
sum_errors The sum of the errors occurred for the statement.
sum_lock_time The sum of time spent waiting for table locks, in nanoseconds.
sum_no_good_index_used The sum of no good index to use for the statement.
sum_no_index_used The sum of statement performing a table scan without using an index.
sum_rows_affected The sum of rows affected by the statement.
sum_rows_examined The sum of rows examined by the server layer (not counting any processing internal to storage engines).
sum_rows_sent The sum of rows returned by the statement.
sum_select_full_join The sum of joins that perform table scans because they do not use indexes. If this value is not 0, you should carefully check the indexes of your tables.
sum_select_full_range_join The sum of joins that used a range search on a reference table.
sum_select_range The sum of joins that used ranges on the first table. This is normally not a critical issue even if the value is quite large.
sum_select_range_check The sum of joins without keys that check for key usage after each row. If this is not 0, you should carefully check the indexes of your tables.
sum_select_scan The sum of joins that did a full scan of the first table.
sum_sort_merge_passes The sum of merge passes that the sort algorithm has had to do. If this value is large.
sum_sort_range The sum of sorts that were done using ranges.
sum_sort_rows The sum of sorted rows.
sum_sort_scan The sum of sorts that were done by scanning the table.
sum_timer_wait The total wait time of the summarized timed events. This value is calculated only for timed events because nontimed events have a wait time of NULL, in nanoseconds.
sum_warnings The sum of warnings, from the statement diagnostics area.

PostgreSQL

Variable description
blk_read_time Total time the statement spent reading blocks, in nanoseconds.
blk_write_time Total time the statement spent writing blocks, in nanoseconds.
calls Number of times executed.
database_name The name of the database.
local_blks_dirtied Total number of local blocks dirtied by the statement.
local_blks_hit Total number of local block cache hits by the statement.
local_blks_read Total number of local blocks read by the statement.
local_blks_written Total number of local blocks written by the statement.
max_time Maximum time spent in the statement, in nanoseconds.
mean_time Mean time spent in the statement, in nanoseconds.
min_time Minimum time spent in the statement, in nanoseconds
query Text of a representative statement.
rows Total number of rows retrieved or affected by the statement.
shared_blks_dirtied Total number of shared blocks dirtied by the statement.
shared_blks_hit Total number of shared block cache hits by the statement.
shared_blks_read Total number of shared blocks read by the statement.
shared_blks_written Total number of shared blocks written by the statement.
stddev_time Population standard deviation of time spent in the statement, in nanoseconds.
temp_blks_read Total number of temp blocks read by the statement.
temp_blks_written Total number of temp blocks written by the statement.
total_time Total time spent in the statement, in nanoseconds.
user_name The user that executed the statement.

Normal response

HTTP/1.1 200 OK
{
  "pg": [
    {
      "blk_read_time": 0,
      "blk_write_time": 0,
      "calls": 57425,
      "database_name": "defaultdb",
      "local_blks_dirtied": 0,
      "local_blks_hit": 0,
      "local_blks_read": 0,
      "local_blks_written": 0,
      "max_time": 133387,
      "mean_time": 1060,
      "min_time": 151,
      "query": "COMMIT",
      "rows": 0,
      "shared_blks_dirtied": 0,
      "shared_blks_hit": 0,
      "shared_blks_read": 0,
      "shared_blks_written": 0,
      "stddev_time": 0,
      "temp_blks_read": 0,
      "temp_blks_written": 0,
      "total_time": 60879904,
      "user_name": "upadmin"
    },
    {
      "blk_read_time": 0,
      "blk_write_time": 0,
      "calls": 47,
      "database_name": "defaultdb",
      "local_blks_dirtied": 0,
      "local_blks_hit": 0,
      "local_blks_read": 0,
      "local_blks_written": 0,
      "max_time": 7123443,
      "mean_time": 1442887,
      "min_time": 819392,
      "query": "SELECT name, setting FROM pg_settings WHERE source = $1",
      "rows": 54,
      "shared_blks_dirtied": 0,
      "shared_blks_hit": 0,
      "shared_blks_read": 0,
      "shared_blks_written": 0,
      "stddev_time": 0,
      "temp_blks_read": 0,
      "temp_blks_written": 0,
      "total_time": 67815714,
      "user_name": "upadmin"
    }
    ... more statistics ...
  ]
}

List metrics

Returns metrics related to a Managed Database service by its {uuid} and query parameter {period}.

Request

GET /1.3/database/{uuid}/metrics?period={period} HTTP/1.1

Query Parameters

Attribute Accepted value Required Description
period hour / day / week / month / year yes Metrics time period.

Normal response

HTTP/1.1 200 OK
{
  "cpu_usage": {
    "data": {
      "cols": [
        { "label": "time", "type": "date" },
        { "label": "test-1 (master)", "type": "number" },
        { "label": "test-2 (standby)", "type": "number" }
      ],
      "rows": [
        ["2022-01-21T13:10:30Z", 2.744682398273781, 3.054323473090861],
        ["2022-01-21T13:11:00Z", 3.0735645433218366, 2.972423595745795],
        ["2022-01-21T13:11:30Z", 2.61619694060839, 3.1358378052207883],
        ["2022-01-21T13:12:00Z", 3.275132296130991, 4.196249043309251]
      ]
    },
    "hints": { "title": "CPU usage %" }
  },
  "disk_usage": {
    "data": {
      "cols": [
        { "label": "time", "type": "date" },
        { "label": "test-1 (master)", "type": "number" },
        { "label": "test-2 (standby)", "type": "number" }
      ],
      "rows": [
        ["2022-01-21T13:10:30Z", 5.654416415900109, 5.58959125727556],
        ["2022-01-21T13:11:00Z", 5.654416415900109, 5.58959125727556],
        ["2022-01-21T13:11:30Z", 5.654416415900109, 5.58959125727556]
      ]
    },
    "hints": { "title": "Disk space usage %" }
  },
  "diskio_reads": {
    "data": {
      "cols": [
        { "label": "time", "type": "date" },
        { "label": "test-1 (master)", "type": "number" },
        { "label": "test-2 (standby)", "type": "number" }
      ],
      "rows": [
        ["2022-01-21T13:10:30Z", 0, 0],
        ["2022-01-21T13:11:00Z", 0, 0],
        ["2022-01-21T13:11:30Z", 0, 0]
      ]
    },
    "hints": { "title": "Disk iops (reads)" }
  },
  "diskio_writes": {
    "data": {
      "cols": [
        { "label": "time", "type": "date" },
        { "label": "test-1 (master)", "type": "number" },
        { "label": "test-2 (standby)", "type": "number" }
      ],
      "rows": [
        ["2022-01-21T13:10:30Z", 3, 2],
        ["2022-01-21T13:11:00Z", 2, 3],
        ["2022-01-21T13:11:30Z", 4, 3]
      ]
    },
    "hints": { "title": "Disk iops (writes)" }
  },
  "load_average": {
    "data": {
      "cols": [
        { "label": "time", "type": "date" },
        { "label": "test-1 (master)", "type": "number" },
        { "label": "test-2 (standby)", "type": "number" }
      ],
      "rows": [
        ["2022-01-21T13:10:30Z", 0.11, 0.11],
        ["2022-01-21T13:11:00Z", 0.14, 0.1],
        ["2022-01-21T13:11:30Z", 0.14, 0.09]
      ]
    },
    "hints": { "title": "Load average (5 min)" }
  },
  "mem_usage": {
    "data": {
      "cols": [
        { "label": "time", "type": "date" },
        { "label": "test-1 (master)", "type": "number" },
        { "label": "test-2 (standby)", "type": "number" }
      ],
      "rows": [
        ["2022-01-21T13:10:30Z", 11.491766148261078, 12.318932883261219],
        ["2022-01-21T13:11:00Z", 11.511967645759277, 12.304403727425075],
        ["2022-01-21T13:11:30Z", 11.488581675749048, 12.272260458006759]
      ]
    },
    "hints": { "title": "Memory usage %" }
  },
  "net_receive": {
    "data": {
      "cols": [
        { "label": "time", "type": "date" },
        { "label": "test-1 (master)", "type": "number" },
        { "label": "test-2 (standby)", "type": "number" }
      ],
      "rows": [
        ["2022-01-21T13:10:30Z", 442, 470],
        ["2022-01-21T13:11:00Z", 439, 384],
        ["2022-01-21T13:11:30Z", 466, 458]
      ]
    },
    "hints": { "title": "Network receive (bytes/s)" }
  },
  "net_send": {
    "data": {
      "cols": [
        { "label": "time", "type": "date" },
        { "label": "test-1 (master)", "type": "number" },
        { "label": "test-2 (standby)", "type": "number" }
      ],
      "rows": [
        ["2022-01-21T13:10:30Z", 672, 581],
        ["2022-01-21T13:11:00Z", 660, 555],
        ["2022-01-21T13:11:30Z", 694, 573]
      ]
    },
    "hints": { "title": "Network transmit (bytes/s)" }
  }
}

List logical databases

Returns a list of logical databases for a Managed Database service identified by {uuid}.

Request

GET /1.3/database/{uuid}/databases HTTP/1.1

Normal response

[
  {
    "name": "db12311111",
    "lc_collate": "en_US.UTF-8",
    "lc_ctype": "en_US.UTF-8"
  },
  {
    "name": "defaultdb",
    "lc_collate": "en_US.UTF-8",
    "lc_ctype": "en_US.UTF-8"
  }
]

Create logical database

Creates a new logical database for the Managed Database service {uuid}.

Request

POST /1.3/database/{uuid}/databases HTTP/1.1
{
  "name": "database-doc-api",
  "lc_collate": "en_US.UTF8",
  "lc_ctype": "en_US.UTF8"
}

Attributes

Attribute Accepted value Default value Required Description
name 1-40 characters yes Service database name.
lc_collate 1-128 characters en_US.UTF-8 no PostgreSQL only, default string sort order (LC_COLLATE).
lc_ctype 1-128 characters en_US.UTF-8 no PostgreSQL only, default character classification (LC_CTYPE).

Normal response

HTTP/1.1 200 OK

Error responses

HTTP status Error code Description
409 Conflict DB_EXISTS Service database with same name already exists.
400 Bad Request SERVICE_ERROR Invalid {lc_lc_collate_value} / {lc_ctype_value}, correct form is {correct_lc_*_value}.
400 Bad Request SERVICE_ERROR Unsupported {lc_collate} / {lc_ctype}.
400 Bad Request VALIDATION_ERROR Invalid input for database: Must consist of alpha-numeric characters, underscores or dashes, may not start with dash, max 40 characters.

Delete logical database

Deletes the logical database {database_name} from the Managed Database service {uuid}.

Request

DELETE /1.3/database/{uuid}/databases/{database_name} HTTP/1.1

Normal response

HTTP/1.1 204 No Content

Error responses

HTTP status Error code Description
404 Not Found DB_NOT_FOUND Logical database not found.

List users

Returns a list of database users associated with the Managed Database service {uuid}.

Request

GET /1.3/database/{uuid}/users HTTP/1.1

Normal response

[
  {
    "username": "upadmin",
    "password": "my-password",
    "authentication": "caching_sha2_password",
    "type": "primary"
  },
  {
    "username": "api-doc-user",
    "password": "my-password-2",
    "authentication": "caching_sha2_password",
    "type": "normal"
  }
]

Get user details

Returns the user {username} details for the Managed Database service {uuid}.

Request

GET /1.3/database/{uuid}/users/{username} HTTP/1.1

Normal response

{
  "username": "api-doc-user",
  "password": "my-password",
  "authentication": "caching_sha2_password",
  "type": "normal"
}

Create user

Creates a new user for the Managed Database service {uuid}.

Request

POST /1.3/database/{uuid}/users HTTP/1.1
{
  "username": "api-doc-user",
  "authentication": "caching_sha2_password",
  "password": "new-password"
}

Attributes

Attribute Accepted value Default value Required Description
name 1-64 characters yes Service username.
authentication caching_sha2_password / mysql_native_password caching_sha2_password no MySQL only, authentication type.
password 8-256 characters randomly generated no User password.

Normal response

HTTP/1.1 200 OK
{
  "username": "api-doc-user",
  "password": "gZMWrgrPmIZLlo9n",
  "authentication": "caching_sha2_password",
  "type": "normal"
}

Error responses

HTTP status Error code Description
409 Conflict SERVICE_ERROR Service username already exists.
400 Bad Request VALIDATION_ERROR User password is too short, min length is 8 characters.
400 Bad Request VALIDATION_ERROR Invalid input for username: Must consist of alpha-numeric characters, dots, underscores or dashes, may not start with dash or dot, max 64 characters.
400 Bad Request VALIDATION_ERROR MySQL only, Invalid input for authentication. Is not one of [None, 'caching_sha2_password', 'mysql_native_password'].

Modify user

Modifies the user {username} details for the Managed Database service {uuid}.

Request

PATCH /1.3/database/{uuid}/users/{username} HTTP/1.1
{
  "authentication": "caching_sha2_password",
  "password": "new-password"
}

Attributes

Attribute Accepted value Required Description
password 8-256 characters no New user password.
authentication caching_sha2_password / mysql_native_password no MySQL only, authentication type.

Normal response

HTTP/1.1 200 OK

Error responses

HTTP status Error code Description
400 Bad Request VALIDATION_ERROR User password is too short, min length is 8 characters.
400 Bad Request VALIDATION_ERROR MySQL only, Invalid input for authentication. Is not one of [None, 'caching_sha2_password', 'mysql_native_password'].

Delete user

Deletes the user {username} from the Managed Database service {uuid}.

Request

DELETE /1.3/database/{uuid}/users/{username} HTTP/1.1

Normal response

HTTP/1.1 204 No Content

Error responses

HTTP status Error code Description
404 Not Found USER_NOT_FOUND User not found.

List connection pools (PostgreSQL)

Returns a list of available connection pools for a Managed Database service. Connection pools are available only for PostgreSQL database services.

Request

GET /1.3/database/{uuid}/connection-pools HTTP/1.1

Normal response

[
  {
    "connection_uri": "postgres://upadmin:[email protected]t.db.upclouddatabases.com:11551/pool-1?sslmode=require",
    "database": "defaultdb",
    "pool_mode": "session",
    "pool_name": "pool-1",
    "pool_size": 50,
    "username": "upadmin"
  },
  {
    "connection_uri": "postgres://pg-2x2xcpu-4gb-50gb-de-fra1-example-prefix-project.db.upclouddatabases.com:11551/pool-2?sslmode=require",
    "database": "defaultdb",
    "pool_mode": "transaction",
    "pool_name": "pool-2",
    "pool_size": 10,
    "username": ""
  }
]

Get connection pool details (PostgreSQL)

Returns the connection pool {pool_name} details for the Managed Database service {uuid}.

Request

GET /1.3/database/{uuid}/connection-pools/{pool_name} HTTP/1.1

Normal response

{
  "connection_uri": "postgres://upadmin:[email protected]upclouddatabases.com:11551/pool-1?sslmode=require",
  "database": "defaultdb",
  "pool_mode": "session",
  "pool_name": "pool-1",
  "pool_size": 50,
  "username": "upadmin"
}

Create connection pool (PostgreSQL)

Creates a connection pool for the Managed Database service {uuid}. Connection pool endpoints are for PostgreSQL Managed Databases only.

Request

POST /1.3/database/{uuid}/connection-pools HTTP/1.1
{
  "database": "defaultdb",
  "pool_mode": "transaction",
  "pool_name": "pool-1",
  "pool_size": 10,
  "username": "upadmin"
}

Attributes

Attribute Accepted value Required Description
database 1-40 characters yes Service logical database name.
pool_mode session / transaction / statement yes Connection pool mode.
pool_name 1-63 characters yes Connection pool name.
pool_size 1-1000 yes Connection pool size.
username 1-64 characters no Service username. If not set, all users are allowed to access this connection pool.

Normal response

HTTP/1.1 200 OK
{
  "connection_uri": "postgres://pg-2x2xcpu-4gb-50gb-de-fra1-example-prefix-project.db.upclouddatabases.com:11551/pool-8?sslmode=require",
  "database": "defaultdb",
  "pool_mode": "transaction",
  "pool_name": "pool-8",
  "pool_size": 10,
  "username": "upadmin"
}

Error responses

HTTP status Error code Description
409 Conflict SERVICE_ERROR Service connection pool {pool_name} already exists.
400 Bad Request SERVICE_ERROR Invalid input for {pool_name} : Must consist of alpha-numeric characters, underscores or dashes, may not start with dash, max 63 characters.
409 Conflict SERVICE_ERROR Pools attached to the PostgreSQL instance have more connections='exceeded_value' than the database can handle='limit_value'. To remedy this, either upgrade your plan, or decrease pool size. Note that three connections from your plan are reserved for database maintenance.
400 Bad Request SERVICE_ERROR Invalid input for {pool_mode} is not one of ['session', 'transaction', 'statement'].
403 Forbidden SERVICE_ERROR Service {database} does not exist.
403 Forbidden SERVICE_ERROR Service database {username} does not exist.

Modify connection pool (PostgreSQL)

Modifies the connection pool {pool_name} for the Managed Database service {uuid}.

Request

PATCH /1.3/database/{uuid}/connection-pools/{pool_name} HTTP/1.1
{
  "database": "defaultdb",
  "pool_mode": "transaction",
  "pool_size": 10,
  "username": "upadmin"
}

Attributes

Attribute Accepted value Required Description
database 1-40 characters no Service database name.
pool_mode session / transaction / statement no Connection pool mode.
pool_size 1-1000 no Connection pool size.
username 1-64 characters no Service username, if not set it will allow all users to access this connection pool.

Normal response

HTTP/1.1 200 OK

Error responses

HTTP status Error code Description
409 Conflict SERVICE_ERROR Pools attached to the PostgreSQL instance have more connections='exceeded_value' than the database can handle='limit_value'. To remedy this, either upgrade your plan, or decrease pool size. Note that three connections from your plan are reserved for database maintenance.
400 Bad Request SERVICE_ERROR Invalid input for {pool_mode} is not one of ['session', 'transaction', 'statement'].
403 Forbidden SERVICE_ERROR Service {database} does not exist.
403 Forbidden SERVICE_ERROR Service database {username} does not exist.

Delete connection pool (PostgreSQL)

Deletes the connection pool {pool_name} for the Managed Database service {uuid}.

Request

DELETE /1.3/database/{uuid}/connection-pools/{pool_name} HTTP/1.1

Normal response

HTTP/1.1 204 No Content

Error responses

HTTP status Error code Description
404 Not Found CONNECTION_POOL_NOT_FOUND Connection pool not found.