16. 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
pending	Indicates newly created service or started reconfiguration.
setup-network	Configuring network.
check-network	Check that the network configuration was applied correctly.
setup-peer	Configuring SDN network peerings if provided.
setup-service	Service is being created or reconfigured.
check-peer	Check SDN network peerings was established if provided.
rebuilding	Service creation in progress.
rebalancing	Service is being upgraded or migrated.
error	Service encountered an error that requires user action.
running	Indicates service up and running.
stopped	Service is stopped.
cleanup-service	Cleaning up service resources.
cleanup-network	Cleaning up network resources.
delete-service	Deleting the service.

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

To get all the available extensions, including the version number of the extension, run select * from pg_available_extensions in your DBaaS managed service for PostgreSQL.

Redis

Redis is an open-source data storage engine that can serve as a key-value database, cache, and message broker. Redis provides various types of data structures including strings, hashes, lists, sets, and sorted sets with range queries, bitmaps, hyperloglog, geospatial indexes, and streams. Redis has built-in replication, Lua scripting, LRU eviction, transactions, and different levels of on-disk persistence, and provides high availability via Redis Sentinel and automatic partitioning with Redis Cluster.

OpenSearch

OpenSearch database is a searchable collection of data that follows the OpenSearch protocol. It is created for various purposes and can be used to standardize search queries across different sources. By using an OpenSearch API, data can be made accessible to a wide range of search engines and tools, allowing for easy discovery and access.

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_mysql": {
          "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_pg": {
          "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_msql": {
          "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

Query parameters

Attribute	Accepted value	Default value	Required	Description
limit	0-100	10	no	Number of entries to receive at most.
offset	>= 0	0	no	Offset for retrieved results.

Normal response

HTTP/1.1 200 OK

[
  {
    "backups": [
      {
        "backup_name": "backup-2022-01-06T12:36:06.739000Z",
        "backup_time": "2022-01-06T12:36:06.739000Z",
        "data_size": 36464640
      },
      {
        "backup_name": "backup-2022-01-07T12:36:06.261000Z",
        "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:example-prefix-project@pg-2x2xcpu-4gb-50gb-de-fra1-example-prefix-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": {
      "pending_updates": [
        {
          "deadline": "2022-01-21T12:21:00Z",
          "description": "description related to the update",
          "start_after": "2022-01-21T12:21:00Z",
          "start_at": "2022-01-21T12:21:00Z"
        }
      ],
      "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,
    "metadata": {
      "max_connections": 200,
      "pg_version": "13.5",
      "write_block_threshold_exceeded": false
   },
    "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: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"
    },
    "users": [
      {
        "username": "upadmin",
        "type": "primary"
      }
    ],
    "termination_protection": false,
    "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_name": "backup-2022-01-06T12:36:06.739000Z",
    "backup_time": "2022-01-06T12:36:06.739000Z",
    "data_size": 36464640
   },
   {
    "backup_name": "backup-2022-01-07T12:36:06.261000Z",
    "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:example-prefix-project@pg-2x2xcpu-4gb-50gb-de-fra1-example-prefix-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": {
   "pending_updates": [
     {
      "deadline": "2022-01-21T12:21:00Z",
      "description": "description related to the update",
      "start_after": "2022-01-21T12:21:00Z",
      "start_at": "2022-01-21T12:21:00Z"
     }
   ],
   "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,
  "metadata": {
    "max_connections": 200,
    "pg_version": "13.5",
    "write_block_threshold_exceeded": false
  },
  "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: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"
  },
  "users": [
   {
    "username": "upadmin",
    "type": "primary"
   }
  ],
  "termination_protection": false,
  "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"
  },
  "termination_protection": false,
  "properties": {
    "automatic_utility_network_ip_filter": true,
    "version": "8",
    "ip_filter": []
    ... more database type-specific configuration properties ...
  },
  "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"
    }
  ]
}

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 / redis	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.
termination_protection	boolean	no	Prevents the managed service from being powered off, or deleted.
networks	An array of 1-8 network objects	no	Attached Networks from where traffic consumed and routed. Private networks must reside in service zone.
labels	An array of 0-255 labels objects / null	no	Labels used for service filtering, see labels usage

Normal response

HTTP/1.1 200 OK

State error

When the service encounters an error during the state transition that is not recoverable, the service details response will include a state_error field containing details about the error and possible action needed from the user.

{
  ...
  "zone": "de-fra1",
  "maintenance": {
    ...
  },
  "state": "error",
  "state_error": {
    "setup-service": "failed to setup service 'service-name'..."
  },
  "termination_protection": false,
  "networks": [
    ...
  ]
}

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"
  },
  "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"
    }
  ]
}

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.
termination_protection	boolean	no	Prevents the managed service from being powered off, or deleted.
networks	An array of 1-8 network objects	no	Attached Networks from where traffic consumed and routed. Private networks must reside in service zone.
labels	An array of 0-255 labels objects / null	no	Labels used for service filtering, see labels usage

Error responses

HTTP status	Error code	Description
403 Forbidden	SERVICE_ERROR	Service is protected against termination and shutdown. Remove termination protection first.
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
403 Forbidden	SERVICE_ERROR	Service is protected against termination and shutdown. Remove termination protection first.
404 Not Found	SERVICE_NOT_FOUND	Service not found.

Attach SDN network

Attaches an SDN network to a Managed Database service by its {uuid}.

Request

POST /1.3/database/{uuid}/networks HTTP/1.1

{
    "name": "example-private-network",
    "uuid": "03bec0ad-85c3-459e-824d-710f8f24f740",
    "type": "private",
    "family": "IPv4"
}

Attributes

Attribute	Accepted value	Required	Description
name	1-64 characters, regexp pattern ^[a-zA-Z0-9_-]+$	yes	The name of the network must be unique within the service.
uuid	A valid network uuid	yes	Private network uuid.
type	private	yes	The type of the network.
family	IPv4	yes	Network family. IPv6 currently not supported.

Normal response

HTTP/1.1 201 Created

Error response

HTTP status	Error code	Description
402 Payment required	INSUFFICIENT_CREDITS	Customer account does not have enough credits for the requested action.
400 Bad Request	INVALID_REQUEST	Validation error.

List attached SDN networks

Returns a list of attached SDN networks to a Managed Database service by its {uuid}.

Request

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

Normal response

HTTP/1.1 200 OK

[
    {
      "uuid": "03aa7245-2ff9-49c8-9f0e-7ca0270d71a4",
      "name": "example-private-network",
      "family": "IPv4",
      "type": "private"
    }
]

Get attached SDN network details

Returns the attached SDN network details to service by its {uuid} and {network_name}.

Request

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

Normal response

HTTP/1.1 200 OK

{
  "uuid": "03aa7245-2ff9-49c8-9f0e-7ca0270d71a4",
  "name": "example-private-network",
  "family": "IPv4",
  "type": "private"
}

Detach SDN network

Detaches an existing SDN network from a Managed Database service by its {uuid} and {network_name}.

Request

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

Normal response

HTTP/1.1 204 No Content

Error response

HTTP status	Error code	Description
404 Not Found	RESOURCE_NOT_FOUND	Resource not found.

Get Service network peering status

Returns networks peering status for a service by its {uuid}. Only available for services using SDN private networks.

Request

GET /1.3/database/{uuid}/peering-status HTTP/1.1

Normal response

HTTP/1.1 200 OK

{
  "create_time": "2023-12-05T09:54:04Z",
  "update_time": "2023-12-05T09:54:09Z",
  "state": "active",
  "network_peerings": [
    {
      "create_time": "2023-12-05T09:54:15Z",
      "update_time": "2023-12-05T09:56:13Z",
      "network_peer": "03196597-b972-4815-ba3a-85bb18365ced",
      "state": "active",
      "state_info": "The peering is in active state"
    },
    {
      "create_time": "2023-12-05T09:54:15Z",
      "update_time": "2023-12-05T09:56:13Z",
      "network_peer": "03ca2397-1026-44ef-ad0c-0c6a3cb43694",
      "state": "active",
      "state_info": "The peering is in active state"
    },
    {
      "create_time": "2023-12-05T09:54:15Z",
      "update_time": "2023-12-05T09:56:13Z",
      "network_peer": "03d377e8-d449-4e68-9975-a8a0718e4e07",
      "state": "active",
      "state_info": "The peering is in active state"
    }
  ]
}

Get Managed Database task details (MySQL / PostgreSQL)

Returns task details of a Managed Database service by its {uuid} and the task {id} obtained from Create Managed Database task.

Request

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

Normal response

HTTP/1.1 200 OK

{
  "create_time": "2022-10-04T12:21:42Z",
  "operation": "mysql_migration_check",
  "id": "9b39f10d-e356-437b-b907-d6d5574721b2",
  "result_codes": [],
  "result": "All pre-checks passed successfully, preferred migration method will be [Replication]",
  "success": true
}

Create Managed Database task (MySQL / PostgreSQL)

Creates a task that checks for potential errors before starting a migration or upgrade for a Managed Database service by its {uuid}. There are two types of operations: sync and async. Synchronous operation returns the result on the same request. Asynchronous requests require tracking using Get Managed Database task details until the task is complete.

Migration check task (MySQL / PostgreSQL)

Request

POST /1.3/database/{uuid}/tasks HTTP/1.1

{
  "migration_check": {
    "source_service_uri": "postgresql://username:password@hostname:port/init_db",
    "method": "dump",
    "ignore_dbs": "db_name_1,db_name_2"
  },
  "operation": "migration_check"
}

Attributes

Attribute	Accepted value	Required	Description
operation	migration_check	yes	Operation name for the service task.
migration_check	Migration object	yes	Embedded migration check fields.
source_service_uri	A valid database connection string	yes	Database connection string.
method	dump / replication	no	Database migration method.
ignore_dbs	A Comma-separated list of databases names	no	Comma-separated list of databases to be ignored. Only supported for MySQL.

Normal response

HTTP/1.1 200 OK

{
  "create_time": "2022-09-22T07:22:15Z",
  "operation": "pg_migration_check",
  "id": "b32bb2e0-30dd-41b1-bb83-3de6806546a5",
  "operation_type": "async"
}

Upgrade check task (PostgreSQL)

Request

POST /1.3/database/{uuid}/tasks HTTP/1.1

{
  "target_version": "14",
  "operation": "upgrade_check"
}

Attributes

Attribute	Accepted value	Required	Description
operation	upgrade_check	yes	Operation name for the service task.
target_version	Major version number as a string	yes	Targeted major version number for the check. Check available versions from Get Managed Database versions.

Normal response

HTTP/1.1 200 OK

{
  "create_time": "2022-09-20T12:59:30Z",
  "result": "ok *Clusters are compatible*",
  "operation": "pg_upgrade_check",
  "success": true,
  "source_pg_version": "12",
  "target_pg_version": "14",
  "id": "96d1f15f-38c6-48b0-87ff-f62c2029338d",
  "operation_type": "sync"
}

Get External Database migration status (MySQL / PostgreSQL)

Returns details about the migration progress over time of a Managed database service by its {uuid}.

Request

GET /1.3/database/{uuid}/migration-status HTTP/1.1

Normal response

HTTP/1.1 200 OK

{
  "method": "replication",
  "seconds_behind_master": 0,
  "source_active": true,
  "status": "done",
  "databases": [
    {
      "dbname": "defaultdb",
      "method": "replication",
      "status": "syncing"
    }
  ]
}

Create External Database migration (MySQL / PostgreSQL)

Creates a migration process from an External Database to a Managed Database service by its {uuid}. Supports both dump and replication. It's recommended to determine in advance if the migration is possible between an External Database and a Managed Database service using Create Managed Database task: Migration check. Once the migration is started, you can track its progress using Get External Database migration status.

Note: To avoid unexpected migration failures or data losses to your Managed Database, the migration should be run on a new and empty Managed Database service.

Request

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

{
  "properties": {
    "migration": {
      "dbname": "source_db_name",
      "host": "100.237.30.9",
      "method": "replication",
      "ignore_dbs": "db_name_1,db_name_2",
      "password": "source_password@123",
      "port": 3306,
      "ssl": true,
      "username": "source_username"
    }
  }
}

Attributes

Attribute	Accepted value	Required	Description
migration	Migration object / null	yes	Embedded migration fields.
host	A valid hostname	yes	Hostname for source database connection.
username	A valid username	yes	Username for source database connection.
password	A valid password	yes	Password for source database connection.
dbname	A valid database name	no	Database name for source database to initiate connection.
ignore_dbs	A Comma-separated list of databases names	no	Comma-separated list of databases to be ignored. Only supported for MySQL.
method	dump / replication	no	Force a method when running the migration. Only supported for MySQL and Redis.
port	1-65535	yes	Post for the source database connection.
ssl	true / false	yes	SSL settings for source database connection.

Normal response

HTTP/1.1 200 OK

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.

Start maintenance updates Managed Database

Start maintenance updates for your Managed Database service if any updates are pending.

Request

PUT /1.3/database/{uuid}/start-maintenance HTTP/1.1

Normal response

HTTP status	Description
200 OK	maintenance started.
200 OK	service is up to date, maintenance not required.

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	Only for PostgreSQL and MySQL. Create a clone of your database service data from the backups at the selected point in time.
backup_name	A valid backup name	Latest created backup if available	no	Only for Redis. Create a clone of your database service data from the backups by name.
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	SERVICE_ERROR	Requested to restore backup {backup_name} but no such backup exists.
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 sessions (MySQL / PostgreSQL / Redis)

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

Request

GET /1.3/database/{uuid}/sessions?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	Session content variable and sorting order combined with a colon ( "pid:desc" )	query_duration:desc	no	Order by Session content variable and sort retrieved results. Limited variables can be used for ordering.

Session content description

Contains information about the returned session variables.

PostgreSQL

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.
id	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, it shows the last query that was executed.
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.

MySQL

Variable	Description
application_name	Name of the application that is connected to this service.
client_addr	IP address of the client connected to this service.
datname	Name of the database this service is connected to.
id	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, it shows an empty string.
query_duration	The active query current duration.
state	Current overall state of this service: active: The service is executing a query, idle: The service is waiting for a new client command.
usename	Name of the user logged into this service.

Redis

Variable	Description
application_name	Name of the application that is connected to this service.
active_channel_subscriptions	Number of active channel subscriptions
active_database	Current database ID
active_pattern_matching_channel_subscriptions	Number of pattern matching subscriptions.
client_addr	IP address of the client connected to this service.
connection_age	Total duration of the connection in nanoseconds.
connection_idle	Idle time of the connection in nanoseconds.
flags	List of array containing flags description.
flags_raw	Client connection flags.
id	Process ID of this session.
multi_exec_commands	Number of commands in a MULTI/EXEC context.
output_buffer	Output buffer length.
output_buffer_memory	Output buffer memory usage.
output_list_length	Output list length (replies are queued in this list when the buffer is full).
query	The last executed command.
query_buffer	Query buffer length (0 means no query pending).
query_buffer_free	Free space of the query buffer (0 means the buffer is full).

Postgres normal response

HTTP/1.1 200 OK

{
  "pg": [
    {
      "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": "111.111.111.111",
      "client_hostname": null,
      "client_port": 61264,
      "datid": 16401,
      "datname": "defaultdb",
      "id": "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
    }
  ]
}

MySQL normal response

HTTP/1.1 200 OK

{
  "mysql": [
    {
      "application_name": "",
      "client_addr": "111.111.111.111:63244",
      "datname": "defaultdb",
      "id": "pid_23325",
      "query": "select\n            ordinal_position,\n            column_name,\n            column_type,\n            column_default,\n            generation_expression,\n            table_name,\n            column_comment,\n            is_nullable,\n            extra,\n            collation_name\n          from information_schema.columns\n          where table_schema = 'performance_schema'\n          order by table_name, ordinal_position",
      "query_duration": 0,
      "state": "active",
      "usename": "upadmin"
    }
  ]
}

Redis normal response

HTTP/1.1 200 OK

{
  "redis": [
    {
      "active_channel_subscriptions": 0,
      "active_database": "",
      "active_pattern_matching_channel_subscriptions": 0,
      "client_addr": "[fff0:fff0:fff0:fff0:0:fff0:fff0:fff0]:39956",
      "connection_age": 2079483000000000,
      "connection_idle": 3000000000,
      "flags": [],
      "flags_raw": "N",
      "id": "15",
      "multi_exec_commands": -1,
      "application_name": "",
      "output_buffer": 0,
      "output_buffer_memory": 0,
      "output_list_length": 0,
      "query": "info",
      "query_buffer": 0,
      "query_buffer_free": 0
    }
  ]
}

Terminate session (MySQL / PostgreSQL)

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

Request

DELETE /1.3/database/{uuid}/sessions/{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 (MySQL / PostgreSQL)

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 (MySQL / PostgreSQL)

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 (MySQL / PostgreSQL)

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 (MySQL / PostgreSQL)

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 responses

MySQL

[
  {
    "username": "upadmin",
    "password": "my-password",
    "authentication": "caching_sha2_password",
    "type": "primary"
  }
]

PostgreSQL

[
  {
    "username": "api-doc-user",
    "password": "my-password-2",
    "type": "normal",
    "pg_access_control": {
      "allow_replication": true
    }
  }
]

Redis

[
  {
    "username": "api-doc-user",
    "password": "my-password-2",
    "type": "regular",
    "redis_access_control": {
      "categories": ["+@set"],
      "channels": ["*"],
      "commands": ["+set"],
      "keys": ["key_*"]
    }
  }
]

OpenSearch

[
  {
    "username": "api-doc-user",
    "password": "new-password",
    "opensearch_access_control": {
      "rules": [
        {
          "index": "index_1",
          "permission": "read"
        },
        {
          "index": "index_2",
          "permission": "write"
        }
      ]
    }
  }
]

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}.

Note:

For Redis services, ACL commands are restricted to ensure replication, backups and configuration management. They can only be set on creation using this endpoint or modified using the Modify user access control endpoint.

For OpenSearch services, when the Security management admin is enabled, all users and access control will be migrated to Security management and this endpoint will be restricted.

Request

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

MySQL

{
  "username": "api-doc-user",
  "authentication": "caching_sha2_password",
  "password": "new-password"
}

PostgreSQL

{
  "username": "api-doc-user",
  "password": "new-password",
  "pg_access_control": {
    "allow_replication": true
  }
}

Redis

{
  "username": "api-doc-user",
  "password": "new-password",
  "redis_access_control": {
    "categories": ["+@set"],
    "channels": ["*"],
    "commands": ["+set"],
    "keys": ["key_*"]
  }
}

OpenSearch

{
  "username": "api-doc-user",
  "password": "new-password",
  "opensearch_access_control": {
    "rules": [
      {
        "index": "index_1",
        "permission": "read"
      },
      {
        "index": "index_2",
        "permission": "write"
      }
    ]
  }
}

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.
pg_access_control	Access control object with PostgreSQL attributes		no	PostgreSQL access control object.
redis_access_control	Access control object with Redis attributes		no	Redis access control object.
opensearch_access_control	Access control object with OpenSearch attributes		no	OpenSearch access control object.

PostgreSQL access control attributes

Attribute	Accepted value	Default value	Required	Description
allow_replication	boolean	true	no	Grant replication privilege

Redis access control attributes

Attribute	Accepted value	Default value	Required	Description
categories	An array of strings		no	Set access control to all commands in specified categories
channels	An array of strings	['*']	no	Set access control to Pub/Sub channels.
commands	An array of strings		no	Set access control to commands.
keys	An array of strings		no	Set access control to keys.

OpenSearch access control attributes

Attribute	Accepted value	Default value	Required	Description
rules	An array of rule objects	[]	no	Access control object containing index and permission keys.
index	An index name / pattern / Top-level API		no	Set index name, pattern or top level API. Check Pattern & Access control.
permission	deny / admin / readwrite / read / write		no	Set permission access.

Rules

Access control rules in OpenSearch will not be enforced unless you enable access control explicitly Modify Access Control. This means that unless you turn on access control, all users will have unrestricted access to your OpenSearch cluster. Once you enable access control, you can define rules that restrict users' actions based on their roles, permissions, or other criteria.

Access control rules have the ability to grant access to the top-level APIs. Only rules starting with _ are considered for controlling access to top-level APIs, while normal index rules do not apply to these APIs. For instance:

*search/admin rule only grants access to matching indices, not to _msearch.

_*/admin grants unrestricted access to all top-level APIs.

_msearch/admin allows unlimited access to only the _msearchAPI.

ACLs control access to the API but not how it's used. Giving access to the top-level API overrides index-specific rules. If given _msearch/admin access, one can search any index through the API since the indices to search are specified in the request body.

Permission access

The permission also determines which index APIs the user can access:

Permission	API access
admin	No restriction.
readwrite	Allows access to _search, _mget, _bulk, _mapping, _update_by_query, and _delete_by_query APIs.
read	Allows access to _search and _mget APIs.
write	Allows access to _bulk, _mapping, _update_by_query, and _delete_by_query APIs.
deny	No access.

Patterns

Patterns are glob-style strings that use the following syntax:

Pattern	Description
*	Matches any number of characters (including none).
?	Matches any single character

Aliases

Include alias patterns explicitly in ACL rules as they are not automatically expanded in access control. Only access control rules that match the alias pattern will be applied, and rules that match physical indices will not be used.

Normal responses

HTTP/1.1 200 OK

MySQL

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

PostgreSQL

{
  "username": "api-doc-user",
  "password": "new-password",
  "type": "normal",
  "pg_access_control": {
    "allow_replication": true
  }
}

Redis

{
  "username": "api-doc-user",
  "password": "new-password",
  "type": "regular",
  "redis_access_control": {
    "categories": ["+@set"],
    "channels": ["*"],
    "commands": ["+set"],
    "keys": ["key_*"]
  }
}

OpenSearch

{
  "username": "api-doc-user",
  "password": "new-password",
  "type": "normal",
  "opensearch_access_control": {
    "rules": [
      {
        "index": "index_1",
        "permission": "read"
      },
      {
        "index": "index_2",
        "permission": "write"
      }
    ]
  }
}

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}.

Note: For OpenSearch services, when the Security management admin is enabled, all users and access control will be migrated to Security management and this endpoint will be restricted.

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'].

Modify user access control

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

Note:

For Redis services, ACL commands are restricted to ensure replication, backups and configuration management. They can only be modified using this endpoint or set on creation using the Create user endpoint.

For OpenSearch services, when the Security management admin is enabled, all users and access control will be migrated to security configuration and access from the API is restricted.

Request

PATCH /1.3/database/{uuid}/users/{username}/access-control HTTP/1.1

PostgreSQL

{
  "pg_access_control": {
    "allow_replication": true
  }
}

Redis

{
  "redis_access_control": {
    "categories": [],
    "channels": ["*"],
    "commands": [],
    "keys": []
  }
}

OpenSearch

{
  "opensearch_access_control": {
    "rules": []
  }
}

Attributes

Attribute	Accepted value	Required	Description
pg_access_control	access control object with PostgreSQL attributes	no	PostgreSQL access control object.
redis_access_control	access control object with Redis attributes	no	Redis access control object.
opensearch_access_control	access control object with OpenSearch attributes	no	OpenSearch access control object.

Normal response

HTTP/1.1 200 OK

Error responses

HTTP status	Error code	Description
400 Bad Request	VALIDATION_ERROR	Must provide 'allow_replication' in the 'pg_access_control' payload.
400 Bad Request	VALIDATION_ERROR	"Must provide at least one of ['channels','commands','keys','categories'] in the 'redis_access_control' payload."

Delete user

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

Note: For OpenSearch services, when the Security management admin is enabled, all users and access control will be migrated to Security management and this endpoint will be restricted.

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:xxxxxxxxxxxxxx@pg-2x2xcpu-4gb-50gb-de-fra1-example-prefix-project.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:U5j43ZzVZ1nDrOtO@pg-2x2xcpu-4gb-50gb-de-fra1-devqtahseeggcyt.db.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-10000	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-10000	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.

Get service access controls (OpenSearch)

Return access controls settings for the OpenSearch Managed Database service {uuid}.

Request

GET /1.3/database/{uuid}/access-control HTTP/1.1

Normal response

HTTP/1.1 200 OK

{
  "access_control": false,
  "extended_access_control": false
}

Access controls content description

Attribute	Description
access_control	Enables users access control for OpenSearch service. Access control rules set in Modify user access control will only be enforced if this attribute is enabled.
extended_access_control	Grant access to top-level _mget, _msearch and _bulk APIs. Users are limited to perform operations on indices based on the user-specific access control rules.

Modify service access controls (OpenSearch)

Modifies access controls settings for the OpenSearch Managed Database service {uuid}.

Enabling access control in OpenSearch will enforce the access control rules currently set for each user. If a user does not have any rules defined, they will be denied all access by default. This means that to grant access to a user, you must first define the appropriate access control rules that allow them to perform specific actions or access certain resources within the service. Without these rules in place, users will be unable to interact with OpenSearch.

If the Security management admin is enabled, all users and access control will be migrated to Security management and this endpoint will be restricted.

Request

PATCH /1.3/database/{uuid}/access-control HTTP/1.1

{
  "access_control": true,
  "extended_access_control": false
}

Attributes

Attribute	Accepted value	Required	Description
access_control	true / false	no	Enables users access control for OpenSearch service. Access control rules set in Modify user access control will only be enforced if this attribute is enabled.
extended_access_control	true / false	no	Grant access to top-level _mget, _msearch and _bulk APIs. Users are limited to perform operations on indices based on the user-specific access control rules.

Normal response

HTTP/1.1 200 OK

Get Security management status (OpenSearch)

Returns Security management status for the OpenSearch Managed Database service {uuid}.

Request

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

Normal response

HTTP/1.1 200 OK

{
  "security_plugin_admin_enabled": true,
  "security_plugin_available": true,
  "security_plugin_enabled": true
}

Security management status content description

Attribute	Description
security_plugin_admin_enabled	Security plugin admin defined.
security_plugin_available	Opensearch security available for the service.
security_plugin_enabled	Opensearch security enabled for the service.

Enable Security management admin (OpenSearch)

Enables Security management admin for the OpenSearch Managed Database service {uuid}.

After enabling Security management for the service, it cannot be reverted or disabled. The UpCloud API for managing users and access control will no longer be accessible. Instead, user authentication and access control should be administered through the OpenSearch Security Dashboard or OpenSearch Security API.

Request

POST /1.3/database/{uuid}/security/admin HTTP/1.1

{
  "admin_password": "d.9aB_23Q"
}

Attributes

Attribute	Accepted value	Required	Description
admin_password	8-256 characters	yes	Security configuration admin password.

Normal response

HTTP/1.1 200 OK

{
  "security_plugin_admin_enabled": true,
  "security_plugin_available": true,
  "security_plugin_enabled": true
}

Modify Security management admin password (OpenSearch)

Modifies Security management admin password for the OpenSearch Managed Database service {uuid}.

Request

PUT /1.3/database/{uuid}/security/admin HTTP/1.1

{
  "admin_password": "d.9aB_23Q",
  "new_password": "d.9aB_43Q"
}

Attributes

Attribute	Accepted value	Required	Description
admin_password	8-256 characters	yes	Current security configuration admin password.
new_password	8-256 characters	yes	New security configuration admin password.

Normal response

HTTP/1.1 200 OK

{
  "security_plugin_admin_enabled": true,
  "security_plugin_available": true,
  "security_plugin_enabled": true
}

List Indices (OpenSearch)

Returns a list of available indices for a Managed Database service {uuid}.

Request

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

Normal response

[
  {
    "create_time": "2023-05-11T13:24:10.623Z",
    "docs": 1,
    "health": "green",
    "index_name": ".kibana_1",
    "number_of_replicas": 0,
    "number_of_shards": 1,
    "read_only_allow_delete": false,
    "size": 5313,
    "status": "open"
  },
  {
    "create_time": "2023-05-11T13:24:10.623Z",