Database instances#

This section describes the following API operations to manage database instances.

Create database instance#

POST /{version}/{accountId}/instances

Creates a new database instance.

This operation asynchronously provisions a new database instance. This call requires the user to specify a flavor and a volume size. The service then provisions the instance with the requested flavor and sets up a volume of the specified size, which is the storage for the database instance.

Note

  • You can create only one database instance per POST request.

  • You can create a database instance with one or more databases, and users associated to those databases.

  • The default binding for the database instance is port 3306.

  • When used with the restorePoint attribute, this call performs the Restore Backup operation, creating a new database instance to store the backup.

  • For information about using SSL with your database instance, refer to Using SSL for Cloud Database instances.

The following table lists the required and optional attributes for Create instance:

Required and optional attributes for Create instance#

Applies To

Name

Description

Required

Instance

flavorRef

Reference (href) to a flavor as specified in the response from the List Flavors API call. This is the actual URI as specified by the href field in the link. Refer to the List Flavors response examples that follow for an example of the flavorRef. Note: Rather than the flavor URI, you can also pass the flavor id (integer) as the value for flavorRef. Refer to List flavors for details.

Yes

(volume) size

Specifies the volume size in gigabytes (GB). The value specified must be between 1 and 300.

Yes

name

Name of the instance to create. The length of the name is limited to 255 characters and any characters are permitted

No

configuration

Identifier of the configuration group to associate with the instance.

No

(datastore) version / type

Name or uuid of the datastore version and type to associate with the instance. If the datastore is not specified, it defaults to mysql.

No

Database

name

Specifies database names for creating databases on instance creation. Refer to Create database for the required json format.

No

character_set

Set of symbols and encodings. The default character set is utf8.

No

collate

Set of rules for comparing characters in a character set. The default value for collate is utf8_general_ci.

No

User

name

Specifies user name for the database on instance creation. Refer to Create user for the required json format.

No

password

Specifies password for those users on instance creation. Refer to Create user for the required json format.

No

(database) name

Specifies names of databases that those users can access on instance creation. Refer to Create user for the required json format.

No

host

Specifies the host from which a user is allowed to connect to the database. Possible values are a string containing an IPv4 address or “%” to allow connecting from any host. Refer to User access restriction by host for details. If host is not specified, it defaults to “%”.

No

Restore

restorePoint

Specifies the backup id from which to restore the database instance. Note: When you execute the Restore Backup operation, a new database instance is created to store the backup whose id is specified by the restorePoint attribute. All users/passwords/access that were on the instance at the time of the backup will be restored along with the databases. You can create new users or databases if you want, but they cannot be the same as the ones from the instance that was backed up. Refer to the Create Database Instance Restore Request and Response examples for the required json format and details.

No

Refer to Database instance status for a list of possible database instance statuses that may be returned.

This table shows the possible response codes for this operation:

Response Code

Name

Description

200

Success

Request succeeded.

400

Bad Request

The request is missing one or more elements, or the values of some elements are invalid.

401

Unauthorized

You are not authorized to complete this operation. This error can occur if the request is submitted with an invalid authentication token.

403

Forbidden

You are denied access to the requested resource.

404

Not Found

The requested item was not found.

405

badMethod

The specified method is not allowed for the given resource.

413

Over Limit

The number of items returned is above the allowed limit.

422

unprocessableEntity

The item cannot be processed.

500

instanceFault

The instance has experienced a fault.

501

notImplemented

The server does not support the functionality required to fulfill the request.

503

Service Unavailable

The service is not available.

Request#

This table shows the URI parameters for the request:

Name

Type

Description

{accountId}

String

The account ID of the owner of the specified instance.

This operation does not accept a request body.

Example Create database instance: JSON request

The following example shows the Create database instance request:

POST /v1.0/1234/instances HTTP/1.1
User-Agent: python-troveclient
Host: ord.databases.api.rackspacecloud.com
X-Auth-Token: 87c6033c-9ff6-405f-943e-2deb73f278b7
Accept: application/json
Content-Type: application/json

{
    "instance": {
        "databases": [
            {
                "character_set": "utf8",
                "collate": "utf8_general_ci",
                "name": "sampledb"
            },
            {
                "name": "nextround"
            }
        ],
        "flavorRef": 1,
        "name": "json_rack_instance",
        "users": [
            {
                "databases": [
                    {
                        "name": "sampledb"
                    }
                ],
                "name": "demouser",
                "password": "demopassword"
            }
        ],
        "volume": {
            "size": 2
        }
    }
}

Example Create database instance restore request: JSON

The following example shows the Create database instance restore request:

POST /v1.0/1234/instances HTTP/1.1
User-Agent: python-troveclient
Host: ord.databases.api.rackspacecloud.com
X-Auth-Token: 87c6033c-9ff6-405f-943e-2deb73f278b7
Accept: application/json
Content-Type: application/json

{
    "instance": {
        "flavorRef": 1,
        "name": "json_restore",
        "restorePoint": {
            "backupRef": "61f12fef-edb1-4561-8122-e7c00ef26a82"
        },
        "volume": {
            "size": 2
        }
    }
}

Example Create database instance configuration request: JSON

The following example shows the Create database instance configuration request:

{
   "instance": {
       "name": "mysql_instance",
       "flavorRef": "https://endpoint/v1.0/1234/flavors/1",
       "volume": {
           "size": 2
       },
       "configuration": "12345678-1111-2222-3333-444444444444"
   }
}

Example Create database instance datastore request: JSON

The following example shows the Create database instance datastore request:

{
   "instance": {
       "name": "mysql_instance",
       "flavorRef": "https://endpoint/v1.0/1234/flavors/1",
       "volume": {
           "size": 2
       },
       "datastore": {
           "version": "5.1",
           "type": "MySQL"
       }
   }
}

Response#

Example Create database instance: JSON response

The following example shows the Create database instance response:

HTTP/1.1 200 OK
Content-Type: application/json
Via: 1.1 Repose (Repose/2.6.7)
Content-Length: 703
Date: Thu, 13 Feb 2014 21:47:13 GMT
Server: Jetty(8.0.y.z-SNAPSHOT)

{
    "instance": {
        "created": "2014-02-13T21:47:13",
        "datastore": {
            "type": "mysql",
            "version": "5.6"
        },
        "flavor": {
            "id": "1",
            "links": [
                {
                    "href": "https://ord.databases.api.rackspacecloud.com/v1.0/1234/flavors/1",
                    "rel": "self"
                },
                {
                    "href": "https://ord.databases.api.rackspacecloud.com/flavors/1",
                    "rel": "bookmark"
                }
            ]
        },
        "hostname": "e09ad9a3f73309469cf1f43d11e79549caf9acf2.rackspaceclouddb.com",
        "id": "d4603f69-ec7e-4e9b-803f-600b9205576f",
        "links": [
            {
                "href": "https://ord.databases.api.rackspacecloud.com/v1.0/1234/instances/d4603f69-ec7e-4e9b-803f-600b9205576f",
                "rel": "self"
            },
            {
                "href": "https://ord.databases.api.rackspacecloud.com/instances/d4603f69-ec7e-4e9b-803f-600b9205576f",
                "rel": "bookmark"
            }
        ],
        "name": "json_rack_instance",
        "status": "BUILD",
        "updated": "2014-02-13T21:47:13",
        "volume": {
            "size": 2
        }
    }
}

For convenience, notice in the response examples above that resources contain links to themselves. This allows a client to easily obtain resource URIs rather than to construct them. There are two kinds of link relations associated with resources. A self link contains a versioned link to the resource. These links should be used in cases where the link will be followed immediately. A bookmark link provides a permanent link to a resource that is appropriate for long term storage.

Example Create database instance restore response: JSON

The following example shows the Create database instance restore response:

HTTP/1.1 200 OK
Content-Type: application/json
Via: 1.1 Repose (Repose/2.6.7)
Content-Length: 697
Date: Thu, 13 Feb 2014 21:47:17 GMT
Server: Jetty(8.0.y.z-SNAPSHOT)

{
    "instance": {
        "created": "2014-02-13T21:47:16",
        "datastore": {
            "type": "mysql",
            "version": "5.6"
        },
        "flavor": {
            "id": "1",
            "links": [
                {
                    "href": "https://ord.databases.api.rackspacecloud.com/v1.0/1234/flavors/1",
                    "rel": "self"
                },
                {
                    "href": "https://ord.databases.api.rackspacecloud.com/flavors/1",
                    "rel": "bookmark"
                }
            ]
        },
        "hostname": "e09ad9a3f73309469cf1f43d11e79549caf9acf2.rackspaceclouddb.com",
        "id": "1e9c84df-4443-4f39-9498-5ab7c14a3bb4",
        "links": [
            {
                "href": "https://ord.databases.api.rackspacecloud.com/v1.0/1234/instances/1e9c84df-4443-4f39-9498-5ab7c14a3bb4",
                "rel": "self"
            },
            {
                "href": "https://ord.databases.api.rackspacecloud.com/instances/1e9c84df-4443-4f39-9498-5ab7c14a3bb4",
                "rel": "bookmark"
            }
        ],
        "name": "json_restore",
        "status": "BUILD",
        "updated": "2014-02-13T21:47:16",
        "volume": {
            "size": 2
        }
    }
}

Example Create database instance config response: JSON

The following example shows the Create database instance configuration response:

{
   "instance": {
       "created": "2012-01-25T21:53:09Z",
       "flavor": {
           "id": "1",
           "links": [
               {
                   "href": "https://endpoint/v1.0/1234/flavors/1",
                   "rel": "self"
               },
               {
                   "href": "https://endpoint/flavors/1",
                   "rel": "bookmark"
               }
           ]
       },
       "configuration": {
          "id": "12345678-1111-2222-3333-444444444444",
          "name": "MySQL Tuned Config",
          "links": [
              {
                  "href": "https://endpoint/v1.0/1234/configurations/12345678-1111-2222-3333-444444444444",
                  "rel": "self"
              },
              {
                  "href": "https://endpoint/configurations/12345678-1111-2222-3333-444444444444",
                  "rel": "bookmark"
              }
          ]
      },
       "hostname": "e09ad9a3f73309469cf1f43d11e79549caf9acf2.hostname",
       "id": "dea5a2f7-3ec7-4496-adab-0abb5a42d635",
       "links": [
           {
               "href": "https://endpoint/v1.0/1234/instances/dea5a2f7-3ec7-4496-adab-0abb5a42d635",
               "rel": "self"
           },
           {
               "href": "https://endpoint/instances/dea5a2f7-3ec7-4496-adab-0abb5a42d635",
               "rel": "bookmark"
           }
       ],
       "name": "json_rack_instance",
       "status": "BUILD",
       "updated": "2012-01-25T21:53:10Z",
       "volume": {
           "size": 2
       }
   }
}

Notice in the response example above the configuration named “MySQL Tuned Config” is returned in the response.

Example Create database instance datastore response: JSON

The following example shows the Create database instance datastore response:

{
   "instance": {
       "created": "2012-01-25T21:53:09Z",
       "flavor": {
           "id": "1",
           "links": [
               {
                   "href": "https://endpoint/v1.0/1234/flavors/1",
                   "rel": "self"
               },
               {
                   "href": "https://endpoint/flavors/1",
                   "rel": "bookmark"
               }
           ]
       },
       "datastore": {
           "version": "5.1",
           "type": "MySQL"
       },
       "hostname": "e09ad9a3f73309469cf1f43d11e79549caf9acf2.hostname",
       "id": "dea5a2f7-3ec7-4496-adab-0abb5a42d635",
       "links": [
           {
               "href": "https://endpoint/v1.0/1234/instances/dea5a2f7-3ec7-4496-adab-0abb5a42d635",
               "rel": "self"
           },
           {
               "href": "https://endpoint/instances/dea5a2f7-3ec7-4496-adab-0abb5a42d635",
               "rel": "bookmark"
           }
       ],
       "name": "json_rack_instance",
       "status": "BUILD",
       "updated": "2012-01-25T21:53:10Z",
       "volume": {
           "size": 2
       }
   }
}

List all database instances#

GET /{version}/{accountId}/instances

Lists the status and information for all database instances.

This operation lists the status and information for all database instances.

This operation lists the sources and replicas part for HA database instances.

Refer to Database instance status for a list of possible database instance statuses that may be returned.

This table shows the possible response codes for this operation:

Response Code

Name

Description

200

Success

Request succeeded.

400

Bad Request

The request is missing one or more elements, or the values of some elements are invalid.

401

Unauthorized

You are not authorized to complete this operation. This error can occur if the request is submitted with an invalid authentication token.

403

Forbidden

You are denied access to the requested resource.

404

Not Found

The requested item was not found.

405

badMethod

The specified method is not allowed for the given resource.

413

Over Limit

The number of items returned is above the allowed limit.

422

unprocessableEntity

The item cannot be processed.

500

instanceFault

The instance has experienced a fault.

501

notImplemented

The server does not support the functionality required to fulfill the request.

503

Service Unavailable

The service is not available.

Request#

This table shows the URI parameters for the request:

Name

Type

Description

{accountId}

String

The account ID of the owner of the specified instance.

This table shows the query parameters for the request:

Name

Type

Description

include_replicas

String (Optional)

When include_replicas is set to false, the replica instances are filtered out of the response.

include_ha

String (Optional)

When include_ha is set to false, the HA instances are filtered out of the response.

This operation does not accept a request body.

Example List all database instances: JSON request

The following example shows the List all database instances request:

GET /v1.0/1234/instances HTTP/1.1
User-Agent: python-troveclient
Host: ord.databases.api.rackspacecloud.com
X-Auth-Token: 87c6033c-9ff6-405f-943e-2deb73f278b7
Accept: application/json
Content-Type: application/json

Example List all sources and replicas part of an HA instance request: JSON

The following example shows the List all sources and replicas part of an HA instance request:

GET /v1.0/1234/instances HTTP/1.1
User-Agent: python-troveclient
Host: ord.databases.api.rackspacecloud.com
X-Auth-Token: e3b2c743aebf467fb6b91cbb644c036e
Accept: application/json
Content-Type: application/json

Example List all instances and filter out instances part of an HA setup request: JSON

The following example shows the List all instances and filter out instances part of an HA setup request:

GET /v1.0/1234/instances?include_ha=false HTTP/1.1
User-Agent: python-troveclient
Host: ord.databases.api.rackspacecloud.com
X-Auth-Token: 87c6033c-9ff6-405f-943e-2deb73f278b7
Accept: application/json
Content-Type: application/json

Response#

Example List all database instances: JSON response

The following example shows the List all database instances response:

HTTP/1.1 200 OK
Content-Type: application/json
Via: 1.1 Repose (Repose/2.6.7)
Content-Length: 1102
Date: Thu, 13 Feb 2014 21:47:15 GMT
Server: Jetty(8.0.y.z-SNAPSHOT)

{
    "instances": [
        {
            "datastore": {
                "type": "mysql",
                "version": "5.1"
            },
            "flavor": {
                "id": "1",
                "links": [
                    {
                        "href": "https://ord.databases.api.rackspacecloud.com/v1.0/1234/flavors/1",
                        "rel": "self"
                    },
                    {
                        "href": "https://ord.databases.api.rackspacecloud.com/flavors/1",
                        "rel": "bookmark"
                    }
                ]
            },
            "id": "d4603f69-ec7e-4e9b-803f-600b9205576f",
            "links": [
                {
                    "href": "https://ord.databases.api.rackspacecloud.com/v1.0/1234/instances/d4603f69-ec7e-4e9b-803f-600b9205576f",
                    "rel": "self"
                },
                {
                    "href": "https://ord.databases.api.rackspacecloud.com/instances/d4603f69-ec7e-4e9b-803f-600b9205576f",
                    "rel": "bookmark"
                }
            ],
            "name": "json_rack_instance",
            "status": "ACTIVE",
            "volume": {
                "size": 2
            }
        },
        {
            "datastore": {
                "type": "mysql"
            },
            "flavor": {
                "id": "1",
                "links": [
                    {
                        "href": "https://ord.databases.api.rackspacecloud.com/v1.0/1234/flavors/1",
                        "rel": "self"
                    },
                    {
                        "href": "https://ord.databases.api.rackspacecloud.com/flavors/1",
                        "rel": "bookmark"
                    }
                ]
            },
            "id": "dcf2c32b-241d-4c39-af70-1001dfe946d6",
            "links": [
                {
                    "href": "https://ord.databases.api.rackspacecloud.com/v1.0/1234/instances/dcf2c32b-241d-4c39-af70-1001dfe946d6",
                    "rel": "self"
                },
                {
                    "href": "https://ord.databases.api.rackspacecloud.com/instances/dcf2c32b-241d-4c39-af70-1001dfe946d6",
                    "rel": "bookmark"
                }
            ],
            "name": "xml_rack_instance",
            "status": "ACTIVE",
            "volume": {
                "size": 2
            }
        }
    ]
}

Example List all sources and replicas part of an HA instance response: JSON

The following example shows the List all sources and replicas part of an HA instance response:

HTTP/1.1 200 OK
Content-Type: application/json
Via: 1.1 Repose (Repose/2.6.7)
Content-Length: ‘19877’
Date: Fri, 08 May 2015 15:56:23 GMT
Server: Jetty(8.0.y.z-SNAPSHOT)

{
   "instances":[
      {
         "status":"ACTIVE",
         "name":"try-1-master_replica2",
         "links":[
            {
               "href":"https://ord.databases.api.rackspacecloud.com/v1.0/1234/instances/35b88c2c-60ba-4f71-af7a-6dd22047dd73",
               "rel":"self"
            },
            {
               "href":"https://ord.databases.api.rackspacecloud.com/instances/35b88c2c-60ba-4f71-af7a-6dd22047dd73",
               "rel":"bookmark"
            }
         ],
         "hostname":"1a0ddee64a843a8afb875c0799c720d134374452.ord.rackspaceclouddb.com",
         "id":"35b88c2c-60ba-4f71-af7a-6dd22047dd73",
         "volume":{
            "size":1
         },
         "ha_id":"0236f3ee-c1c6-40d1-8388-69da13c09cfe",
         "flavor":{
            "id":"2",
            "links":[
               {
                  "href":"https://ord.databases.api.rackspacecloud.com/v1.0/1234/flavors/2",
                  "rel":"self"
               },
               {
                  "href":"https://ord.databases.api.rackspacecloud.com/flavors/2",
                  "rel":"bookmark"
               }
            ]
         },
         "datastore":{
            "version":"5.6",
            "type":"mysql"
         },
         "replica_of":{
            "id":"8ae74c7c-b4d2-4461-92ee-41c824a79124",
            "links":[
               {
                  "href":"https://ord.databases.api.rackspacecloud.com/v1.0/1234/instances/8ae74c7c-b4d2-4461-92ee-41c824a79124",
                  "rel":"self"
               },
               {
                  "href":"https://ord.databases.api.rackspacecloud.com/instances/8ae74c7c-b4d2-4461-92ee-41c824a79124",
                  "rel":"bookmark"
               }
            ]
         }
      },
      {
         "status":"ACTIVE",
         "name":"source",
         "links":[
            {
               "href":"https://ord.databases.api.rackspacecloud.com/v1.0/1234/instances/82cba72c-26a3-4e61-a4f1-7c65647b1c9f",
               "rel":"self"
            },
            {
               "href":"https://ord.databases.api.rackspacecloud.com/instances/82cba72c-26a3-4e61-a4f1-7c65647b1c9f",
               "rel":"bookmark"
            }
         ],
         "replicas":[
            {
               "id":"4eeeb7a6-0dee-4e66-b433-f6462d45c580",
               "links":[
                  {
                     "href":"https://ord.databases.api.rackspacecloud.com/v1.0/1234/instances/4eeeb7a6-0dee-4e66-b433-f6462d45c580",
                     "rel":"self"
                  },
                  {
                     "href":"https://ord.databases.api.rackspacecloud.com/instances/4eeeb7a6-0dee-4e66-b433-f6462d45c580",
                     "rel":"bookmark"
                  }
               ],
               "name":"source_replica1"
            }
         ],
         "hostname":"55036bc3d34c36a44911414d0e92bba071f0bfc8.ord.rackspaceclouddb.com",
         "id":"82cba72c-26a3-4e61-a4f1-7c65647b1c9f",
         "volume":{
            "size":1
         },
         "flavor":{
            "id":"2",
            "links":[
               {
                  "href":"https://ord.databases.api.rackspacecloud.com/v1.0/1234/flavors/2",
                  "rel":"self"
               },
               {
                  "href":"https://ord.databases.api.rackspacecloud.com/flavors/2",
                  "rel":"bookmark"
               }
            ]
         },
         "datastore":{
            "version":"5.6",
            "type":"mysql"
         },
         "ha_id":"e7fdf90b-7140-4edb-b449-e093d55008fb"
      },
      {
         "status":"ACTIVE",
         "name":"source_replica1",
         "links":[
            {
               "href":"https://ord.databases.api.rackspacecloud.com/v1.0/1234/instances/4eeeb7a6-0dee-4e66-b433-f6462d45c580",
               "rel":"self"
            },
            {
               "href":"https://ord.databases.api.rackspacecloud.com/instances/4eeeb7a6-0dee-4e66-b433-f6462d45c580",
               "rel":"bookmark"
            }
         ],
         "hostname":"7e51adcbf8ded6ed1d41311e2e449d5836914dc2.ord.rackspaceclouddb.com",
         "id":"4eeeb7a6-0dee-4e66-b433-f6462d45c580",
         "volume":{
            "size":1
         },
         "ha_id":"e7fdf90b-7140-4edb-b449-e093d55008fb",
         "flavor":{
            "id":"2",
            "links":[
               {
                  "href":"https://ord.databases.api.rackspacecloud.com/v1.0/1234/flavors/2",
                  "rel":"self"
               },
               {
                  "href":"https://ord.databases.api.rackspacecloud.com/flavors/2",
                  "rel":"bookmark"
               }
            ]
         },
         "datastore":{
            "version":"5.6",
            "type":"mysql"
         },
         "replica_of":{
            "id":"82cba72c-26a3-4e61-a4f1-7c65647b1c9f",
            "links":[
               {
                  "href":"https://ord.databases.api.rackspacecloud.com/v1.0/1234/instances/82cba72c-26a3-4e61-a4f1-7c65647b1c9f",
                  "rel":"self"
               },
               {
                  "href":"https://ord.databases.api.rackspacecloud.com/instances/82cba72c-26a3-4e61-a4f1-7c65647b1c9f",
                  "rel":"bookmark"
               }
            ]
         }
      }
   ]
}

Example List all instances and filter out instances part of an HA setup response: JSON

The following example shows the List all instances and filter out instances part of an HA setup response:

HTTP/1.1 200 OK
Content-Type: application/json
Via: 1.1 Repose (Repose/2.6.7)
Content-Length: 697
Date: Thu, 13 Feb 2014 21:47:17 GMT
Server: Jetty(8.0.y.z-SNAPSHOT

{
   "instances":[
      {
         "status":"ACTIVE",
         "name":"master1",
         "links":[
            {
               "href":"https://ord.databases.api.rackspacecloud.com/v1.0/1234/instances/df9e5206-cc95-4131-9ea4-f928c99f1aec",
               "rel":"self"
            },
            {
               "href":"https://ord.databases.api.rackspacecloud.com/instances/df9e5206-cc95-4131-9ea4-f928c99f1aec",
               "rel":"bookmark"
            }
         ],
         "replicas":[
            {
               "id":"1b1fc872-00bb-4fc7-894f-b02e83609ae6",
               "name":"slave1",
               "links":[
                  {
                     "href":"https://ord.databases.api.rackspacecloud.com/v1.0/1234/instances/1b1fc872-00bb-4fc7-894f-b02e83609ae6",
                     "rel":"self"
                  },
                  {
                     "href":"https://ord.databases.api.rackspacecloud.com/instances/1b1fc872-00bb-4fc7-894f-b02e83609ae6",
                     "rel":"bookmark"
                  }
               ]
            },
            {
               "id":"3ac8641f-293d-4533-ab7a-9be25070b98f",
               "name":"slave2",
               "links":[
                  {
                     "href":"https://ord.databases.api.rackspacecloud.com/v1.0/1234/instances/3ac8641f-293d-4533-ab7a-9be25070b98f",
                     "rel":"self"
                  },
                  {
                     "href":"https://ord.databases.api.rackspacecloud.com/instances/3ac8641f-293d-4533-ab7a-9be25070b98f",
                     "rel":"bookmark"
                  }
               ]
            }
         ],
         "ip":[
            "10.0.0.2"
         ],
         "id":"df9e5206-cc95-4131-9ea4-f928c99f1aec",
         "volume":{
            "size":1
         },
         "flavor":{
            "id":"9",
            "links":[
               {
                  "href":"https://ord.databases.api.rackspacecloud.com/v1.0/1234/flavors/9",
                  "rel":"self"
               },
               {
                  "href":"https://ord.databases.api.rackspacecloud.com/flavors/9",
                  "rel":"bookmark"
               }
            ]
         },
         "datastore":{
            "version":"5.6",
            "type":"mysql"
         }
      }
   ]
}

Update database instance#

PUT /{version}/{accountId}/instances/{instanceId}

Associates a specified database instance with a configuration group.

This operation associates a specified database instance with a configuration group.

Note

If any of the parameters in the configuration require a restart, then you will need to reboot the Database instance after associating the configuration. You can call the API operation List Configuration Parameters to find out which of the configuration parameters require a restart.

This table shows the possible response codes for this operation:

Response Code

Name

Description

200

Success

Request succeeded.

400

Bad Request

The request is missing one or more elements, or the values of some elements are invalid.

401

Unauthorized

You are not authorized to complete this operation. This error can occur if the request is submitted with an invalid authentication token.

403

Forbidden

You are denied access to the requested resource.

404

Not Found

The requested item was not found.

405

badMethod

The specified method is not allowed for the given resource.

413

Over Limit

The number of items returned is above the allowed limit.

422

unprocessableEntity

The item cannot be processed.

500

instanceFault

The instance has experienced a fault.

501

notImplemented

The server does not support the functionality required to fulfill the request.

503

Service Unavailable

The service is not available.

Request#

This table shows the URI parameters for the request:

Name

Type

Description

{accountId}

String

The account ID of the owner of the specified instance.

{instanceId}

String

The instance ID for the specified database instance.

This operation does not accept a request body.

Example Update database instance: JSON request

The following example shows the Update database instance request:

PUT /v1.0/1234/instances/d4603f69-ec7e-4e9b-803f-600b9205576f HTTP/1.1
User-Agent: python-troveclient
Host: ord.databases.api.rackspacecloud.com
X-Auth-Token: 87c6033c-9ff6-405f-943e-2deb73f278b7
Accept: application/json
Content-Type: application/json

{
    "instance": {
        "configuration": ""
    }
}

Response#

Example Update database instance: JSON response

The following example shows the Update database instance response:

HTTP/1.1 202 Accepted
Content-Type: application/json
Via: 1.1 Repose (Repose/2.6.7)
Content-Length: 0
Date: Thu, 13 Feb 2014 21:47:15 GMT
Server: Jetty(8.0.y.z-SNAPSHOT)

List database instance status and details#

GET /{version}/{accountId}/instances/{instanceId}

Lists status and details for a specified database instance.

This operation lists the status and details of the specified database instance. The operation also lists the configuration group id/name if the running instance has been associated with a configuration group. For HA instances, lists details for the source instance part or the replica instance part, depending on the ID specified.

This operation lists the volume size in gigabytes (GB) and the approximate GB used.

Note

After instance creation, the used size of your volume will be greater than 0. This is expected and due to the automatic creation of non-empty transaction logs for database optimization. The used attribute is not returned in the response when the status for the instance is BUILD, REBOOT, RESIZE, or ERROR.

Refer to Database instance status for a list of possible database instance statuses that may be returned.

The list operations return a DNS-resolvable hostname associated with the database instance instead of an IP address. Since the hostname always resolves to the correct IP address of the database instance, this relieves the user from the task of maintaining the mapping. Note that although the IP address may likely change on resizing, migrating, and so forth, the hostname always resolves to the correct database instance.

This table shows the possible response codes for this operation:

Response Code

Name

Description

200

Success

Request succeeded.

400

Bad Request

The request is missing one or more elements, or the values of some elements are invalid.

401

Unauthorized

You are not authorized to complete this operation. This error can occur if the request is submitted with an invalid authentication token.

403

Forbidden

You are denied access to the requested resource.

404

Not Found

The requested item was not found.

405

badMethod

The specified method is not allowed for the given resource.

413

Over Limit

The number of items returned is above the allowed limit.

422

unprocessableEntity

The item cannot be processed.

500

instanceFault

The instance has experienced a fault.

501

notImplemented

The server does not support the functionality required to fulfill the request.

503

Service Unavailable

The service is not available.

Request#

This table shows the URI parameters for the request:

Name

Type

Description

{accountId}

String

The account ID of the owner of the specified instance.

{instanceId}

String

The instance ID for the specified database instance.

This operation does not accept a request body.

Example List database instance status and details: JSON request

The following example shows the List database instance status and details request:

GET /v1.0/1234/instances/d4603f69-ec7e-4e9b-803f-600b9205576f HTTP/1.1
User-Agent: python-troveclient
Host: ord.databases.api.rackspacecloud.com
X-Auth-Token: 87c6033c-9ff6-405f-943e-2deb73f278b7
Accept: application/json
Content-Type: application/json

Example List database instance status and details with configuration request: JSON

The following example shows the List database instance status and details with configuration request:

GET /v1.0/1234/instances/d4603f69-ec7e-4e9b-803f-600b9205576f HTTP/1.1
User-Agent: python-troveclient
Host: ord.databases.api.rackspacecloud.com
X-Auth-Token: 87c6033c-9ff6-405f-943e-2deb73f278b7
Accept: application/json
Content-Type: application/json

Example List details of a source instance in an HA setup request: JSON

The following example shows the List database instance status and details of a source instance in an HA setup request:

GET /v1.0/1234/instances/82cba72c-26a3-4e61-a4f1-7c65647b1c9f HTTP/1.1
User-Agent: python-troveclient
Host: ord.databases.api.rackspacecloud.com
X-Auth-Token: e3b2c743aebf467fb6b91cbb644c036e
Accept: application/json
Content-Type: application/json

Example List details of a replica instance in an HA setup request: JSON

The following example shows the List database instance status and details of a replica instance in an HA setup request:

GET /v1.0/1234/instances/4eeeb7a6-0dee-4e66-b433-f6462d45c580  HTTP/1.1
User-Agent: python-troveclient
Host: ord.databases.api.rackspacecloud.com
X-Auth-Token: e3b2c743aebf467fb6b91cbb644c036e
Accept: application/json
Content-Type: application/json

Response#

Example List database instance status and details: JSON response

The following example shows the List database instance status and details response:

HTTP/1.1 200 OK
Content-Type: application/json
Via: 1.1 Repose (Repose/2.6.7)
Content-Length: 718
Date: Thu, 13 Feb 2014 21:47:15 GMT
Server: Jetty(8.0.y.z-SNAPSHOT)

{
    "instance": {
        "created": "2014-02-13T21:47:13",
        "datastore": {
            "type": "mysql",
            "version": "5.1"
        },
        "flavor": {
            "id": "1",
            "links": [
                {
                    "href": "https://ord.databases.api.rackspacecloud.com/v1.0/1234/flavors/1",
                    "rel": "self"
                },
                {
                    "href": "https://ord.databases.api.rackspacecloud.com/flavors/1",
                    "rel": "bookmark"
                }
            ]
        },
        "hostname": "e09ad9a3f73309469cf1f43d11e79549caf9acf2.rackspaceclouddb.com",
        "id": "d4603f69-ec7e-4e9b-803f-600b9205576f",
        "links": [
            {
                "href": "https://ord.databases.api.rackspacecloud.com/v1.0/1234/instances/d4603f69-ec7e-4e9b-803f-600b9205576f",
                "rel": "self"
            },
            {
                "href": "https://ord.databases.api.rackspacecloud.com/instances/d4603f69-ec7e-4e9b-803f-600b9205576f",
                "rel": "bookmark"
            }
        ],
        "name": "json_rack_instance",
        "status": "ACTIVE",
        "updated": "2014-02-13T21:47:15",
        "volume": {
            "size": 2,
            "used": 0.16
        }
    }
}

Example List database instance status and details with configuration response: JSON

The following example shows the List database instance status and details with configuration response:

{
 "instance": {
       "created": "2012-01-25T21:53:09Z",
       "flavor": {
           "id": "1",
           "links": [
               {
                   "href": "https://endpoint/v1.0/1234/flavors/1",
                   "rel": "self"
               },
               {
                   "href": "https://endpoint/flavors/1",
                   "rel": "bookmark"
               }
           ]
       },
       "configuration": {
           "id": "12345678-1111-2222-3333-444444444444",
           "name": "MySQL Tuned Config",
           "links": [
               {
                   "href": "https://endpoint/v1.0/1234/configurations/12345678-1111-2222-3333-444444444444",
                   "rel": "self"
               },
               {
                   "href": "https://endpoint/configurations/12345678-1111-2222-3333-444444444444",
                   "rel": "bookmark"
               }
           ]
       },
       "hostname": "e09ad9a3f73309469cf1f43d11e79549caf9acf2.hostname",
       "id": "dea5a2f7-3ec7-4496-adab-0abb5a42d635",
       "links": [
           {
               "href": "https://endpoint/v1.0/1234/instances/dea5a2f7-3ec7-4496-adab-0abb5a42d635",
               "rel": "self"
           },
           {
               "href": "https://endpoint/instances/dea5a2f7-3ec7-4496-adab-0abb5a42d635",
               "rel": "bookmark"
           }
       ],
       "name": "json_rack_instance",
       "status": "BUILD",
       "updated": "2012-01-25T21:53:10Z",
       "volume": {
           "size": 2
       }
   }
}

Notice in the response example above the configuration named “MySQL Tuned Config” is returned since the instance is associated with that configuration.

Example List details of a source instance in an HA setup response: JSON

The following example shows the List database instance status and details of a source instance in an HA setup response:

HTTP/1.1 200 OK
Content-Type: application/json
Via: 1.1 Repose (Repose/2.6.7)
Content-Length: ‘1243’
Date: Fri, 08 May 2015 15:56:23 GMT
Server: Jetty(8.0.y.z-SNAPSHOT)

{
   "instance":{
      "status":"ACTIVE",
      "updated":"2015-05-08T13:03:43Z",
      "name":"source",
      "links":[
         {
            "href":"https://ord.databases.api.rackspacecloud.com/v1.0/1234/instances/82cba72c-26a3-4e61-a4f1-7c65647b1c9f",
            "rel":"self"
         },
         {
            "href":"https://ord.databases.api.rackspacecloud.com/instances/82cba72c-26a3-4e61-a4f1-7c65647b1c9f",
            "rel":"bookmark"
         }
      ],
      "replicas":[
         {
            "id":"4eeeb7a6-0dee-4e66-b433-f6462d45c580",
            "links":[
               {
                  "href":"https://ord.databases.api.rackspacecloud.com/v1.0/1234/instances/4eeeb7a6-0dee-4e66-b433-f6462d45c580",
                  "rel":"self"
               },
               {
                  "href":"https://ord.databases.api.rackspacecloud.com/instances/4eeeb7a6-0dee-4e66-b433-f6462d45c580",
                  "rel":"bookmark"
               }
            ],
            "name":"source_replica1"
         }
      ],
      "hostname":"55036bc3d34c36a44911414d0e92bba071f0bfc8.ord.rackspaceclouddb.com",
      "id":"82cba72c-26a3-4e61-a4f1-7c65647b1c9f",
      "volume":{
         "used":0.18,
         "size":1
      },
      "created":"2015-05-08T13:03:08Z",
      "flavor":{
         "id":"2",
         "links":[
            {
               "href":"https://ord.databases.api.rackspacecloud.com/v1.0/1234/flavors/2",
               "rel":"self"
            },
            {
               "href":"https://ord.databases.api.rackspacecloud.com/flavors/2",
               "rel":"bookmark"
            }
         ]
      },
      "datastore":{
         "version":"5.6",
         "type":"mysql"
      },
      "ha_id":"e7fdf90b-7140-4edb-b449-e093d55008fb"
   }
}

Example List details of a replica instance in an HA setup response: JSON

The following example shows the List database instance status and details of a replica instance in an HA setup response:

HTTP/1.1 200 OK
Content-Type: application/json
Via: 1.1 Repose (Repose/2.6.7)
Content-Length: ‘1225’
Date: Fri, 08 May 2015 16:32:09 GMT
Server: Jetty(8.0.y.z-SNAPSHOT)

{
   "instance":{
      "status":"ACTIVE",
      "updated":"2015-05-08T13:06:55Z",
      "name":"source_replica1",
      "links":[
         {
            "href":"https://ord.databases.api.rackspacecloud.com/v1.0/1234/instances/4eeeb7a6-0dee-4e66-b433-f6462d45c580",
            "rel":"self"
         },
         {
            "href":"https://ord.databases.api.rackspacecloud.com/instances/4eeeb7a6-0dee-4e66-b433-f6462d45c580",
            "rel":"bookmark"
         }
      ],
      "created":"2015-05-08T13:05:41Z",
      "hostname":"7e51adcbf8ded6ed1d41311e2e449d5836914dc2.ord.rackspaceclouddb.com",
      "id":"4eeeb7a6-0dee-4e66-b433-f6462d45c580",
      "volume":{
         "used":0.18,
         "size":1
      },
      "ha_id":"e7fdf90b-7140-4edb-b449-e093d55008fb",
      "flavor":{
         "id":"2",
         "links":[
            {
               "href":"https://ord.databases.api.rackspacecloud.com/v1.0/1234/flavors/2",
               "rel":"self"
            },
            {
               "href":"https://ord.databases.api.rackspacecloud.com/flavors/2",
               "rel":"bookmark"
            }
         ]
      },
      "datastore":{
         "version":"5.6",
         "type":"mysql"
      },
      "replica_of":{
         "id":"82cba72c-26a3-4e61-a4f1-7c65647b1c9f",
         "links":[
            {
               "href":"https://ord.databases.api.rackspacecloud.com/v1.0/1234/instances/82cba72c-26a3-4e61-a4f1-7c65647b1c9f",
               "rel":"self"
            },
            {
               "href":"https://ord.databases.api.rackspacecloud.com/instances/82cba72c-26a3-4e61-a4f1-7c65647b1c9f",
               "rel":"bookmark"
            }
         ]
      }
   }
}

Change database instance name#

PATCH /{version}/{accountId}/instances/{instanceId}

Changes the name of the instance to the new specified name.

The following table lists the required and optional attributes for Change database instance name:

Required attributes for Create instance#

Name

Description

Required

name

Name of the instance to create. The length of the name is limited to 255 characters and any characters are permitted.

Yes

This table shows the possible response codes for this operation:

Response Code

Name

Description

202

Success

Request succeeded.

400

Bad Request

The request is missing one or more elements, or the values of some elements are invalid.

401

Unauthorized

You are not authorized to complete this operation. This error can occur if the request is submitted with an invalid authentication token.

403

Forbidden

You are denied access to the requested resource.

404

Not Found

The requested item was not found.

405

badMethod

The specified method is not allowed for the given resource.

413

Over Limit

The number of items returned is above the allowed limit.

422

unprocessableEntity

The item cannot be processed.

500

instanceFault

The instance has experienced a fault.

501

notImplemented

The server does not support the functionality required to fulfill the request.

503

Service Unavailable

The service is not available.

Request#

This table shows the URI parameters for the request:

Name

Type

Description

{accountId}

String

The account ID of the owner of the specified instance.

{instanceId}

String

The instance ID for the specified database instance.

Example Change database instance name: JSON request

The following example shows the Change database instance name request:

PATCH  v1.0/1234/instances/ef38d201-89c9-4c11-8407-6f66adb93538 HTTP/1.1
User-Agent: python-troveclient
Host: ord.databases.api.rackspacecloud.com
X-Auth-Token: 87c6033c-9ff6-405f-943e-2deb73f278b7
Accept: application/json
Content-Type: application/json
{

    "instance":{
       "name":"test-instance-2"

    }

}

Response#

Example Change database instance name: JSON response

The following example shows the Change database instance name response:

HTTP/1.1 202 Accepted
Content-Type: application/json
Via: 1.1 Repose (Repose/2.12)
Content-Length: 0
Date: Fri, 06 Nov 2015 16:22:52 GMT
Connection: close
Server: Jetty(8.0.y.z-SNAPSHOT)

Delete database instance#

DELETE /{version}/{accountId}/instances/{instanceId}

Deletes the specified database instance.

This operation deletes the specified database instance, including any associated data.

Refer to Database instance status.

Note

This operation is not allowed when the instance status is BUILD.

This table shows the possible response codes for this operation:

Response Code

Name

Description

202

Accepted

The request has been accepted for processing.

400

Bad Request

The request is missing one or more elements, or the values of some elements are invalid.

401

Unauthorized

You are not authorized to complete this operation. This error can occur if the request is submitted with an invalid authentication token.

403

Forbidden

You are denied access to the requested resource.

404

Not Found

The requested item was not found.

405

badMethod

The specified method is not allowed for the given resource.

413

Over Limit

The number of items returned is above the allowed limit.

422

unprocessableEntity

The item cannot be processed.

500

instanceFault

The instance has experienced a fault.

501

notImplemented

The server does not support the functionality required to fulfill the request.

503

Service Unavailable

The service is not available.

Request#

This table shows the URI parameters for the request:

Name

Type

Description

{accountId}

String

The account ID of the owner of the specified instance.

{instanceId}

String

The instance ID for the specified database instance.

This operation does not accept a request body.

Example Delete database instance: JSON request

The following example shows the Delete database instance request:

DELETE /v1.0/1234/instances/d4603f69-ec7e-4e9b-803f-600b9205576f HTTP/1.1
User-Agent: python-troveclient
Host: ord.databases.api.rackspacecloud.com
X-Auth-Token: 87c6033c-9ff6-405f-943e-2deb73f278b7
Accept: application/json
Content-Type: application/json

Response#

Example Delete database instance: JSON response

The following example shows the Delete database instance response:

HTTP/1.1 202 Accepted
Content-Type: application/json
Via: 1.1 Repose (Repose/2.6.7)
Content-Length: 0
Date: Thu, 13 Feb 2014 21:47:19 GMT
Server: Jetty(8.0.y.z-SNAPSHOT)

Get default configuration#

GET /{version}/{accountId}/instances/{instanceId}/configuration

Lists the default configuration settings from the template that were applied to the specified instance.

This operation lists the default configuration settings from the template that were applied to the specified instance.

This table shows the possible response codes for this operation:

Response Code

Name

Description

200

Success

Request succeeded.

400

Bad Request

The request is missing one or more elements, or the values of some elements are invalid.

401

Unauthorized

You are not authorized to complete this operation. This error can occur if the request is submitted with an invalid authentication token.

403

Forbidden

You are denied access to the requested resource.

404

Not Found

The requested item was not found.

405

badMethod

The specified method is not allowed for the given resource.

413

Over Limit

The number of items returned is above the allowed limit.

422

unprocessableEntity

The item cannot be processed.

500

instanceFault

The instance has experienced a fault.

501

notImplemented

The server does not support the functionality required to fulfill the request.

503

Service Unavailable

The service is not available.

Request#

This table shows the URI parameters for the request:

Name

Type

Description

{accountId}

String

The account ID of the owner of the specified instance.

{instanceId}

String

The instance ID for the specified database instance.

This operation does not accept a request body.

Example Get default configuration: JSON request

The following example shows the Get default configuration request:

GET /v1.0/1234/instances/dcc5c518-73c7-4471-83e1-15fae67a98eb/configuration HTTP/1.1
User-Agent: python-reddwarfclient
Host: ord.databases.api.rackspacecloud.com
X-Auth-Token: 87c6033c-9ff6-405f-943e-2deb73f278b7
Accept: application/json
Content-Type: application/json

Response#

Example Get default configuration: JSON response

The following example shows the Get default configuration response:

{
    "instance": {
        "configuration": {
            "basedir": "/usr",
            "connect_timeout": "15",
            "datadir": "/var/lib/mysql",
            "default_storage_engine": "innodb",
            "innodb_buffer_pool_instances": "1",
            "innodb_buffer_pool_size": "175M",
            "innodb_checksum_algorithm": "crc32",
            "innodb_data_file_path": "ibdata1:10M:autoextend",
            "innodb_file_per_table": "1",
            "innodb_io_capacity": "200",
            "innodb_io_capacity_max": "400               # 2 x innodb_io_capacity",
            "innodb_log_buffer_size": "8M",
            "innodb_log_file_size": "256M",
            "innodb_log_files_in_group": "2",
            "innodb_open_files": "8192",
            "innodb_thread_concurrency": "0",
            "join_buffer_size": "1M",
            "key_buffer_size": "50M",
            "local-infile": "0",
            "log-error": "/var/log/mysql/mysqld.log",
            "max_allowed_packet": "16M",
            "max_connect_errors": "10000",
            "max_connections": "40",
            "max_heap_table_size": "16M",
            "myisam-recover": "BACKUP",
            "open_files_limit": "8192",
            "performance_schema": "off",
            "pid_file": "/var/run/mysqld/mysqld.pid",
            "port": "3306",
            "query_cache_limit": "1M",
            "query_cache_size": "8M",
            "query_cache_type": "1",
            "read_buffer_size": "256K",
            "read_rnd_buffer_size": "1M",
            "server_id": "1",
            "skip-external-locking": "1",
            "skip_name_resolve": "1",
            "sort_buffer_size": "256K",
            "table_open_cache": "4096",
            "thread_stack": "192K",
            "tmp_table_size": "16M",
            "tmpdir": "/var/tmp",
            "user": "mysql",
            "wait_timeout": "3600"
        }
    }
}

Enable root user#

POST /{version}/{accountId}/instances/{instanceId}/root

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

This operation enables login from any host for the root user and provides the user with a generated root password.

This table shows the possible response codes for this operation:

Response Code

Name

Description

200

Success

Request succeeded.

400

Bad Request

The request is missing one or more elements, or the values of some elements are invalid.

401

Unauthorized

You are not authorized to complete this operation. This error can occur if the request is submitted with an invalid authentication token.

403

Forbidden

You are denied access to the requested resource.

404

Not Found

The requested item was not found.

405

badMethod

The specified method is not allowed for the given resource.

413

Over Limit

The number of items returned is above the allowed limit.

422

unprocessableEntity

The item cannot be processed.

500

instanceFault

The instance has experienced a fault.

501

notImplemented

The server does not support the functionality required to fulfill the request.

503

Service Unavailable

The service is not available.

Request#

This table shows the URI parameters for the request:

Name

Type

Description

{accountId}

String

The account ID of the owner of the specified instance.

{instanceId}

String

The instance ID for the specified database instance.

This operation does not accept a request body.

Example Enable root user: JSON request

The following example shows the Enable root user request:

POST /v1.0/1234/instances/d4603f69-ec7e-4e9b-803f-600b9205576f/root HTTP/1.1
User-Agent: python-troveclient
Host: ord.databases.api.rackspacecloud.com
X-Auth-Token: 87c6033c-9ff6-405f-943e-2deb73f278b7
Accept: application/json
Content-Type: application/json

Response#

Example Enable root user: JSON response

The following example shows the Enable root user response:

HTTP/1.1 200 OK
Content-Type: application/json
Via: 1.1 Repose (Repose/2.6.7)
Content-Length: 47
Date: Thu, 13 Feb 2014 21:47:14 GMT
Server: Jetty(8.0.y.z-SNAPSHOT)

{
    "user": {
        "name": "root",
        "password": "12345"
    }
}

List root-enabled status#

GET /{version}/{accountId}/instances/{instanceId}/root

Returns true if root user is enabled for the specified database instance or false otherwise.

This operation checks an active specified database instance to see if root access is enabled. It returns True if root user is enabled for the specified database instance or False otherwise.

This table shows the possible response codes for this operation:

Response Code

Name

Description

200

Success

Request succeeded.

400

Bad Request

The request is missing one or more elements, or the values of some elements are invalid.

401

Unauthorized

You are not authorized to complete this operation. This error can occur if the request is submitted with an invalid authentication token.

403

Forbidden

You are denied access to the requested resource.

404

Not Found

The requested item was not found.

405

badMethod

The specified method is not allowed for the given resource.

413

Over Limit

The number of items returned is above the allowed limit.

422

unprocessableEntity

The item cannot be processed.

500

instanceFault

The instance has experienced a fault.

501

notImplemented

The server does not support the functionality required to fulfill the request.

503

Service Unavailable

The service is not available.

Request#

This table shows the URI parameters for the request:

Name

Type

Description

{accountId}

String

The account ID of the owner of the specified instance.

{instanceId}

String

The instance ID for the specified database instance.

This operation does not accept a request body.

Example List root-enabled status: JSON request

The following example shows the Check root user access request:

GET /v1.0/1234/instances/d4603f69-ec7e-4e9b-803f-600b9205576f/root HTTP/1.1
User-Agent: python-troveclient
Host: ord.databases.api.rackspacecloud.com
X-Auth-Token: 87c6033c-9ff6-405f-943e-2deb73f278b7
Accept: application/json
Content-Type: application/json

Response#

Example List root-enabled status: JSON response

The following example show the Check root user access response:

HTTP/1.1 200 OK
Content-Type: application/json
Via: 1.1 Repose (Repose/2.6.7)
Content-Length: 21
Date: Thu, 13 Feb 2014 21:47:14 GMT
Server: Jetty(8.0.y.z-SNAPSHOT)

{
    "rootEnabled": true
}