Create and use a database instance#
Use the examples in the following sections to create, use, and manage a database instance, database, and database users.
You’ll learn how to complete the following tasks:
Find the available hardware configurations to provision a database instance.
Create a database instance, a database, and a database user
Verify that the database and user have been created by using list operations.
Note
These examples use the $API_ENDPOINT, and $AUTH_TOKEN environment
variables to specify the endpoint URI and authentication token values for
accessing the Rackspace Cloud Databases API. Make sure you
configure these variables before
running the code samples.
Listing flavors#
A flavor is an available hardware configuration for a database instance. Each flavor has a unique combination of memory capacity and priority for CPU time. The larger the flavor size you use, the larger the amount of RAM and priority for CPU time your database instance will receive. You can use the list flavors operation to find the available configurations for your database instance, and then decide which size you need.
Following are two methods to list flavors:
List flavors by using the trove client#
Run the ‘flavor-list` command from the command line to list available hardware configuration flavors:
$ trove flavor-list
For each flavor, the command returns the flavor ID, name, and memory:
Flavor List for IAD, DFW, ORD, SYD
+----+----------------+-------+
| id | name | ram |
+----+----------------+-------+
| 1 | 512MB Instance | 512 |
| 2 | 1GB Instance | 1024 |
| 3 | 2GB Instance | 2048 |
| 4 | 4GB Instance | 4096 |
| 5 | 8GB Instance | 8192 |
| 6 | 16GB Instance | 16384 |
| 7 | 32GB Instance | 32768 |
| 8 | 64GB Instance | 65536 |
+----+----------------+-------+
The examples in Create a database instance use the flavor ID for the 512MB Standard Instance, which is 1.
List flavors by using the cURL#
The following example shows the cURL request and corresponding response to list flavors.
Example cURL List Flavors cURL Reques
curl -s \
-H "X-Auth-Token: $AUTH_TOKEN" \
-H "Accept: application/json" \
$API_ENDPOINT/flavors \
| python -m json.tool
JSON response
HTTP/1.1 200 OK
Content-Type: application/json
Via: 1.1 Repose (Repose/2.6.7)
Content-Length: 1186
Date: Thu, 13 Feb 2014 21:47:13 GMT
Server: Jetty(8.0.y.z-SNAPSHOT)
{
"flavors": [
{
"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"
}
],
"name": "512MB Instance",
"ram": 512
},
{
"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"
}
],
"name": "1GB Instance",
"ram": 1024
},
{
"id": 3,
"links": [
{
"href": "https://ord.databases.api.rackspacecloud.com/v1.0/1234/flavors/3",
"rel": "self"
},
{
"href": "https://ord.databases.api.rackspacecloud.com/flavors/3",
"rel": "bookmark"
}
],
"name": "2GB Instance",
"ram": 2048
},
{
"id": 4,
"links": [
{
"href": "https://ord.databases.api.rackspacecloud.com/v1.0/1234/flavors/4",
"rel": "self"
},
{
"href": "https://ord.databases.api.rackspacecloud.com/flavors/4",
"rel": "bookmark"
}
],
"name": "4GB Instance",
"ram": 4096
},
{
"id": 5,
"links": [
{
"href": "https://ord.databases.api.rackspacecloud.com/v1.0/1234/flavors/5",
"rel": "self"
},
{
"href": "https://ord.databases.api.rackspacecloud.com/flavors/5",
"rel": "bookmark"
}
],
"name": "8GB Instance",
"ram": 8192
},
{
"id": 6,
"links": [
{
"href": "https://ord.databases.api.rackspacecloud.com/v1.0/1234/flavors/6",
"rel": "self"
},
{
"href": "https://ord.databases.api.rackspacecloud.com/flavors/6",
"rel": "bookmark"
}
],
"name": "16GB Instance",
"ram": 16384
},
{
"id": 7,
"links": [
{
"href": "https://ord.databases.api.rackspacecloud.com/v1.0/647683/flavors/7",
"rel": "self"
},
{
"href": "https://ord.databases.api.rackspacecloud.com/flavors/7",
"rel": "bookmark"
}
],
"name": "32GB Instance",
"ram": 32768
},
{
"id": 8,
"links": [
{
"href": "https://ord.databases.api.rackspacecloud.com/v1.0/647683/flavors/8",
"rel": "self"
},
{
"href": "https://ord.databases.api.rackspacecloud.com/flavors/8",
"rel": "bookmark"
}
],
"name": "64GB Instance",
"ram": 65536
}
]
}
In the response, you can see from the flavor name that there are multiple flavors available, including 2GB Instance (with 1 virtual CPU and 2 gigabytes of memory) and 512MB Instance (with 1 virtual CPU and 0.5 gigabytes of memory).
In addition to a flavor ID, the response returns two types of links that can be used to reference the flavor configuration.
The
selflinks contains a versioned link to the flavor resource. Use these links in cases where the link is followed immediately (as you will see in the next section).The
bookmarklinks provide a permanent link to each flavor resource. You can use the bookmark link for long term storage, and it also works across API versions.
The examples in Create a database instance use the flavor ID for the 512MB Standard Instance, which is 1.
Creating a database instance, database, and a user#
A database instance is an isolated database environment with compute and storage resources in a single tenant environment on a shared physical host machine.
You can run a database instance with one of the following database engines: MySQL, Percona, or MariaDB. For details, see Database types and versions.
The instance created by running the commands in the following examples, uses the 512MB Instance flavor and a volume size of 2 gigabytes (GB).
Note
For the SYD and HKG datacenters only, the default database is MySQL 5.1 if users do not specify the datastore type and version at instance creation.
For information about database naming restrictions, see Create a database.
Note that it can take several minutes to create the database. You cannot send requests to get information about the database until the database instance status is
ACTIVE.
Following are two methods for creating a database instance:
Create a database instance by using the trove client#
The following example creates a MySQL database instance mytroveinstance,
with the following configuration and user settings:
the 512MB Instance flavor
volume size of 2 gigabytes (GB)
a database named
mytrovedba user
mytroveuserwith passwordpassword
Run the create command with parameters to provision the database instance,
and create the database and database user:
$ trove create --size 2 --databases mytrovedb --users mytroveuser:password --datastore MySQL mytroveinstance 1
Note
If you want to create a different database and version, use the
--datastore and --datastore_version parameters to specify your
choice. For example, to specify a Percona 5.6 database, run the following
command.
$ trove create --size 2 --databases mytrovedb --users mytroveuser:password --datastore Percona --datastore_version 5.6 mytroveinstance 1
When the instance is created, the command returns the date created, flavor ID, hostname, id, name, status, and volume size as shown in the following example.
+-------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Property | Value |
+-------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| created | 2014-04-29T13:33:51 |
| datastore | {u'version': u'5.6', u'type': u'MySQL'} |
| datastore_version | 5.6 |
| flavor | {u'id': u'1', u'links': [{u'href': u'https://dfw.databases.api.rackspacecloud.com/v1.0/647683/flavors/1', u'rel': u'self'}, {u'href': u'https://dfw.databases.api.rackspacecloud.com/flavors/1', u'rel': u'bookmark'}]} |
| hostname | 9175290275ef3292efb02be33dd38ed44443e311.rackspaceclouddb.com |
| id | 18d48a36-0682-4cd7-a419-864105d6079a |
| name | mytroveinstance |
| status | BUILD |
| updated | 2014-04-29T13:33:51 |
| volume | {u'size': 2} |
+-------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
The includes an instance ID value,``id=”18d48a36-0682-4cd7-a419-864105d6079a`` which is the unique ID for the database instance. You need this ID to make subsequent requests that require it like the list databases for an instance operation.
Create a database instance by using cURL#
The following example creates a MySQL database instance myrackinstance,
with the following configuration and user settings:
the 512MB Instance flavor
volume size of 2 gigabytes (GB)
a database named
sampledbwith:
utf8character set
utf8_general_cicollationa user
simplestUserwith passwordpassword
If you want to create a different database and version, use the
datastore version and type parameters to specify your
choice. For example, to specify a Percona 5.6 database, include the
following information in the flavorRev section of the cURL request.
"datastore": { "version": "5.6", "type": "Percona" },
Submit the following cURL request to create the instance:
Example Create Instance cURL request
curl -s -d \
'{
"instance": {
"databases": [
{
"character_set": "utf8",
"collate": "utf8_general_ci",
"name": "sampledb"
}
],
"flavorRef": "https://ord.databases.api.rackspacecloud.com/v1.0/$account/flavors/1",
"name": "myrackinstance",
"users": [
{
"databases": [
{
"name": "sampledb"
}
],
"name": "simplestUser",
"password": "password"
}
],
"volume":
{
"size": 2
}
}
}' \
-H "X-Auth-Token: $AUTH_TOKEN" \
-H "Content-Type: application/json" \
$API_ENDPOINT/instances | python -m json.tool
Note
Rather than the flavorRef URI shown in the example, you can also pass
the flavor id (integer) as the value for flavorRef. For example, the flavor
id for the flavor URI shown above is “1”. The flavorRef URI reference is
returned in the href self link field of the list flavors operation
response.
JSON response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 756
Date: Thu, 05 Apr 2012 16:48:44 GMT
{
"instance": {
"status": "BUILD",
"updated": "2012-04-05T16:48:44Z",
"name": "myrackinstance",
"links": [
{
"href": "http://ord.databases.api.rackspacecloud.com/v1.0/1234/instances/d379ba5c-9a1f-4aa9-9a17-afe237d04c65",
"rel": "self"
},
{
"href": "http://ord.databases.api.rackspacecloud.com/instances/d379ba5c-9a1f-4aa9-9a17-afe237d04c65",
"rel": "bookmark"
}
],
"created": "2012-04-05T16:48:44Z",
"datastore": {
"type": "mysql",
"version": "5.6"
},
"hostname": "ca9fa2985e47b351915c75f1a8e95d0729068892.rackspaceclouddb.com",
"volume": {
"size": 2
},
"flavor": {
"id": "1",
"links": [
{
"href": "http://ord.databases.api.rackspacecloud.com/v1.0/1234/flavors/1",
"rel": "self"
},
{ "href": "http://ord.databases.api.rackspacecloud.com/flavors/1",
"rel": "bookmark"
}
]
},
"id": "d379ba5c-9a1f-4aa9-9a17-afe237d04c65"
}
}
You will need to specify the instance id returned (in the response
examples above: id="d379ba5c-9a1f-4aa9-9a17-afe237d04c65") on
subsequent API calls that require it, for example List Databases for
Instance.
Listing databases for an instance#
After you add a database to an instance, you can use the list databases operation to confirm that it was successfully created.
You need to specify the ID for the database instance in the API request. The instance ID is the unique identifier assigned when the database was created. The following examples use the instance ID from the Create database instance examples.
Following are two methods for listing database instances:
Listing database instances by using the trove client#
Run the database-list command with ID for the database instance:
$ trove database-list <instance_id>
The command returns the database name(s) for the instance:
+-----------+
| name |
+-----------+
| mytrovedb |
+-----------+
Listing database instances by using cURL#
Run the following cURL command to create the instance, replacing
instance_id with the ID for the database instance.
Example List Databases for Instance Request cURLN
curl -s \
-H "X-Auth-Token: $AUTH_TOKEN" \
-H "Content-Type: application/json" \
$API_ENDPOINT/instances/instance_id/databases | python -m json.tool
JSON response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 37
Date: Thu, 05 Apr 2012 18:13:53 GMT
{
"databases": [
{
"name": "sampledb"
}
]
}
Listing users in a database instance#
After you add a database user to an instance, you can use the list users operation to confirm that the user was successfully created.
You need to specify the ID for the database instance in the API request. The instance ID is the unique identifier assigned when the database was created. The following examples use the instance ID from the Create database instance examples.
Following are two methods to list users:
List users for an instance by using the trove client#
Run the database-list command with the ID for the database instance:
$ trove user-list <instance_id>
For the instance, the command returns the user name and the databases that the user can access:
+-------------+------+-----------+
| name | host | databases |
+-------------+------+-----------+
| mytroveuser | % | mytrovedb |
+-------------+------+-----------+
List users for an instance by using the trove client#
Run the following cURL command to create the instance, replacing
instance_id with the ID for the database instance.
Example List Users in Database Instance Request cURL request
curl -s \
-H "X-Auth-Token: $AUTH_TOKEN" \
-H "Content-Type: application/json" \
$API_ENDPOINT/instances/instance_id/users | python -m json.tool
JSON Response
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 113
Date: Thu, 05 Apr 2012 18:13:53 GMT
{
"users": [
{
"databases": [
{
"name": "sampledb"
}
],
"host": "%",
"name": "simplestUser"
}
]
}