4.2.1. Create Database Instance

Verb	URI	Description
POST	`/instances`	Creates a new database instance.

Normal Response Code(s): 200

Error Response Code(s): badRequest (400), unauthorized (401), forbidden (403), badMethod (405), overLimit (413), unprocessableEntity (422), instanceFault (500), notImplemented (501), serviceUnavailable (503), itemNotFound (404)

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.

	Notes
	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 MySQL instance is port 3306.

The following table lists the 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 Section 4.6.1, “List Flavors” for details.

Yes

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

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

Database name Specifies database names for creating databases on instance creation. Refer to Section 4.4.1, “Create Database” for the required xml/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 Section 4.5.1, “Create User” for the required xml/json format. No

password Specifies password for those users on instance creation. Refer to Section 4.5.1, “Create User” for the required xml/json format. No

(database) name Specifies names of databases that those users can access on instance creation. Refer to Section 4.5.1, “Create User” for the required xml/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 Section 3.11.1, “User Access Restriction by Host” for details. If host is not specified, it defaults to "%". No

Refer to Section 3.9, “Database Instance Status” for a list of possible database instance statuses that may be returned.

Table 4.2. Create Database Instance Request Parameters
Name	Style	Type	Description
`accountId`	Template	String	The account ID of the owner of the specified instance.

The following examples show the Create Database Instance requests and responses:

Example 4.9. Create Database Instance Request: XML

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

<instance xmlns="http://docs.openstack.org/database/api/v1.0" flavorRef="1" name="xml_rack_instance">
  <volume size="2"/>
  <users>
    <user password="demopassword" name="demouser">
      <databases>
        <database name="sampledb"/>
      </databases>
    </user>
  </users>
  <databases>
    <database collate="utf8_general_ci" name="sampledb" character_set="utf8"/>
    <database name="nextround"/>
  </databases>
</instance>

Example 4.10. Create Database Instance Request: JSON

POST /v1.0/1234/instances 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

{
    "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 4.11. Create Database Instance Response: XML

HTTP/1.1 200 OK
Content-Type: application/xml
Via: 1.1 Repose (Repose/2.6.7)
Content-Length: 724
Date: Wed, 08 May 2013 22:43:34 GMT
Server: Jetty(8.0.y.z-SNAPSHOT)

<instance created="2013-05-08 22:43:34.487559" hostname="e09ad9a3f73309469cf1f43d11e79549caf9acf2.rackspaceclouddb.com" id="9cccb45e-e15d-4bcc-aedc-61a4bf3e4ad9" name="xml_rack_instance" status="BUILD" updated="2013-05-08 22:43:34.487705" xmlns="http://docs.openstack.org/database/api/v1.0">
    <links>
        <link href="https://ord.databases.api.rackspacecloud.com/v1.0/1234/instances/9cccb45e-e15d-4bcc-aedc-61a4bf3e4ad9" rel="self"/>
        <link href="https://ord.databases.api.rackspacecloud.com/instances/9cccb45e-e15d-4bcc-aedc-61a4bf3e4ad9" rel="bookmark"/>
    </links>
    <volume size="2"/>
    <flavor id="1">
        <links>
            <link href="https://ord.databases.api.rackspacecloud.com/v1.0/1234/flavors/1" rel="self"/>
            <link href="https://ord.databases.api.rackspacecloud.com/flavors/1" rel="bookmark"/>
        </links>
    </flavor>
</instance>

Example 4.12. Create Database Instance Response: JSON

HTTP/1.1 200 OK
Content-Type: application/json
Via: 1.1 Repose (Repose/2.6.7)
Content-Length: 591
Date: Wed, 08 May 2013 22:43:34 GMT
Server: Jetty(8.0.y.z-SNAPSHOT)

{
    "instance": {
        "created": "2013-05-08T22:43:34", 
        "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": "dcc5c518-73c7-4471-83e1-15fae67a98eb", 
        "links": [
            {
                "href": "https://ord.databases.api.rackspacecloud.com/v1.0/1234/instances/dcc5c518-73c7-4471-83e1-15fae67a98eb", 
                "rel": "self"
            }, 
            {
                "href": "https://ord.databases.api.rackspacecloud.com/instances/dcc5c518-73c7-4471-83e1-15fae67a98eb", 
                "rel": "bookmark"
            }
        ], 
        "name": "json_rack_instance", 
        "status": "BUILD", 
        "updated": "2013-05-08T22:43:34", 
        "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.

Legal notices