Database API

API versions

Lists information for all Database Service API versions.

GET
/

List versions

Lists information about all Database Service API versions. No authentication needed.

Normal response codes: 200

Response Example

{
    "versions": [
        {
            "id": "v1.0",
            "links": [
                {
                    "href": "http://127.0.0.1:8779/v1.0/",
                    "rel": "self"
                }
            ],
            "status": "CURRENT",
            "updated": "2012-08-01T00:00:00Z"
        }
    ]
}

Datastores

GET
/v1.0/{project_id}/datastores

List datastores

Get all the datastores registered in the system

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

Response Example

{
    "datastores": [
        {
            "default_version": "9e46a201-e92e-4ae0-af89-4af12a21bb45",
            "id": "75dc45e0-2c3c-47ee-a5b8-5213288e3fe2",
            "links": [
                {
                    "href": "https://127.0.0.1:8779/v1.0/9f8dd5eacb074c9f87d2d822c9092aa5/datastores/75dc45e0-2c3c-47ee-a5b8-5213288e3fe2",
                    "rel": "self"
                },
                {
                    "href": "https://127.0.0.1:8779/datastores/75dc45e0-2c3c-47ee-a5b8-5213288e3fe2",
                    "rel": "bookmark"
                }
            ],
            "name": "mariadb",
            "versions": [
                {
                    "id": "9e46a201-e92e-4ae0-af89-4af12a21bb45",
                    "links": [
                        {
                            "href": "https://127.0.0.1:8779/v1.0/9f8dd5eacb074c9f87d2d822c9092aa5/datastores/versions/9e46a201-e92e-4ae0-af89-4af12a21bb45",
                            "rel": "self"
                        },
                        {
                            "href": "https://127.0.0.1:8779/datastores/versions/9e46a201-e92e-4ae0-af89-4af12a21bb45",
                            "rel": "bookmark"
                        }
                    ],
                    "name": "10.4"
                }
            ]
        },
        {
            "default_version": "b3d5c099-dbd5-4518-baa3-7c7c195671bf",
            "id": "3bf89e46-c3ed-4db6-a423-6e6709ec21ef",
            "links": [
                {
                    "href": "https://127.0.0.1:8779/v1.0/9f8dd5eacb074c9f87d2d822c9092aa5/datastores/3bf89e46-c3ed-4db6-a423-6e6709ec21ef",
                    "rel": "self"
                },
                {
                    "href": "https://127.0.0.1:8779/datastores/3bf89e46-c3ed-4db6-a423-6e6709ec21ef",
                    "rel": "bookmark"
                }
            ],
            "name": "mysql",
            "versions": [
                {
                    "id": "b3d5c099-dbd5-4518-baa3-7c7c195671bf",
                    "links": [
                        {
                            "href": "https://127.0.0.1:8779/v1.0/9f8dd5eacb074c9f87d2d822c9092aa5/datastores/versions/b3d5c099-dbd5-4518-baa3-7c7c195671bf",
                            "rel": "self"
                        },
                        {
                            "href": "https://127.0.0.1:8779/datastores/versions/b3d5c099-dbd5-4518-baa3-7c7c195671bf",
                            "rel": "bookmark"
                        }
                    ],
                    "name": "5.7"
                }
            ]
        },
        {
            "id": "cc9ee471-e781-43bf-a796-423c5d549997",
            "links": [
                {
                    "href": "https://127.0.0.1:8779/v1.0/9f8dd5eacb074c9f87d2d822c9092aa5/datastores/cc9ee471-e781-43bf-a796-423c5d549997",
                    "rel": "self"
                },
                {
                    "href": "https://127.0.0.1:8779/datastores/cc9ee471-e781-43bf-a796-423c5d549997",
                    "rel": "bookmark"
                }
            ],
            "name": "postgresql",
            "versions": [
                {
                    "id": "4eb0179d-fe11-4556-9422-5267d2fc7625",
                    "links": [
                        {
                            "href": "https://127.0.0.1:8779/v1.0/9f8dd5eacb074c9f87d2d822c9092aa5/datastores/versions/4eb0179d-fe11-4556-9422-5267d2fc7625",
                            "rel": "self"
                        },
                        {
                            "href": "https://127.0.0.1:8779/datastores/versions/4eb0179d-fe11-4556-9422-5267d2fc7625",
                            "rel": "bookmark"
                        }
                    ],
                    "name": "12"
                }
            ]
        }
    ]
}
GET
/v1.0/{project_id}/datastores/{datastore}

Show datastore details

Shows datastore details

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

datastore (Optional)

path

string

Name or ID of the data store.

Response Example

{
    "datastore": {
        "id": "cc9ee471-e781-43bf-a796-423c5d549997",
        "links": [
            {
                "href": "https://127.0.0.1:8779/v1.0/9f8dd5eacb074c9f87d2d822c9092aa5/datastores/cc9ee471-e781-43bf-a796-423c5d549997",
                "rel": "self"
            },
            {
                "href": "https://127.0.0.1:8779/datastores/cc9ee471-e781-43bf-a796-423c5d549997",
                "rel": "bookmark"
            }
        ],
        "name": "postgresql",
        "versions": [
            {
                "id": "4eb0179d-fe11-4556-9422-5267d2fc7625",
                "links": [
                    {
                        "href": "https://127.0.0.1:8779/v1.0/9f8dd5eacb074c9f87d2d822c9092aa5/datastores/versions/4eb0179d-fe11-4556-9422-5267d2fc7625",
                        "rel": "self"
                    },
                    {
                        "href": "https://127.0.0.1:8779/datastores/versions/4eb0179d-fe11-4556-9422-5267d2fc7625",
                        "rel": "bookmark"
                    }
                ],
                "name": "12"
            }
        ]
    }
}
DELETE
/v1.0/{project_id}/datastores/{datastore}

Delete datastore

Delete a datastore.

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

datastore (Optional)

path

string

Name or ID of the data store.

Datastore Versions

GET
/v1.0/{project_id}/datastores/{datastore}/versions

List datastore versions

Get all the registered versions for a given datastore

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

datastore (Optional)

path

string

Name or ID of the data store.

Response Example

{
    "versions": [
        {
            "datastore": "cc9ee471-e781-43bf-a796-423c5d549997",
            "id": "4eb0179d-fe11-4556-9422-5267d2fc7625",
            "links": [
                {
                    "href": "https://127.0.0.1:8779/v1.0/9f8dd5eacb074c9f87d2d822c9092aa5/datastores/versions/4eb0179d-fe11-4556-9422-5267d2fc7625",
                    "rel": "self"
                },
                {
                    "href": "https://127.0.0.1:8779/datastores/versions/4eb0179d-fe11-4556-9422-5267d2fc7625",
                    "rel": "bookmark"
                }
            ],
            "name": "12",
            "version": "5.7.29"
        }
    ]
}
GET
/v1.0/{project_id}/datastores/{datastore}/versions/{version}

Show datastore version

Get information for a given datastore version(name or ID)

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

datastore (Optional)

path

string

Name or ID of the data store.

version (Optional)

path

string

Name or ID of the datastore version. If there are multiple datastore versions with the same name but different version numbers, ID is needed.

Response Example

{
    "version": {
        "datastore": "cc9ee471-e781-43bf-a796-423c5d549997",
        "id": "4eb0179d-fe11-4556-9422-5267d2fc7625",
        "links": [
            {
                "href": "https://127.0.0.1:8779/v1.0/9f8dd5eacb074c9f87d2d822c9092aa5/datastores/versions/4eb0179d-fe11-4556-9422-5267d2fc7625",
                "rel": "self"
            },
            {
                "href": "https://127.0.0.1:8779/datastores/versions/4eb0179d-fe11-4556-9422-5267d2fc7625",
                "rel": "bookmark"
            }
        ],
        "name": "12",
        "version": "5.7.29"
    }
}
GET
/v1.0/{project_id}/datastores/{datastore}/versions/{version}/parameters

List datastore version configuration parameters

Get all the config parameters associated with the specified datastore version

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

datastore (Optional)

path

string

Name or ID of the data store.

version (Optional)

path

string

Name or ID of the datastore version. If there are multiple datastore versions with the same name but different version numbers, ID is needed.

Response Example

{
    "configuration-parameters": [
        {
            "datastore_version_id": "b3d5c099-dbd5-4518-baa3-7c7c195671bf",
            "max": 1,
            "min": 0,
            "name": "autocommit",
            "restart_required": false,
            "type": "integer"
        },
        {
            "datastore_version_id": "b3d5c099-dbd5-4518-baa3-7c7c195671bf",
            "max": 65535,
            "min": 1,
            "name": "auto_increment_increment",
            "restart_required": false,
            "type": "integer"
        },
        {
            "datastore_version_id": "b3d5c099-dbd5-4518-baa3-7c7c195671bf",
            "max": 65535,
            "min": 1,
            "name": "auto_increment_offset",
            "restart_required": false,
            "type": "integer"
        },
        {
            "datastore_version_id": "b3d5c099-dbd5-4518-baa3-7c7c195671bf",
            "max": 31536000,
            "min": 1,
            "name": "wait_timeout",
            "restart_required": false,
            "type": "integer"
        }
    ]
}
GET
/v1.0/{project_id}/datastores/{datastore}/versions/{version}/parameters/{parameter_name}

Show datastore version configuration parameter

Get the specified config parameter definition.

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

datastore (Optional)

path

string

Name or ID of the data store.

version (Optional)

path

string

Name or ID of the datastore version. If there are multiple datastore versions with the same name but different version numbers, ID is needed.

parameter_name (Optional)

path

string

The name of the parameter for which to show details.

Response Example

{
    "datastore_version_id": "b3d5c099-dbd5-4518-baa3-7c7c195671bf",
    "max": 31536000,
    "min": 1,
    "name": "wait_timeout",
    "restart_required": false,
    "type": "integer"
}
GET
/v1.0/{project_id}/datastores/versions/{datastore_version_id}

Show datastore version

Get information for a given datastore version ID.

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

datastore_version_id (Optional)

path

string

The UUID of the data store version.

Response Example

{
    "version": {
        "datastore": "cc9ee471-e781-43bf-a796-423c5d549997",
        "id": "4eb0179d-fe11-4556-9422-5267d2fc7625",
        "links": [
            {
                "href": "https://127.0.0.1:8779/v1.0/9f8dd5eacb074c9f87d2d822c9092aa5/datastores/versions/4eb0179d-fe11-4556-9422-5267d2fc7625",
                "rel": "self"
            },
            {
                "href": "https://127.0.0.1:8779/datastores/versions/4eb0179d-fe11-4556-9422-5267d2fc7625",
                "rel": "bookmark"
            }
        ],
        "name": "12",
        "version": "5.7.29"
    }
}
GET
/v1.0/{project_id}/datastores/versions/{datastore_version_id}/parameters

List datastore version configuration parameters

Get all the config parameters associated with the specified datastore version ID.

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

datastore_version_id (Optional)

path

string

The UUID of the data store version.

Response Example

{
    "configuration-parameters": [
        {
            "datastore_version_id": "b3d5c099-dbd5-4518-baa3-7c7c195671bf",
            "max": 1,
            "min": 0,
            "name": "autocommit",
            "restart_required": false,
            "type": "integer"
        },
        {
            "datastore_version_id": "b3d5c099-dbd5-4518-baa3-7c7c195671bf",
            "max": 65535,
            "min": 1,
            "name": "auto_increment_increment",
            "restart_required": false,
            "type": "integer"
        },
        {
            "datastore_version_id": "b3d5c099-dbd5-4518-baa3-7c7c195671bf",
            "max": 65535,
            "min": 1,
            "name": "auto_increment_offset",
            "restart_required": false,
            "type": "integer"
        },
        {
            "datastore_version_id": "b3d5c099-dbd5-4518-baa3-7c7c195671bf",
            "max": 31536000,
            "min": 1,
            "name": "wait_timeout",
            "restart_required": false,
            "type": "integer"
        }
    ]
}
GET
/v1.0/{project_id}/datastores/versions/{datastore_version_id}/parameters/{parameter_name}

Show datastore version configuration parameter

Get the specified config parameter definition.

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

datastore_version_id (Optional)

path

string

The UUID of the data store version.

parameter_name (Optional)

path

string

The name of the parameter for which to show details.

Response Example

{
    "datastore_version_id": "b3d5c099-dbd5-4518-baa3-7c7c195671bf",
    "max": 31536000,
    "min": 1,
    "name": "wait_timeout",
    "restart_required": false,
    "type": "integer"
}
POST
/v1.0/{project_id}/mgmt/datastores/versions/{datastore_version_id}/parameters

Create datastore version configuration parameters

Admin only API. Register a configuration parameter for the specified datastore version. The parameter definition contains the type, minimum and maximum values(if type is integer), and whether you must restart the instance after the parameter value is changed.

Normal response codes: 200

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

datastore_version_id (Optional)

path

string

The UUID of the data store version.

Request Example

{
    "configuration-parameter": {
        "name": "connect_timeout",
        "data_type": "integer",
        "min_size": 64,
        "max_size": 65535,
        "restart_required": 0
    }
}

Response Example

{
    "configuration-parameters": [
        {
            "datastore_version_id": "4eb0179d-fe11-4556-9422-5267d2fc7625",
            "max": 65535,
            "min": 64,
            "name": "connect_timeout",
            "restart_required": false,
            "type": "integer"
        }
    ]
}
PUT
/v1.0/{project_id}/mgmt/datastores/versions/{datastore_version_id}/parameters/{parameter_name}

Update a datastore version configuration parameter

Admin only API. Update a configuration parameter for the specified datastore version.

Normal response codes: 200

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

datastore_version_id (Optional)

path

string

The UUID of the data store version.

parameter_name (Optional)

path

string

The name of the parameter for which to show details.

Request Example

{
    "configuration-parameter": {
        "name": "connect_timeout",
        "data_type": "integer",
        "min_size": 64,
        "max_size": 65535,
        "restart_required": 1
    }
}

Response Example

{
    "datastore_version_id": "4eb0179d-fe11-4556-9422-5267d2fc7625",
    "deleted": 0,
    "deleted_at": null,
    "max_size": 65535,
    "min_size": 64,
    "name": "connect_timeout",
    "restart_required": true,
    "type": "integer"
}
DELETE
/v1.0/{project_id}/mgmt/datastores/versions/{datastore_version_id}/parameters/{parameter_name}

Delete a datastore version configuration parameter

Admin only API. Remove a configuration parameter for the specified datastore version.

Normal response codes: 204

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

datastore_version_id (Optional)

path

string

The UUID of the data store version.

parameter_name (Optional)

path

string

The name of the parameter for which to show details.

POST
/v1.0/{project_id}/mgmt/datastore-versions

Create datastore version

Admin only API. Register a datastore version, the datastore is created automatically if doesn’t exist.

It’s allowed to create datastore versions with the same name but different version numbers, or vice versa.

Normal response codes: 202

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

name

body

string

The name of the datastore version. Different datastore versions can have the same name.

datastore_name

body

string

The name of a datastore.

datastore_manager

body

string

The type of a datastore.

image (Optional)

body

string

The ID of an image.

Either image or image_tags needs to be specified when creating datastore version.

image_tags (Optional)

body

array

List of image tags.

Either image or image_tags needs to be specified when creating datastore version.

If the image ID is not provided, the image can be retrieved by the image tags. The tags are used for filtering as a whole rather than separately. Using image tags is more flexible than ID especially when a new guest image is uploaded to Glance, Trove can pick up the latest image automatically for creating instances.

When updating, only specifying image_tags could remove image from the datastore version.

active

body

boolean

Whether the database version is enabled.

default (Optional)

body

boolean

When true this datastore version is created as the default in the datastore. If not specified, for creating, default is false, for updating, it’s ignored.

version (Optional)

body

string

The version number for the database. In container based trove instance deployment, the version number is the same as the container image tag, e.g. for MySQL, a valid version number is 5.7.30

Request Example

{
    "version": {
        "datastore_name": "mysql",
        "datastore_manager": "mysql",
        "name": "test",
        "image_tags": ["trove"],
        "active": true,
        "default": false,
        "packages": [],
        "version": "5.7.30"
    }
}
GET
/v1.0/{project_id}/mgmt/datastore-versions

List datastore versions

Admin only API. Get all the datastore versions.

Normal response codes: 200

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

Response Example

{
    "versions": [
        {
            "active": true,
            "datastore_id": "75dc45e0-2c3c-47ee-a5b8-5213288e3fe2",
            "datastore_manager": "mariadb",
            "datastore_name": "mariadb",
            "default": false,
            "id": "385fa391-f6f1-4444-9d80-7dc3b2188fa3",
            "image": "42706631-3b76-4d1c-95c9-6a85e72eebda",
            "name": "10.4-dev-train",
            "packages": [
                ""
            ],
            "version": "10.4.12"
        },
        {
            "active": true,
            "datastore_id": "cc9ee471-e781-43bf-a796-423c5d549997",
            "datastore_manager": "postgresql",
            "datastore_name": "postgresql",
            "default": false,
            "id": "4eb0179d-fe11-4556-9422-5267d2fc7625",
            "image": "2eb8005f-270c-492f-977e-3c041a622ef7",
            "name": "12",
            "packages": [
                ""
            ],
            "version": "12.4"
        }
    ]
}
GET
/v1.0/{project_id}/mgmt/datastore-versions/{datastore_version_id}

Show datastore version details

Admin only API. Get information for a datastore version.

Normal response codes: 200

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

datastore_version_id (Optional)

path

string

The UUID of the data store version.

Response Example

{
    "version": {
        "active": true,
        "datastore_id": "75dc45e0-2c3c-47ee-a5b8-5213288e3fe2",
        "datastore_manager": "mariadb",
        "datastore_name": "mariadb",
        "default": false,
        "id": "385fa391-f6f1-4444-9d80-7dc3b2188fa3",
        "image": "42706631-3b76-4d1c-95c9-6a85e72eebda",
        "name": "10.4-dev-train",
        "packages": [
            ""
        ],
        "version": "10.4.12"
    }
}
PATCH
/v1.0/{project_id}/mgmt/datastore-versions/{datastore_version_id}

Update datastore version details

Admin only API. Update a specific datastore version.

The version number is not allowed to update.

Normal response codes: 202

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

datastore_version_id (Optional)

path

string

The UUID of the data store version.

name (Optional)

body

string

The name of the datastore version. Different datastore versions can have the same name.

datastore_manager (Optional)

body

string

The type of a datastore.

image (Optional)

body

string

The ID of an image.

Either image or image_tags needs to be specified when creating datastore version.

image_tags (Optional)

body

array

List of image tags.

Either image or image_tags needs to be specified when creating datastore version.

If the image ID is not provided, the image can be retrieved by the image tags. The tags are used for filtering as a whole rather than separately. Using image tags is more flexible than ID especially when a new guest image is uploaded to Glance, Trove can pick up the latest image automatically for creating instances.

When updating, only specifying image_tags could remove image from the datastore version.

active (Optional)

body

boolean

Whether the database version is enabled.

default (Optional)

body

boolean

When true this datastore version is created as the default in the datastore. If not specified, for creating, default is false, for updating, it’s ignored.

Request Example

{
    "name": "new name",
    "image": "42706631-3b76-4d1c-95c9-6a85e72eebda",
    "active": true
}
DELETE
/v1.0/{project_id}/mgmt/datastore-versions/{datastore_version_id}

Delete a datastore version

Admin only API. Delete a specific datastore version.

Normal response codes: 202

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

datastore_version_id (Optional)

path

string

The UUID of the data store version.

Instances

GET
/v1.0/{project_id}/instances

List database instances

Lists information for all database instances. Supported filters: include_clustered

Normal response codes: 200

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

Response Example

{
    "instances": [
        {
            "datastore": {
                "type": "mysql",
                "version": "5.7"
            },
            "flavor": {
                "id": "6"
            },
            "id": "7de1bed8-6983-4d46-9a52-0abfbb0d27a2",
            "ip": [
                "10.1.0.62",
                "172.24.5.114"
            ],
            "links": [
                {
                    "href": "https://127.0.0.1:8779/v1.0/9f8dd5eacb074c9f87d2d822c9092aa5/instances/7de1bed8-6983-4d46-9a52-0abfbb0d27a2",
                    "rel": "self"
                },
                {
                    "href": "https://127.0.0.1:8779/instances/7de1bed8-6983-4d46-9a52-0abfbb0d27a2",
                    "rel": "bookmark"
                }
            ],
            "name": "test",
            "operating_status": "HEALTHY",
            "region": "RegionOne",
            "status": "ACTIVE",
            "volume": {
                "size": 1
            }
        }
    ]
}
GET
/v1.0/{project_id}/mgmt/instances

List database instances(admin)

Admin only API. Get all the instances, Could show more information such as Cinder volume ID, Nova server information, etc.

Supported filters:

  • deleted.

  • include_clustered.

  • project_id: Get instances of a speficied project.

Normal response codes: 200

Response Example

{
    "instances": [
        {
            "addresses": [
                {
                    "address": "10.1.0.62",
                    "type": "private",
                    "network": "3dc8f3c2-f335-11eb-878c-00224d6b7bc1"
                },
                {
                    "address": "172.24.5.114",
                    "type": "public"
                }
            ],
            "created": "2019-12-23T20:58:35",
            "datastore": {
                "type": "mysql",
                "version": "5.7"
            },
            "deleted": false,
            "deleted_at": null,
            "encrypted_rpc_messaging": true,
            "flavor": {
                "id": "d2"
            },
            "id": "7de1bed8-6983-4d46-9a52-0abfbb0d27a2",
            "ip": [
                "10.1.0.62",
                "172.24.5.114"
            ],
            "links": [
                {
                    "href": "https://127.0.0.1:8779/v1.0/2afa58fd5db34fd8b7b659d997a5341f/instances/7de1bed8-6983-4d46-9a52-0abfbb0d27a2",
                    "rel": "self"
                },
                {
                    "href": "https://127.0.0.1:8779/instances/7de1bed8-6983-4d46-9a52-0abfbb0d27a2"
                }
            ],
            "name": "test",
            "operating_status": "HEALTHY",
            "region": "RegionOne",
            "server": {
                "host": "bdfe3275004d2a98d38d494fd7adfcd0c6d5d5198e86fa0d6ec5d588",
                "id": "710a84e5-6adf-4a4c-9167-8bade67a5a1c",
                "name": "test",
                "status": "ACTIVE",
                "tenant_id": "27ac4b83e9d045eb8c373bacaa994eb7"
            },
            "server_id": "710a84e5-6adf-4a4c-9167-8bade67a5a1c",
            "service_status": "HEALTHY",
            "service_status_updated": "2019-12-24T00:02:55",
            "status": "ACTIVE",
            "task_description": "No tasks for the instance.",
            "tenant_id": "9f8dd5eacb074c9f87d2d822c9092aa5",
            "updated": "2019-12-23T23:53:46",
            "volume": {
                "size": 1
            },
            "volume_id": "ccb62e29-73ea-4859-b206-3b3a4e30a991"
        },
        {
            "created": "2019-12-23T20:53:38",
            "datastore": {
                "type": "mysql",
                "version": "5.7"
            },
            "deleted": false,
            "deleted_at": null,
            "encrypted_rpc_messaging": true,
            "fault": {
                "created": "2019-12-23T20:53:41",
                "details": "Failed to create User port for instance b76a6a76-748b-4064-adec-4c9e6c9abd68",
                "message": "Failed to create User port for instance b76a6a76-748b-4064-adec-4c9e6c9abd68"
            },
            "flavor": {
                "id": "6"
            },
            "id": "b76a6a76-748b-4064-adec-4c9e6c9abd68",
            "links": [
                {
                    "href": "https://127.0.0.1:8779/v1.0/2afa58fd5db34fd8b7b659d997a5341f/instances/b76a6a76-748b-4064-adec-4c9e6c9abd68",
                    "rel": "self"
                },
                {
                    "href": "https://127.0.0.1:8779/instances/b76a6a76-748b-4064-adec-4c9e6c9abd68",
                    "rel": "bookmark"
                }
            ],
            "name": "test",
            "operating_status": "",
            "region": "RegionOne",
            "server": null,
            "server_id": null,
            "service_status": "NEW",
            "service_status_updated": "2019-12-23T20:53:38",
            "status": "ERROR",
            "task_description": "Build error: Port.",
            "tenant_id": "9f8dd5eacb074c9f87d2d822c9092aa5",
            "updated": "2019-12-23T20:53:41",
            "volume": {
                "size": 1
            },
            "volume_id": null
        }
    ]
}
GET
/v1.0/{project_id}/instances/detail

List database instances(with details)

Lists information for all database instances with more details, such as created and updated time, service status updated time, the failure message, etc. Supported filters: include_clustered

Normal response codes: 200

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

Response Example

{
    "instances": [
        {
            "addresses": [
                {
                    "address": "10.1.0.62",
                    "type": "private",
                    "network": "3dc8f3c2-f335-11eb-878c-00224d6b7bc1"
                },
                {
                    "address": "172.24.5.114",
                    "type": "public"
                }
            ],
            "created": "2019-12-23T20:58:35",
            "datastore": {
                "type": "mysql",
                "version": "5.7"
            },
            "flavor": {
                "id": "6"
            },
            "id": "7de1bed8-6983-4d46-9a52-0abfbb0d27a2",
            "ip": [
                "10.1.0.62",
                "172.24.5.114"
            ],
            "links": [
                {
                    "href": "https://127.0.0.1:8779/v1.0/9f8dd5eacb074c9f87d2d822c9092aa5/instances/7de1bed8-6983-4d46-9a52-0abfbb0d27a2",
                    "rel": "self"
                },
                {
                    "href": "https://127.0.0.1:8779/instances/7de1bed8-6983-4d46-9a52-0abfbb0d27a2",
                    "rel": "bookmark"
                }
            ],
            "name": "test",
            "operating_status": "HEALTHY",
            "region": "RegionOne",
            "service_status_updated": "2019-12-23T21:01:11",
            "status": "ACTIVE",
            "updated": "2019-12-23T20:58:45",
            "volume": {
                "size": 1
            }
        },
        {
            "created": "2019-12-23T20:53:38",
            "datastore": {
                "type": "mysql",
                "version": "5.7"
            },
            "fault": {
                "created": "2019-12-23T20:53:41",
                "details": null,
                "message": "Failed to create User port for instance b76a6a76-748b-4064-adec-4c9e6c9abd68"
            },
            "flavor": {
                "id": "6"
            },
            "id": "b76a6a76-748b-4064-adec-4c9e6c9abd68",
            "links": [
                {
                    "href": "https://127.0.0.1:8779/v1.0/9f8dd5eacb074c9f87d2d822c9092aa5/instances/b76a6a76-748b-4064-adec-4c9e6c9abd68",
                    "rel": "self"
                },
                {
                    "href": "https://127.0.0.1:8779/instances/b76a6a76-748b-4064-adec-4c9e6c9abd68",
                    "rel": "bookmark"
                }
            ],
            "name": "test",
            "operating_status": "",
            "region": "RegionOne",
            "service_status_updated": "2019-12-23T20:53:38",
            "status": "ERROR",
            "updated": "2019-12-23T20:53:41",
            "volume": {
                "size": 1
            }
        }
    ]
}
POST
/v1.0/{project_id}/instances

Create database instance

Creates a database instance.

Normally, you must specify a flavor ID, a volume size and the network the instance is attached to. The service provisions the instance with a volume of the requested size, which serves as storage for the database instance.

If creating replica (a secondary instance of the replication cluster), flavor and volume size are not needed.

The database service can only be access within the tenant network, unless the access parameter is defined.

Normal response codes: 200

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

users (Optional)

body

array

A users object.

users.name

body

string

The name of a user.

users.password

body

string

The password of a user.

users.host (Optional)

body

string

A host allowed for a user.

users.databases (Optional)

body

array

The databases object. This is a list of databases which the user can access.

users.databases.name

body

string

The name of a database which the user can access.

datastore (Optional)

body

object

A datastore object.

datastore.type (Optional)

body

string

The type of a datastore.

datastore.version (Optional)

body

string

Name of the datastore version to use when creating/updating the instance.

datastore.version_number (Optional)

body

string

The version number for the database. In container based trove instance deployment, the version number is the same as the container image tag, e.g. for MySQL, a valid version number is 5.7.30

name

body

string

Name of the instance.

flavorRef

body

string

Reference (href), which is the actual URI to a flavor as it appears in the list flavors response. Rather than the flavor URI, you can also pass the flavor ID (integer) as the flavorRef value. For example, 1.

volume (Optional)

body

object

A volume object.

volume.size

body

integer

The volume size, in gigabytes (GB). A valid value is from 1 to 50(this limit is controlled by the configuration max_accepted_volume_size).

volume.type (Optional)

body

string

The volume type to use. You can list the available volume types on your system by using the cinder type- list command. If you want to specify a volume type, you must also specify a volume size.

modules (Optional)

body

object

The modules object.

modules.id

body

string

The ID of a module.

restorePoint (Optional)

body

object

The restorePoint object. Use this paramter to create an instance from a backup.

restorePoint.backupRef

body

string

The backup id used from which a new instance is created.

availability_zone (Optional)

body

string

The availability zone of the instance.

nics (Optional)

body

array

Network interface definition for database instance. This is a list of mappings for backward compatibility, but only one item is allowed. The allowed keys in the mapping are: network_id, subnet_id, ip_address and net-id (for backward compatibility, deprecated).

Trove will allocate port using the given information. In order to successfully create database instance, either the user should make sure the traffic coming through that port could access the public contaier image registry(i.e. the port subnet is associated with a Neutron router), or the cloud provider should be responsible for that.

replica_of

body

string

ID or name of an existing instance to replicate from.

replica_count (Optional)

body

integer

Number of replicas to create (defaults to 1).

locality (Optional)

body

string

The scheduler hint when creating underlying Nova instances. Valide values are: affinity, anti-affinity.

region_name (Optional)

body

string

The region name of an instance.

databases (Optional)

body

array

A databases object.

databases.characterSet (Optional)

body

string

A set of symbols and encodings. Default is utf8. For information about supported character sets and collations, see Character Sets and Collations in MySQL.

databases.collate (Optional)

body

string

A set of rules for comparing characters in a character set. Default is utf8_general_ci. For information about supported character sets and collations, see Character Sets and Collations in MySQL.

instance

body

object

An instance object.

configuration

body

string

ID of the configuration group that you want to attach to the instance.

access (Optional)

body

object

A access object defines how the database service is exposed.

access.is_public (Optional)

body

boolean

Whether the database service is exposed to the public.

access.allowed_cidrs (Optional)

body

array

A list of IPv4, IPv6 or mix of both CIDRs that restrict access to the database service. 0.0.0.0/0 is used by default if this parameter is not provided.

Request Example

{
  "instance": {
    "name": "test",
    "flavorRef": 1,
    "volume": {"size": 2},
    "nics": [{"net-id": "a5330d7d-0e8c-48b4-9f6c-0f2c4ab1b854"}],
    "datastore": {
      "type": "mysql",
      "version": "5.7"
    },
    "databases": [
      {
        "character_set": "utf8mb3",
        "collate": "utf8mb3_general_ci",
        "name": "sampledb"
      },
      {
        "name": "nextround"
      }
    ],
    "users": [
      {
        "databases": [
          {
              "name": "sampledb"
          }
        ],
        "name": "demouser",
        "password": "demopassword"
      }
    ],
    "access": {
      "is_public": true,
      "allowed_cidrs": ["202.78.240.0/24"]
    }
  }
}

Response Parameters

Name

In

Type

Description

id

body

string

The ID of the database instance.

name

body

string

Name of the instance.

status

body

string

Status of the instance.

operating_status

body

string

The operating status of the database service inside the Trove instance.

links

body

array

The links object of the instance.

links.href

body

string

The href attribute of an instance link.

links.rel

body

string

The rel attribute of an instance link.

flavor

body

object

A flavor object, which includes the flavor ID (integer) and flavor relative links.

flavor.id

body

string

The ID of the flavor.

flavor.links

body

array

The links object of a flavor.

flavor.links.href

body

string

The href attribute of a flavor link.

flavor.links.rel

body

string

The rel attribute of a flavor link.

datastore

body

object

A datastore object.

datastore.type (Optional)

body

string

The type of a datastore.

datastore.version

body

string

Name or ID of a datastore version.

datastore.version_number (Optional)

body

string

The version number for the database. In container based trove instance deployment, the version number is the same as the container image tag, e.g. for MySQL, a valid version number is 5.7.30

volume (Optional)

body

object

A volume object.

volume.size

body

integer

The volume size, in gigabytes (GB). A valid value is from 1 to 50(this limit is controlled by the configuration max_accepted_volume_size).

volume.used (Optional)

body

float

The used space of the volume, in gigabytes (GB).

created

body

string

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

updated

body

string

The date and time when the resource was updated.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, is the time zone as an offset from UTC.

For example, 2015-08-27T09:49:58-05:00.

The UTC time zone is assumed.

service_status_updated

body

string

The date and time when the database service status was updated. This field can be used to validate if the ‘HEALTHY’ status is stale or not.

locality (Optional)

body

string

The scheduler hint when creating underlying Nova instances. Valide values are: affinity, anti-affinity.

password (Optional)

body

string

The password of the database root user(i.e. the administrative user).

instance

body

object

An instance object.

Response Example

{
    "instance": {
        "id": "b76a6a76-748b-4064-adec-4c9e6c9abd68",
        "name": "test",
        "status": "BUILD",
        "operating_status": "",
        "datastore": {
            "type": "mysql",
            "version": "5.7.29",
            "version_number": "5.7.29"
        },
        "flavor": {
          "id": "3ca76fe7-8dc1-4059-b728-de725835abcb",
          "links": [
            {
              "href": "https://192.168.206.8:87 79/v1.0/c37341d7d1934ebc949c9d6b5c9f818c/flavors/3ca76fe7-8dc1-4059-b728-de725835abcb",
              "rel": "self"
            },
            {
              "href": "https://192.168.206.8:8779/flavors/3ca76fe7-8dc1-4059-b728-de725835abcb",
              "rel": "bookmark"
            }
          ]
        },
        "links": [
            {
                "href": "https://127.0.0.1:8779/v1.0/9f8dd5eacb074c9f87d2d822c9092aa5/instances/b76a6a76-748b-4064-adec-4c9e6c9abd68",
                "rel": "self"
            },
            {
                "href": "https://127.0.0.1:8779/instances/b76a6a76-748b-4064-adec-4c9e6c9abd68",
                "rel": "bookmark"
            }
        ],
        "region": "RegionOne",
        "access": {
          "is_public": false
        },
        "volume": {
            "size": 1
        },
        "created": "2019-12-23T20:53:38",
        "updated": "2019-12-23T20:53:38",
        "service_status_updated": "2019-12-23T20:53:38"
    }
}
GET
/v1.0/{project_id}/instances/{instanceId}

Show database instance details

Shows database instance details.

Lists the volume size in gigabytes (GB) and the approximate GB used. After instance creation, the used value is greater than 0, which is expected as databases may create some basic (non empty) files to represent an empty schema. The response does not include the used attribute when the instance status is BUILD, REBOOT, RESIZE, or ERROR.

Normal response codes: 200

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

instanceId

path

string

The ID of the database instance.

Response Parameters

Name

In

Type

Description

instance

body

object

An instance object.

id

body

string

The ID of the database instance.

name

body

string

Name of the instance.

status

body

string

Status of the instance.

operating_status

body

string

The operating status of the database service inside the Trove instance.

links

body

array

The links object of the instance.

links.href

body

string

The href attribute of an instance link.

links.rel

body

string

The rel attribute of an instance link.

flavor

body

object

A flavor object, which includes the flavor ID (integer) and flavor relative links.

flavor.id

body

string

The ID of the flavor.

flavor.links

body

array

The links object of a flavor.

flavor.links.href

body

string

The href attribute of a flavor link.

flavor.links.rel

body

string

The rel attribute of a flavor link.

datastore

body

object

A datastore object.

datastore.type (Optional)

body

string

The type of a datastore.

datastore.version

body

string

Name or ID of a datastore version.

region

body

string

The region name of an instance.

tenant_id (Optional)

body

string

The ID of a tenant.

volume (Optional)

body

object

A volume object.

volume.size

body

integer

The volume size, in gigabytes (GB). A valid value is from 1 to 50(this limit is controlled by the configuration max_accepted_volume_size).

volume.used (Optional)

body

float

The used space of the volume, in gigabytes (GB).

hostname (Optional)

body

string

The hostname of an instance.

ip (Optional)

body

string

The IP address of an instance(deprecated).

addresses (Optional)

body

array

The IP addresses of an instance, including the address type(“private” or “public”) and IP. “network” field is added since Xena when the address type is “private”.

created

body

string

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

updated

body

string

The date and time when the resource was updated.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, is the time zone as an offset from UTC.

For example, 2015-08-27T09:49:58-05:00.

The UTC time zone is assumed.

service_status_updated

body

string

The date and time when the database service status was updated. This field can be used to validate if the ‘HEALTHY’ status is stale or not.

fault (Optional)

body

object

The fault object of an instance.

fault.message

body

string

The fault message of an instance.

fault.created

body

string

The update timestamp of the fault message for an instance.

fault.details

body

string

The detail fault explanation of an instance.

replicas (Optional)

body

array

The replicas object of an instance.

replicas.id

body

string

The ID of a replica instance.

replicas.links

body

array

The links object of a replica instance.

replicas.links.href

body

string

The href attribute of a replica instance link.

replicas.links.rel

body

string

The rel attribute of a replica instance link.

replica_of (Optional)

body

string

The primary instance ID of this replica.

configuration (Optional)

body

object

A configuration object.

configuration.id

body

string

The ID of a configuration.

configuration.name

body

string

The name of a configuration.

configuration.links

body

array

The links object of a configuration.

configuration.links.href

body

string

The href attribute of a configuration link.

configuration.links.rel

body

string

The rel attribute of a configuration link.

locality (Optional)

body

string

The scheduler hint when creating underlying Nova instances. Valide values are: affinity, anti-affinity.

local_storage_used (Optional)

body

float

The used space of the ephemeral disk, in gigabytes (GB).

password (Optional)

body

string

The password of the database root user(i.e. the administrative user).

cluster_id (Optional)

body

string

The cluster ID of an instance.

shard_id (Optional)

body

string

The shard ID of an instance.

server_id (Optional)

body

string

The ID of the underlying Nova instance for an instance.

volume_id (Optional)

body

string

The ID of a volume.

encrypted_rpc_messaging (Optional)

body

boolean

Whether the instance is using encrypted rpm messaging feature or not.

access (Optional)

body

object

A access object defines how the database service is exposed.

access.is_public (Optional)

body

boolean

Whether the database service is exposed to the public.

access.allowed_cidrs (Optional)

body

array

A list of IPv4, IPv6 or mix of both CIDRs that restrict access to the database service. 0.0.0.0/0 is used by default if this parameter is not provided.

Response Example

{
    "instance": {
        "addresses": [
            {
                "address": "10.1.0.62",
                "type": "private",
                "network": "3dc8f3c2-f335-11eb-878c-00224d6b7bc1"
            },
            {
                "address": "172.24.5.114",
                "type": "public"
            }
        ],
        "created": "2019-12-23T20:58:35",
        "datastore": {
            "type": "mysql",
            "version": "5.7"
        },
        "flavor": {
            "id": "6"
        },
        "id": "7de1bed8-6983-4d46-9a52-0abfbb0d27a2",
        "ip": [
            "10.1.0.62",
            "172.24.5.114"
        ],
        "links": [
            {
                "href": "https://127.0.0.1:8779/v1.0/9f8dd5eacb074c9f87d2d822c9092aa5/instances/7de1bed8-6983-4d46-9a52-0abfbb0d27a2",
                "rel": "self"
            },
            {
                "href": "https://127.0.0.1:8779/instances/7de1bed8-6983-4d46-9a52-0abfbb0d27a2",
                "rel": "bookmark"
            }
        ],
        "name": "test",
        "operating_status": "HEALTHY",
        "region": "RegionOne",
        "service_status_updated": "2019-12-23T22:15:11",
        "status": "ACTIVE",
        "updated": "2019-12-23T20:58:45",
        "volume": {
            "size": 1,
            "used": 0.12
        }
    }
}
GET
/v1.0/{project_id}/mgmt/instances/{instanceId}

Show database instance details(admin)

Admin only API. Get an instance information, including Cinder volume, Nova server, etc.

Normal response codes: 200

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

instanceId

path

string

The ID of the database instance.

Response Example

{
    "instance": {
        "addresses": [
            {
                "address": "10.1.0.62",
                "type": "private",
                "network": "3dc8f3c2-f335-11eb-878c-00224d6b7bc1"
            },
            {
                "address": "172.24.5.114",
                "type": "public"
            }
        ],
        "created": "2019-12-23T20:58:35",
        "datastore": {
            "type": "mysql",
            "version": "5.7"
        },
        "deleted": false,
        "deleted_at": null,
        "encrypted_rpc_messaging": true,
        "flavor": {
            "id": "d2"
        },
        "guest_status": {
            "state_description": "healthy"
        },
        "id": "7de1bed8-6983-4d46-9a52-0abfbb0d27a2",
        "ip": [
            "10.1.0.62",
            "172.24.5.114"
        ],
        "links": [
            {
                "href": "https://127.0.0.1:8779/v1.0/2afa58fd5db34fd8b7b659d997a5341f/instances/7de1bed8-6983-4d46-9a52-0abfbb0d27a2",
                "rel": "self"
            },
            {
                "href": "https://127.0.0.1:8779/instances/7de1bed8-6983-4d46-9a52-0abfbb0d27a2",
                "rel": "bookmark"
            }
        ],
        "name": "test",
        "operating_status": "HEALTHY",
        "region": "RegionOne",
        "server": {
            "addresses": {
                "private": [
                    {
                        "OS-EXT-IPS-MAC:mac_addr": "fa:16:3e:fc:eb:4a",
                        "OS-EXT-IPS:type": "fixed",
                        "addr": "10.1.0.62",
                        "version": 4
                    },
                    {
                        "OS-EXT-IPS-MAC:mac_addr": "fa:16:3e:fc:eb:4a",
                        "OS-EXT-IPS:type": "floating",
                        "addr": "172.24.5.114",
                        "version": 4
                    }
                ],
                "trove-mgmt": [
                    {
                        "OS-EXT-IPS-MAC:mac_addr": "fa:16:3e:f9:0f:6a",
                        "OS-EXT-IPS:type": "fixed",
                        "addr": "192.168.254.125",
                        "version": 4
                    }
                ]
            },
            "host": "bdfe3275004d2a98d38d494fd7adfcd0c6d5d5198e86fa0d6ec5d588",
            "id": "710a84e5-6adf-4a4c-9167-8bade67a5a1c",
            "name": "test",
            "status": "ACTIVE",
            "tenant_id": "27ac4b83e9d045eb8c373bacaa994eb7"
        },
        "server_id": "710a84e5-6adf-4a4c-9167-8bade67a5a1c",
        "service_status": "HEALTHY",
        "service_status_updated": "2019-12-24T00:08:55",
        "status": "ACTIVE",
        "task_description": "No tasks for the instance.",
        "tenant_id": "9f8dd5eacb074c9f87d2d822c9092aa5",
        "updated": "2019-12-23T23:53:46",
        "volume": {
            "attachments": [
                {
                    "attached_at": "2019-12-23T23:11:39.000000",
                    "attachment_id": "a31526ba-884a-4e1f-8c64-4dc4b987ba4e",
                    "device": "/dev/vdb",
                    "host_name": "node.trove.magnum-pg0.utah.cloudlab.us",
                    "id": "ccb62e29-73ea-4859-b206-3b3a4e30a991",
                    "server_id": "710a84e5-6adf-4a4c-9167-8bade67a5a1c",
                    "volume_id": "ccb62e29-73ea-4859-b206-3b3a4e30a991"
                }
            ],
            "availability_zone": "nova",
            "created_at": "2019-12-23T20:58:39.000000",
            "id": "ccb62e29-73ea-4859-b206-3b3a4e30a991",
            "size": 1,
            "status": "in-use",
            "total": 0.95,
            "used": 0.12
        },
        "volume_id": "ccb62e29-73ea-4859-b206-3b3a4e30a991"
    }
}
PUT
/v1.0/{project_id}/instances/{instanceId}

Attach/Detach configuration group

Attach or detach a configuration group for an instance. When you pass in only an instance ID and omit the configuration ID, this operation detaches any configuration group that was attached to the instance.

Normal response codes: 202

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

instanceId

path

string

The ID of the database instance.

configuration

body

string

ID of the configuration group that you want to attach to the instance.

Request Example

{
    "instance": {
        "configuration": "2aa51628-5c42-4086-8682-137caffd2ba6"
    }
}
PUT
/v1.0/{project_id}/instances/{instanceId}

Update instance name

Update the instance name.

Normal response codes: 202

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

instanceId

path

string

The ID of the database instance.

instance

body

object

An instance object.

name (Optional)

body

string

Name of the instance.

Request Example

{
    "instance": {
        "name": "sample_instance"
    }
}
PUT
/v1.0/{project_id}/instances/{instanceId}

Upgrade datastore version for instance

Upgrade datastore version.

During datastore version upgrading, the instance status change to UPGRADE, and changes back to HEALTHY after upgrading finishes, otherwize changes to ERROR if the upgrading fails.

Normal response codes: 202

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

instanceId

path

string

The ID of the database instance.

instance

body

object

An instance object.

datastore_version (Optional)

body

string

Name of the datastore version to use when creating/updating the instance.

Request Example

{
    "instance": {
        "datastore_version": "sample_datastore_version"
    }
}
PUT
/v1.0/{project_id}/instances/{instanceId}

Detach replica

Detaches a replica from its replication source.

If you created an instance that is a replica of a source instance, you can detach the replica from the source later on. This can be useful if the source becomes unavailable. In this case, you can detach the replica from the source, making the replica a standalone database instance. You can then take the new standalone instance and create a new replica of that instance.

Normal response codes: 202

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

instanceId

path

string

The ID of the database instance.

instance

body

object

An instance object.

replica_of

body

string

ID or name of an existing instance to replicate from.

slave_of (Optional)

body

string

To detach a replica, set slave_of to null. Deprecated in favor of replica_of

Request Example

{
    "instance": {
        "replica_of": null
    }
}
PUT
/v1.0/{project_id}/instances/{instanceId}

Update instance accessbility

The following operations are supported:

  • If the instance should be exposed to public or not. Not providing is_public means private.

  • The list of CIDRs that are allowed to access the database service. Not providing allowed_cidrs means allowing everything.

Normal response codes: 202

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

instanceId

path

string

The ID of the database instance.

instance

body

object

An instance object.

access (Optional)

body

object

A access object defines how the database service is exposed.

access.is_public (Optional)

body

boolean

Whether the database service is exposed to the public.

access.allowed_cidrs (Optional)

body

array

A list of IPv4, IPv6 or mix of both CIDRs that restrict access to the database service. 0.0.0.0/0 is used by default if this parameter is not provided.

Request Example

{
    "instance": {
        "access": {
            "is_public": true,
            "allowed_cidrs": ["10.0.0.0/24"]
        }
    }
}
DELETE
/v1.0/{project_id}/instances/{instanceId}

Delete database instance

Deletes a database instance.

This operation does not delete any slaves.

Normal response codes: 202

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

instanceId

path

string

The ID of the database instance.

GET
/v1.0/{project_id}/instances/{instanceId}/backups

List backups of database instance

Get all the backups for an instance.

Normal response codes: 200

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

instanceId

path

string

The ID of the database instance.

Response Example

{
    "backups": [
        {
            "created": "2019-12-23T22:38:42",
            "datastore": {
                "type": "mysql",
                "version": "5.7",
                "version_id": "b3d5c099-dbd5-4518-baa3-7c7c195671bf"
            },
            "description": null,
            "id": "71557643-2245-43ac-b871-3d5a50af21d3",
            "instance_id": "7de1bed8-6983-4d46-9a52-0abfbb0d27a2",
            "locationRef": "http://127.0.0.1:8080/v1/AUTH_9f8dd5eacb074c9f87d2d822c9092aa5/database_backups/71557643-2245-43ac-b871-3d5a50af21d3.xbstream.gz.enc",
            "name": "backup-full",
            "parent_id": null,
            "size": 0.12,
            "status": "COMPLETED",
            "updated": "2019-12-23T22:38:45"
        }
    ]
}
GET
/v1.0/{project_id}/instances/{instanceId}/configuration

List default configuration parameters of database instance

Get the default configuration parameters for an instance.

Normal response codes: 200

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

instanceId

path

string

The ID of the database instance.

Response Example

{
    "instance": {
        "configuration": {
            "basedir": "/usr",
            "connect_timeout": 15,
            "datadir": "/var/lib/mysql/data",
            "default_storage_engine": "innodb",
            "innodb_buffer_pool_size": "2401M",
            "innodb_data_file_path": "ibdata1:10M:autoextend",
            "innodb_file_per_table": 1,
            "innodb_log_buffer_size": "25M",
            "innodb_log_file_size": "50M",
            "innodb_log_files_in_group": 2,
            "join_buffer_size": "1M",
            "key_buffer_size": "800M",
            "local-infile": 0,
            "max_allowed_packet": "16392K",
            "max_connections": 1600,
            "max_heap_table_size": "256M",
            "max_user_connections": 1600,
            "myisam-recover-options": "BACKUP,FORCE",
            "open_files_limit": 8196,
            "performance_schema": "ON",
            "pid-file": "/var/run/mysqld/mysqld.pid",
            "port": 3306,
            "query_cache_limit": "1M",
            "query_cache_size": "128M",
            "query_cache_type": 1,
            "read_buffer_size": "512K",
            "read_rnd_buffer_size": "512K",
            "server_id": 1468542390,
            "skip-external-locking": 1,
            "socket": "/var/run/mysqld/mysqld.sock",
            "sort_buffer_size": "1M",
            "table_definition_cache": 4098,
            "table_open_cache": 4098,
            "thread_cache_size": 64,
            "thread_stack": "192K",
            "tmp_table_size": "256M",
            "tmpdir": "/var/tmp",
            "user": "mysql",
            "wait_timeout": 120
        }
    }
}

Instance actions

POST
/v1.0/{project_id}/instances/{instanceId}/action

Restart instance

Restarts the database service for an instance.

The restart operation restarts only the database instance. Restarting the database erases any dynamic configuration settings that you make in the database instance.

The database service is unavailable until the instance restart finishes.

Normal response codes: 202

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

instanceId

path

string

The ID of the database instance.

Request Example

{
    "restart": {}
}
POST
/v1.0/{project_id}/instances/{instanceId}/action

Resize instance flavor

Resizes the (Nova)flavor for an instance.

If you provide a valid flavorRef, this operation changes the memory size of the instance, and restarts the database.

Normal response codes: 202

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

instanceId

path

string

The ID of the database instance.

flavorRef

body

string

Reference (href), which is the actual URI to a flavor as it appears in the list flavors response. Rather than the flavor URI, you can also pass the flavor ID (integer) as the flavorRef value. For example, 1.

Request Example

{
    "resize": {
        "flavorRef": "2"
    }
}
POST
/v1.0/{project_id}/instances/{instanceId}/action

Resize instance volume

Resizes the volume that is attached to an instance.

You can use this operation to increase but not decrease the volume size. A valid volume size is an integer value in gigabytes (GB).

You cannot increase the volume to a size that is larger than the API volume size limit.

For replication cluster, resizing volume of the primary will also resize replicas automatically.

Normal response codes: 202

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

instanceId

path

string

The ID of the database instance.

volume (Optional)

body

object

A volume object.

Request Example

{
    "resize": {
        "volume": {
            "size": 4
        }
    }
}
POST
/v1.0/{project_id}/instances/{instanceId}/action

Promote instance to replica master

Promotes a replica.

If you have set up replication, and the master instance is still reachable, you can use this operation to promote a replica to be the new master instance.

This can be useful if you want to make a configuration change or maintenance to the master instance. If you made the change on the master instance directly, you would need to take the master instance down for the duration of the operation. Instead, you can create a replica, make the configuration change on the replica, and then promote the replica to become the new master instance.

Once this command is executed, the status of all the instances will be set to PROMOTE and Trove will work its magic until all of them to come back to HEALTHY.

The instanceId is the instance ID of the replica you want to promote.

Normal response codes: 202

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

instanceId

path

string

The ID of the database instance.

Request Example

{
    "promote_to_replica_source": {}
}
POST
/v1.0/{project_id}/instances/{instanceId}/action

Eject the master instance

Remove the master instance in a replication set.

This should be only done in a failed master scenario. This command ejects the current master and then forces a re-election for the new master. The new master is effectively the one with the most current replica of the old master.

Once this command is executed, the status of all the instances will be set to EJECT and Trove will work its magic until all of them to come back to HEALTHY.

The instanceId is the ID of the current unavailable master instance.

Normal response codes: 202

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

instanceId

path

string

The ID of the database instance.

Request Example

{
    "eject_replica_source": {}
}
POST
/v1.0/{project_id}/instances/{instanceId}/action

Reset instance status

Set instance service status to ERROR and clear the current task status. Mark any running backup operations as FAILED.

Normal response codes: 202

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

instanceId

path

string

The ID of the database instance.

Request Example

{
    "reset_status": {}
}
POST
/v1.0/{project_id}/mgmt/instances/{instanceId}/action

Stop database service

Admin only API. Stop database service inside an instance.

Normal response codes: 202

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

instanceId

path

string

The ID of the database instance.

Request Example

{
    "stop": {}
}
POST
/v1.0/{project_id}/mgmt/instances/{instanceId}/action

Reboot instance

Admin only API. Reboot the database instance, database service will be stopped before rebooting.

Normal response codes: 202

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

instanceId

path

string

The ID of the database instance.

Request Example

{
    "reboot": {}
}
POST
/v1.0/{project_id}/mgmt/instances/{instanceId}/action

Cold Migrate instance

Admin only API. Migrate(resize) the database instance, database service will be stopped before migrating.

Normal response codes: 202

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

instanceId

path

string

The ID of the database instance.

Request Example

{
    "migrate": {
        "host": "compute-001"
    }
}
POST
/v1.0/{project_id}/mgmt/instances/{instanceId}/action

Reset instance task status

Admin only API. Reset task status of an instance, mark any running backup operations as FAILED.

Normal response codes: 202

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

instanceId

path

string

The ID of the database instance.

Request Example

{
    "reset-task-status": {}
}
POST
/v1.0/{project_id}/mgmt/instances/{instanceId}/action

Rebuild instance

Admin only API. Rebuild the Nova server’s operating system for the database instance. The rebuild operation is mainly for Trove upgrade, especially when the interface between Trove controller and guest agent changes. After Trove controller is upgraded, the cloud administrator needs to send rebuild request with the new guest image ID. Communication with the end users is needed as the database service goes offline during the process. User’s data in the database is not affected.

Normal response codes: 202

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

instanceId

path

string

The ID of the database instance.

Request Example

{
  "rebuild": {
      "image_id": "3e50414a-8532-4646-982c-a66fe8f0411b"
  }
}

Instance logs

GET
/v1.0/{project_id}/instances/{instanceId}/log

List instance logs

Listing all logs for an instance.

Different datastore backend has its own guest_log_exposed_logs configuration to determine which type of logs will be listed by default. Admin user can get all the logs.

Normal response codes: 200

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

instanceId

path

string

The ID of the database instance.

Response Parameters

Name

In

Type

Description

logs

body

array

A list of log objects.

name

body

string

The name of the log.

type

body

string

The type of the log.

status

body

string

The log status.

published

body

string

Published size of the log.

pending

body

string

Log file size pending to be published.

container

body

string

The object store container where the published log data will be stored. Defaults to None before the log has been published.

prefix

body

string

If the log has been published, thi is the prefix location of where the log data are stored. Otherwize the prefix is None.

metafile

body

string

The log metafile location.

Response Example

{
    "logs": [
        {
            "name": "general",
            "type": "USER",
            "status": "Partial",
            "published": "128",
            "pending": "4096",
            "container": "data_logs",
            "prefix": "5e9e616c-1827-45f5-a487-679084d82f7e/mysql-general/",
            "metafile": "5e9e616c-1827-45f5-a487-679084d82f7e/mysql-general_metafile"
        },
        {
            "name": "slow_query",
            "type": "USER",
            "status": "Ready",
            "published": "0",
            "pending": "128",
            "container": "None",
            "prefix": "None",
            "metafile": "5e9e616c-1827-45f5-a487-679084d82f7e/mysql-slow_query_metafile"
        }
    ]
}
POST
/v1.0/{project_id}/instances/{instanceId}/log

Show instance log details

Show details for a instance log.

Normal response codes: 200

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

instanceId

path

string

The ID of the database instance.

name

body

string

The name of the log.

Request Example

{
    "name": "general"
}

Response Parameters

Name

In

Type

Description

log

body

array

A log objects.

name

body

string

The name of the log.

type

body

string

The type of the log.

status

body

string

The log status.

published

body

string

Published size of the log.

pending

body

string

Log file size pending to be published.

container

body

string

The object store container where the published log data will be stored. Defaults to None before the log has been published.

prefix

body

string

If the log has been published, thi is the prefix location of where the log data are stored. Otherwize the prefix is None.

metafile

body

string

The log metafile location.

Response Example

{
    "log": {
        "name": "general",
        "type": "USER",
        "status": "Partial",
        "published": "128",
        "pending": "4096",
        "container": "data_logs",
        "prefix": "5e9e616c-1827-45f5-a487-679084d82f7e/mysql-general/",
        "metafile": "5e9e616c-1827-45f5-a487-679084d82f7e/mysql-general_metafile"
    }
}
POST
/v1.0/{project_id}/instances/{instanceId}/log

Enable instance log

Enable a log type for a instance.

Normal response codes: 200

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

instanceId

path

string

The ID of the database instance.

name

body

string

The name of the log.

enable (Optional)

body

integer

To enable a log type, this should always set to 1.

Request Example

{
    "name": "general",
    "enable": 1
}

Response Parameters

Name

In

Type

Description

log

body

array

A log objects.

name

body

string

The name of the log.

type

body

string

The type of the log.

status

body

string

The log status.

published

body

string

Published size of the log.

pending

body

string

Log file size pending to be published.

container

body

string

The object store container where the published log data will be stored. Defaults to None before the log has been published.

prefix

body

string

If the log has been published, thi is the prefix location of where the log data are stored. Otherwize the prefix is None.

metafile

body

string

The log metafile location.

Response Example

{
    "log": {
        "name": "general",
        "type": "USER",
        "status": "Eanbled",
        "published": "0",
        "pending": "0",
        "container": "None",
        "prefix": "None",
        "metafile": "5e9e616c-1827-45f5-a487-679084d82f7e/mysql-general_metafile"
    }
}
POST
/v1.0/{project_id}/instances/{instanceId}/log

Disable instance log

Disable a log type for a instance.

Normal response codes: 200

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

instanceId

path

string

The ID of the database instance.

name

body

string

The name of the log.

disable (Optional)

body

integer

To disable a log type, this should always set to 1.

Request Example

{
    "name": "general",
    "disable": 1
}

Response Parameters

Name

In

Type

Description

log

body

array

A log objects.

name

body

string

The name of the log.

type

body

string

The type of the log.

status

body

string

The log status.

published

body

string

Published size of the log.

pending

body

string

Log file size pending to be published.

container

body

string

The object store container where the published log data will be stored. Defaults to None before the log has been published.

prefix

body

string

If the log has been published, thi is the prefix location of where the log data are stored. Otherwize the prefix is None.

metafile

body

string

The log metafile location.

Response Example

{
    "log": {
        "name": "general",
        "type": "USER",
        "status": "Disabled",
        "published": "4096",
        "pending": "0",
        "container": "data_logs",
        "prefix": "5e9e616c-1827-45f5-a487-679084d82f7e/mysql-general/",
        "metafile": "5e9e616c-1827-45f5-a487-679084d82f7e/mysql-general_metafile"
    }
}
POST
/v1.0/{project_id}/instances/{instanceId}/log

Publish instance log

Publish a log type for a instance.

Publish`` will automatically enable a log.

Normal response codes: 200

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

instanceId

path

string

The ID of the database instance.

name

body

string

The name of the log.

publish (Optional)

body

integer

To publish a log type, this should always set to 1.

Request Example

{
    "name": "general",
    "publish": 1
}

Response Parameters

Name

In

Type

Description

log

body

array

A log objects.

name

body

string

The name of the log.

type

body

string

The type of the log.

status

body

string

The log status.

published

body

string

Published size of the log.

pending

body

string

Log file size pending to be published.

container

body

string

The object store container where the published log data will be stored. Defaults to None before the log has been published.

prefix

body

string

If the log has been published, thi is the prefix location of where the log data are stored. Otherwize the prefix is None.

metafile

body

string

The log metafile location.

Response Example

{
    "log": {
        "name": "general",
        "type": "USER",
        "status": "Published",
        "published": "128",
        "pending": "0",
        "container": "data_logs",
        "prefix": "5e9e616c-1827-45f5-a487-679084d82f7e/mysql-general/",
        "metafile": "5e9e616c-1827-45f5-a487-679084d82f7e/mysql-general_metafile"
    }
}
POST
/v1.0/{project_id}/instances/{instanceId}/log

Discard instance log

Discard all previously published logs for a instance.

Normal response codes: 200

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

instanceId

path

string

The ID of the database instance.

name

body

string

The name of the log.

discard (Optional)

body

integer

To discard a log type which has been published previously, this should always set to 1.

Request Example

{
    "name": "general",
    "discard": 1
}

Response Parameters

Name

In

Type

Description

log

body

array

A log objects.

name

body

string

The name of the log.

type

body

string

The type of the log.

status

body

string

The log status.

published

body

string

Published size of the log.

pending

body

string

Log file size pending to be published.

container

body

string

The object store container where the published log data will be stored. Defaults to None before the log has been published.

prefix

body

string

If the log has been published, thi is the prefix location of where the log data are stored. Otherwize the prefix is None.

metafile

body

string

The log metafile location.

Response Example

{
    "log": {
        "name": "general",
        "type": "USER",
        "status": "Ready",
        "published": "0",
        "pending": "128",
        "container": "None",
        "prefix": "None",
        "metafile": "5e9e616c-1827-45f5-a487-679084d82f7e/mysql-general_metafile"
    }
}

Backups

GET
/v1.0/{project_id}/backups

List database backups

List all database backups information for a project. You can filter results by using query string parameters. The following filters are supported:

  • instance_id={instance_id} - Return the list of backups for a particular database instance.

  • all_projects=True/False - Return the list of backups for all the projects, this is an admin only param by default.

  • datastore={datastore} - Return a list of backups of the same datastore.

  • project_id={project_id} - Get backups of a specific project. Admin required.

Normal response codes: 200

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

Response Parameters

Name

In

Type

Description

backups

body

array

A list of backup objects.

created

body

string

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

datastore

body

object

A datastore object.

datastore.type

body

string

The type of a datastore.

datastore.version

body

string

The name of the datastore version. Different datastore versions can have the same name.

datastore.version_id

body

string

The UUID of the data store version.

description

body

string

An optional description for the backup.

id

path

string

The ID of the backup.

instance_id (Optional)

body

string

The ID of the instance to create backup for.

locationRef

body

string

The URL of the backup location.

name

body

string

Name of the backup.

parent_id

body

string

ID of the parent backup to perform an incremental backup from.

size

body

string

Size of the backup, the unit is GB.

status

body

string

Status of the backup.

updated

body

string

The date and time when the resource was updated.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, is the time zone as an offset from UTC.

For example, 2015-08-27T09:49:58-05:00.

The UTC time zone is assumed.

project_id

body

string

The project ID of the resource.

Response Example

{
    "backups": [
        {
            "created": "2014-10-30T12:30:00",
            "datastore": {
                "type": "mysql",
                "version": "5.5",
                "version_id": "b00000b0-00b0-0b00-00b0-000b000000bb"
            },
            "description": "My Backup",
            "id": "a9832168-7541-4536-b8d9-a8a9b79cf1b4",
            "instance_id": "44b277eb-39be-4921-be31-3d61b43651d7",
            "locationRef": "http://localhost/path/to/backup",
            "name": "snapshot",
            "parent_id": null,
            "size": 0.14,
            "status": "COMPLETED",
            "updated": "2014-10-30T12:30:00"
        },
        {
            "created": "2014-10-30T12:30:00",
            "datastore": {
                "type": "mysql",
                "version": "5.5",
                "version_id": "b00000b0-00b0-0b00-00b0-000b000000bb"
            },
            "description": "My Incremental Backup",
            "id": "2e351a71-dd28-4bcb-a7d6-d36a5b487173",
            "instance_id": "44b277eb-39be-4921-be31-3d61b43651d7",
            "locationRef": "http://localhost/path/to/backup",
            "name": "Incremental Snapshot",
            "parent_id": "a9832168-7541-4536-b8d9-a8a9b79cf1b4",
            "size": 0.14,
            "status": "COMPLETED",
            "updated": "2014-10-30T12:30:00"
        }
    ]
}
POST
/v1.0/{project_id}/backups

Create database backup

Creates a database backup for instance.

In the Trove deployment with service tenant enabled, The backup data is stored as objects in OpenStack Swift service in the user’s container. If not specified, the container name is defined by the cloud admin.

The user can create a backup strategy within the project scope or specific to a particular instance.

In multi-region deployment with geo-replicated Swift, the user can also restore a backup in a region by manually specifying the backup data location created in another region, then create instances from the backup. Instance ID is not required in this case.

Warning

The restored backup is dependent on the original backup data, if the original backup is deleted, the restored backup is invalid.

Normal response codes: 202

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

name

body

string

Name of the backup.

instance (Optional)

body

string

The ID of the instance to create backup for.

parent_id (Optional)

body

string

ID of the parent backup to perform an incremental backup from.

incremental (Optional)

body

integer

Create an incremental backup based on the last full backup by setting this parameter to 1 or 0. It will create a full backup if no existing backup found.

description (Optional)

body

string

An optional description for the backup.

swift_container (Optional)

body

string

User defined swift container name. When creating backups, the swift container is created automatically if does not exist.

restore_from (Optional)

body

object

The information needed to restore a backup, including:

  • remote_location: The original backup data location.

  • local_datastore_version_id: The local datastore version corresponding to the original backup.

  • size: The original backup size.

Request Example

{
    "backup": {
        "description": "My Backup",
        "incremental": 0,
        "instance": "44b277eb-39be-4921-be31-3d61b43651d7",
        "name": "snapshot"
    }
}

Response Parameters

Name

In

Type

Description

created

body

string

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

datastore

body

object

A datastore object.

datastore.type

body

string

The type of a datastore.

datastore.version

body

string

The name of the datastore version. Different datastore versions can have the same name.

datastore.version_id

body

string

The UUID of the data store version.

description

body

string

An optional description for the backup.

id

path

string

The ID of the backup.

instance_id (Optional)

body

string

The ID of the instance to create backup for.

locationRef

body

string

The URL of the backup location.

name

body

string

Name of the backup.

parent_id

body

string

ID of the parent backup to perform an incremental backup from.

size

body

string

Size of the backup, the unit is GB.

status

body

string

Status of the backup.

updated

body

string

The date and time when the resource was updated.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, is the time zone as an offset from UTC.

For example, 2015-08-27T09:49:58-05:00.

The UTC time zone is assumed.

project_id

body

string

The project ID of the resource.

Response Example

{
    "backup": {
        "created": "2014-10-30T12:30:00",
        "datastore": {
            "type": "mysql",
            "version": "5.5",
            "version_id": "b00000b0-00b0-0b00-00b0-000b000000bb"
        },
        "description": "My Backup",
        "id": "a9832168-7541-4536-b8d9-a8a9b79cf1b4",
        "instance_id": "44b277eb-39be-4921-be31-3d61b43651d7",
        "locationRef": null,
        "name": "snapshot",
        "parent_id": null,
        "size": null,
        "status": "NEW",
        "updated": "2014-10-30T12:30:00"
    }
}
GET
/v1.0/{project_id}/backups/{backupId}

Show database backup details

Show detailes of a backup.

Normal response codes: 200

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

backupId

path

string

The ID of the backup.

Response Parameters

Name

In

Type

Description

created

body

string

The date and time when the resource was created.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

For example, 2015-08-27T09:49:58-05:00.

The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00.

datastore

body

object

A datastore object.

datastore.type

body

string

The type of a datastore.

datastore.version

body

string

The name of the datastore version. Different datastore versions can have the same name.

datastore.version_id

body

string

The UUID of the data store version.

description

body

string

An optional description for the backup.

id

path

string

The ID of the backup.

instance_id (Optional)

body

string

The ID of the instance to create backup for.

locationRef

body

string

The URL of the backup location.

name

body

string

Name of the backup.

parent_id

body

string

ID of the parent backup to perform an incremental backup from.

size

body

string

Size of the backup, the unit is GB.

status

body

string

Status of the backup.

updated

body

string

The date and time when the resource was updated.

The date and time stamp format is ISO 8601:

CCYY-MM-DDThh:mm:ss±hh:mm

The ±hh:mm value, if included, is the time zone as an offset from UTC.

For example, 2015-08-27T09:49:58-05:00.

The UTC time zone is assumed.

project_id

body

string

The project ID of the resource.

Response Example

{
    "backup": {
        "created": "2014-10-30T12:30:00",
        "datastore": {
            "type": "mysql",
            "version": "5.5",
            "version_id": "b00000b0-00b0-0b00-00b0-000b000000bb"
        },
        "description": "My Backup",
        "id": "a9832168-7541-4536-b8d9-a8a9b79cf1b4",
        "instance_id": "44b277eb-39be-4921-be31-3d61b43651d7",
        "locationRef": "http://localhost/path/to/backup",
        "name": "snapshot",
        "parent_id": null,
        "size": 0.14,
        "status": "COMPLETED",
        "updated": "2014-10-30T12:30:00"
    }
}
DELETE
/v1.0/{project_id}/backups/{backupId}

Delete database backup

Deletes a database backup. All the child backups are deleted automatically when a parent backup is deleted.

Normal response codes: 202

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

backupId

path

string

The ID of the backup.

Backup Strategy

Backup strategy allows the user to customize the way of creating backups. Users can create strategy either in the project scope or for a particular database instance.

GET
/v1.0/{project_id}/backup_strategies

List backup strategies

List backup strategies for a project. You can filter the results by using query string parameters. The following filters are supported:

  • instance_id={instance_id} - Return the list of backup strategies for a particular database instance.

  • project_id={project_id} - Return the list of backup strategies for a particular project, admin only.

Normal response codes: 200

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

Response Parameters

Name

In

Type

Description

backup_strategies

body

array

A list of backup_strategy objects.

project_id

path

string

The project ID of the instance owner.

instance_id

body

string

The ID of the database instance.

backend

body

string

The storage backend of instance backups, currently only swift is supported.

swift_container

body

string

User defined swift container name.

Response Example

{
    "backup_strategies": [
        {
            "backend": "swift",
            "instance_id": "0602db72-c63d-11ea-b87c-00224d6b7bc1",
            "project_id": "922b47766bcb448f83a760358337f2b4",
            "swift_container": "my_trove_backups"
        }
    ]
}
POST
/v1.0/{project_id}/backup_strategies

Create backup strategy

Creates or updates backup strategy for the project or a database instance.

Normal response codes: 202

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

instance_id (Optional)

body

string

The ID of the database instance.

swift_container

body

string

User defined swift container name.

Request Example

{
  "backup_strategy": {
    "instance_id": "0602db72-c63d-11ea-b87c-00224d6b7bc1",
    "swift_container": "my_trove_backups"
  }
}

Response Parameters

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

instance_id

body

string

The ID of the database instance.

backend

body

string

The storage backend of instance backups, currently only swift is supported.

swift_container

body

string

User defined swift container name.

Response Example

{
    "backup_strategy": {
        "project_id": "922b47766bcb448f83a760358337f2b4",
        "instance_id": "0602db72-c63d-11ea-b87c-00224d6b7bc1",
        "backend": "swift",
        "swift_container": "my_trove_backups"
    }
}
DELETE
/v1.0/{project_id}/backup_strategies

Delete database strategy

Deletes a database strategy for a project. If instance_id is specified in the URL query parameters, delete the database strategy for that particular database instance. Additionally, admin user is allowed to delete backup strategy of other projects by specifying project_id in the URL query parameters.

Normal response codes: 202

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

Configuration groups

GET
/v1.0/{project_id}/configurations

List configuration groups

Lists all configuration groups.

Normal response codes: 200

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

Response Example

{
    "configurations": [
        {
            "updated": "2015-07-01T16:38:27",
            "datastore_version_id": "2dc7faa0-efff-4c2b-8cff-bcd949c518a5",
            "datastore_name": "mysql",
            "datastore_version_name": "mysql-5.7",
            "datastore_version_number": "5.7.29",
            "name": "group1",
            "created": "2015-07-01T16:38:27",
            "id": "2aa51628-5c42-4086-8682-137caffd2ba6",
            "description": null
        }
    ]
}
POST
/v1.0/{project_id}/configurations

Create configuration group

Creates a configuration group.

Normal response codes: 200

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

datastore

body

string

Data store type and version assigned to the configuration group. Required if the default data store is not configured.

name

body

string

Name of the configuration group you are creating.

values

body

string

Dictionary that lists configuration parameter names and associated values.

Request Example

{
    "configuration": {
        "name": "group1",
        "datastore": {
            "type": "mysql",
            "version": "mysql-5.7",
            "version_number": "5.7.29"
        },
        "values": {
            "connect_timeout": 200
        }
    }
}

Response Example

{
    "configuration": {
        "created": "2020-06-16T10:40:50",
        "updated": "2020-06-16T10:40:50",
        "datastore_name": "mysql",
        "datastore_version_id": "cf91aa9a-2192-4ec4-b7ce-5cac3b1e7dbe",
        "datastore_version_name": "mysql-5.7",
        "datastore_version_number": "5.7.29",
        "description": null,
        "id": "9dcfca0b-d181-4b36-bbf0-09bc47b103ab",
        "instance_count": 0,
        "name": "group1",
        "values": {
            "connect_timeout": 200
        }
    }
}
GET
/v1.0/{project_id}/configurations/{configId}

Show configuration group details

Lists details about a configuration group, including its values.

Normal response codes: 200

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

configId (Optional)

path

string

The ID of the configuration group.

Response Example

{
    "configuration": {
        "datastore_name": "mysql",
        "datastore_version_id": "b9f97132-467b-4f8e-b12d-947cfc223ac3",
        "datastore_version_name": "mysql-5.7",
        "datastore_version_number": "5.7.29",
        "updated": "2015-11-22T19:07:20",
        "values": {
            "connect_timeout": 17
        },
        "name": "group1",
        "created": "2015-11-20T20:51:24",
        "instance_count": 1,
        "id": "1c8a4fdd-690c-4e6e-b2e1-148b8d738770",
        "description": null
    }
}
GET
/v1.0/{project_id}/configurations/{configId}/instances

List instances applied the configuration group

Lists the instances associated with the specified configuration group.

Normal response codes: 200

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

configId (Optional)

path

string

The ID of the configuration group.

Response Example

{
    "instances": [
        {
            "id": "7fd2d1d6-a2ef-4a76-8c03-e233db4d86da",
            "name": "master_1"
        }
    ]
}
PATCH
/v1.0/{project_id}/configurations/{configId}

Patch configuration group

Sets new values for a configuration group.

Normal response codes: 200

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

configId (Optional)

path

string

The ID of the configuration group.

values

body

string

Dictionary that lists configuration parameter names and associated values.

Request Example

{
    "configuration": {
        "values": {
            "connect_timeout": 17
        }
    }
}
PUT
/v1.0/{project_id}/configurations/{configId}

Update configuration group

Sets new values for a configuration group. Also lets you change the name and description of the configuration group.

Normal response codes: 202

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

configId (Optional)

path

string

The ID of the configuration group.

values

body

string

Dictionary that lists configuration parameter names and associated values.

description

body

string

New description of the configuration group.

name

body

string

Name of the configuration group you are creating.

Request Example

{
    "configuration": {
        "values": {
            "connect_timeout": 18
        },
        "name": "new_name",
        "description": "New description"
    }
}
DELETE
/v1.0/{project_id}/configurations/{configId}

Delete configuration group

Deletes a configuration group.

Normal response codes: 202

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

configId (Optional)

path

string

The ID of the configuration group.

Databases

Currently, the Database and User API is only supported by mysql datastore. For others, the recommended way is to get root password (POST /v1.0/{project_id}/instances/{instance_id}/root) and communicate with the database service directly for database and user management.

POST
/v1.0/{project_id}/instances/{instanceId}/databases

Create database

Creates a database within an instance.

Normal response codes: 202

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

instanceId

path

string

The ID of the database instance.

name

body

string

Name of the configuration group you are creating.

characterSet (Optional)

body

string

A set of symbols and encodings. Default is utf8. For information about supported character sets and collations, see Character Sets and Collations in MySQL.

collate (Optional)

body

string

A set of rules for comparing characters in a character set. Default is utf8_general_ci. For information about supported character sets and collations, see Character Sets and Collations in MySQL.

Request Example

{
    "databases": [
        {
            "character_set": "utf8mb3",
            "collate": "utf8mb3_general_ci",
            "name": "databaseA"
        },
        {
            "name": "databaseB"
        },
        {
            "name": "databaseC"
        }
    ]
}
GET
/v1.0/{project_id}/instances/{instanceId}/databases

List instance databases

Lists databases for an instance.

This operation returns only the user-defined databases and not the system databases. Only the database administrator can get system databases such as mysql, information_schema, and lost+found.

Normal response codes: 200

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

instanceId

path

string

The ID of the database instance.

Response Example

{
    "databases": [
        {
            "name": "databaseB"
        },
        {
            "name": "databaseC"
        },
        {
            "name": "databaseD"
        }
    ]
}
GET
/v1.0/{project_id}/instances/{instanceId}/users/{user_name}/databases

List instance databases for a user

Get all the databases that the user has access to.

Normal response codes: 200

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

instanceId

path

string

The ID of the database instance.

user_name (Optional)

path

string

The name of the user.

Response Example

{
    "databases": [
        {
            "name": "databaseB"
        },
        {
            "name": "databaseC"
        },
        {
            "name": "databaseD"
        }
    ]
}
PUT
/v1.0/{project_id}/instances/{instanceId}/users/{user_name}/databases

Grant databases access

Grant user access to the databases.

Normal response codes: 202

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

instanceId

path

string

The ID of the database instance.

user_name (Optional)

path

string

The name of the user.

Request Example

{
    "databases":[
        {
            "name": "test"
        }
    ]
}
DELETE
/v1.0/{project_id}/instances/{instanceId}/users/{user_name}/databases/{database_name}

Revoke databases access

Revoke user access to the database.

Normal response codes: 202

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

instanceId

path

string

The ID of the database instance.

user_name (Optional)

path

string

The name of the user.

database_name (Optional)

path

string

The name for the database.

DELETE
/v1.0/{project_id}/instances/{instanceId}/databases/{database_name}

Delete database

Deletes a database.

Normal response codes: 202

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

instanceId

path

string

The ID of the database instance.

database_name (Optional)

path

string

The name for the database.

Users

Currently, the Database and User API is only supported by mysql datastore. For others, the recommended way is to get root password (POST /v1.0/{project_id}/instances/{instance_id}/root) and communicate with the database service directly for database and user management.

POST
/v1.0/{project_id}/instances/{instanceId}/users

Create user

Creates users for a database instance.

When specifying user name and password, you can also specify databases that the user can access.

Normal response codes: 202

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

instanceId

path

string

The ID of the database instance.

Request Example

{
    "users": [
        {
            "databases": [
                {
                    "name": "databaseA"
                }
            ],
            "name": "dbuser1",
            "password": "password"
        },
        {
            "databases": [
                {
                    "name": "databaseB"
                },
                {
                    "name": "databaseC"
                }
            ],
            "name": "dbuser2",
            "password": "password"
        },
        {
            "name": "dbuser3",
            "password": "password"
        }
    ]
}
GET
/v1.0/{project_id}/instances/{instanceId}/users

List database instance users

Lists the users in a database instance and the associated databases for that user.

This operation does not return system users. A system user is a database administrator who administers the health of the database. Also, this operation returns the root user only if it is enabled.

Normal response codes: 200

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

instanceId

path

string

The ID of the database instance.

Response Example

{
    "users": [
        {
            "databases": [
                {
                    "name": "databaseA"
                }
            ],
            "host": "%",
            "name": "dbuser1"
        },
        {
            "databases": [
                {
                    "name": "databaseB"
                },
                {
                    "name": "databaseC"
                }
            ],
            "host": "%",
            "name": "dbuser2"
        },
        {
            "databases": [],
            "host": "%",
            "name": "dbuser3"
        }
    ]
}
GET
/v1.0/{project_id}/instances/{instanceId}/users/{user_name}

Show database instance user

Get a specific user information in an instance.

Normal response codes: 200

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

instanceId

path

string

The ID of the database instance.

user_name (Optional)

path

string

The name of the user.

Response Example

{
    "user": {
        "databases": [
            {
                "name": "databaseA"
            }
        ],
        "host": "%",
        "name": "dbuser1"
    }
}
DELETE
/v1.0/{project_id}/instances/{instanceId}/users/{user_name}

Delete user

Deletes a user for a database instance.

Normal response codes: 202

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

instanceId

path

string

The ID of the database instance.

user_name (Optional)

path

string

The name of the user.

PUT
/v1.0/{project_id}/instances/{instanceId}/users/{user_name}

Update a user

Modify attributes(e.g. user name, allowed host, password) for a specific user.

Normal response codes: 202

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

instanceId

path

string

The ID of the database instance.

user_name (Optional)

path

string

The name of the user.

Request Example

{
    "user": {
        "name": "new_name",
        "password": "new_password",
        "host": "192.168.30.98"
    }
}
PUT
/v1.0/{project_id}/instances/{instanceId}/users

Update users passwords

Modify passwords for users.

Normal response codes: 202

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

instanceId

path

string

The ID of the database instance.

Request Example

{
    "users": [
        {
            "name": "new_name",
            "password": "another_password",
            "host": "192.168.30.98"
        }
    ]
}
GET
/v1.0/{project_id}/instances/{instanceId}/root

Show root-enabled status for database instance

Shows root-enabled status for a database instance.

Returns true if root user is enabled for a database instance. Otherwise, returns false.

Normal response codes: 200

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

instanceId

path

string

The ID of the database instance.

Response Example

{
    "rootEnabled": true
}
POST
/v1.0/{project_id}/instances/{instanceId}/root

Enable root user

Enables the root user for a database instance and returns the root password.

This operation generates password for the root user if not provided and enables the root user to log in from any host. If provided, the user should guarantee the password complexity and change regularly.

Other than managing databases and users, root user can change database settings without touching Trove API which is not recommended.

Normal response codes: 200

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

instanceId

path

string

The ID of the database instance.

password (Optional)

body

string

The password of the database root user(i.e. the administrative user).

Request Example

{
  "password": "q5BXXMUMbc8XBf5kkVToKZW4Kx3Egv5VjY0P"
}

Response Example

{
    "user": {
        "name": "root",
        "password": "q5BXXMUMbc8XBf5kkVToKZW4Kx3Egv5VjY0P"
    }
}
DELETE
/v1.0/{project_id}/instances/{instanceId}/root

Disable root user

Disables the root user.

Normal response codes: 204

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

instanceId

path

string

The ID of the database instance.

GET
/v1.0/{project_id}/mgmt/instances/{instanceId}/root

Show root-enabled history for database instance

Admin only API. Show the date and time that root user was enabled(if ever) for an instance.

Normal response codes: 200

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

instanceId

path

string

The ID of the database instance.

Response Example

{
    "root_history": {
        "enabled": "2019-12-24T03:10:16",
        "id": "7de1bed8-6983-4d46-9a52-0abfbb0d27a2",
        "user": "7578487d3cc843dca904d2f4eced7dd2"
    }
}

Quotas

GET
/v1.0/{project_id}/limits

Show resources limit for current project

Get resources quota and rate limit for the current project.

Normal response codes: 200

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

Response Example

{
    "limits": [
        {
            "max_backups": 50,
            "max_instances": 10,
            "max_volumes": 40,
            "verb": "ABSOLUTE"
        },
        {
            "nextAvailable": "2019-12-23T22:38:41Z",
            "regex": ".*",
            "remaining": 199,
            "unit": "MINUTE",
            "uri": "*",
            "value": 200,
            "verb": "POST"
        },
        {
            "nextAvailable": "2019-12-24T02:49:24Z",
            "regex": ".*",
            "remaining": 199,
            "unit": "MINUTE",
            "uri": "*",
            "value": 200,
            "verb": "PUT"
        },
        {
            "nextAvailable": "2019-12-24T03:42:19Z",
            "regex": ".*",
            "remaining": 200,
            "unit": "MINUTE",
            "uri": "*",
            "value": 200,
            "verb": "DELETE"
        },
        {
            "nextAvailable": "2019-12-24T03:42:19Z",
            "regex": ".*",
            "remaining": 199,
            "unit": "MINUTE",
            "uri": "*",
            "value": 200,
            "verb": "GET"
        },
        {
            "nextAvailable": "2019-12-24T03:42:19Z",
            "regex": "^/mgmt",
            "remaining": 200,
            "unit": "MINUTE",
            "uri": "*/mgmt",
            "value": 200,
            "verb": "POST"
        }
    ]
}
GET
/v1.0/{project_id}/mgmt/quotas/{user_project}

Show resources quota for a specific project

Admin can query resource quota of any project. The project user can only show the project’s own quota.

Normal response codes: 200

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

user_project

path

string

The project ID of the user’s project.

Response Parameters

Name

In

Type

Description

quotas

body

array

A list of resource quotas.

resource

body

string

The resource name.

in_use

body

integer

The used quota for a resource.

limit

body

integer

The limit of a resource quota.

reserved

body

integer

The reserved quota for a resource.

Response Example

{
    "quotas": [
        {
            "in_use": 5,
            "limit": 15,
            "reserved": 0,
            "resource": "instances"
        },
        {
            "in_use": 2,
            "limit": 50,
            "reserved": 0,
            "resource": "backups"
        },
        {
            "in_use": 1,
            "limit": 40,
            "reserved": 0,
            "resource": "volumes"
        }
    ]
}
PUT
/v1.0/{project_id}/mgmt/quotas/{user_project}

Update resources quota for a specific project

Admin only action by default. Supported resources:

  • instances

  • backups

If not set, use the default resource quota in Trove configuration.

Normal response codes: 200

Request

Name

In

Type

Description

project_id

path

string

The project ID of the instance owner.

user_project

path

string

The project ID of the user’s project.

quotas

body

string

Dictionary that defines the resources quota.

Request Example

{
    "quotas": {
        "instances": 10,
        "backups": 30
    }
}

Response Parameters

Name

In

Type

Description

quotas

body

string

Dictionary that defines the resources quota.

Response Example

{
    "quotas": {
        "instances": 10,
        "backups": 30
    }
}