openstack/trove
Code Issues Proposed changes

Add Database service user guide

Browse Source 
import the trove user guide from openstack-manuals

Closes-Bug: #1731209
Change-Id: I939e88bfb88234045b0a8b00ee0d6d623c6b10d1
This commit is contained in:
chenxing 2017-10-13 09:49:04 +08:00
parent fa171bd3e9
commit 4d99ae4bb3
8 changed files with 1073 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
doc/source/index.rst
View File

@ -1,6 +1,6 @@
===========================================
Welcome to Trove's developer documentation!
===========================================
=================================
Welcome to Trove's documentation!
=================================
Trove is Database as a Service for OpenStack. It's designed to run
entirely on OpenStack, with the goal of allowing users to quickly and
@ -21,6 +21,7 @@ For an in-depth look at the project's design and structure, see the
:maxdepth: 2
install/index
user/index
admin/index
cli/index
contributor/index

127
doc/source/user/backup-db-incremental.rst Normal file
View File

@ -0,0 +1,127 @@
=======================
Use incremental backups
=======================
Incremental backups let you chain together a series of backups. You
start with a regular backup. Then, when you want to create a subsequent
incremental backup, you specify the parent backup.
Restoring a database instance from an incremental backup is the same as
creating a database instance from a regular backup—the Database service
handles the complexities of applying the chain of incremental backups.
This example shows you how to use incremental backups with a MySQL
database.
**Assumptions.** Assume that you have created a regular
backup for the following database instance:
- Instance name: ``guest1``
- ID of the instance (``INSTANCE_ID``):
``792a6a56-278f-4a01-9997-d997fa126370``
- ID of the regular backup artifact (``BACKUP_ID``):
``6dc3a9b7-1f3e-4954-8582-3f2e4942cddd``
Create and use incremental backups
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#. **Create your first incremental backup**
Use the :command:`trove backup-create` command and specify:
- The ``INSTANCE_ID`` of the database instance you are doing the
incremental backup for (in this example,
``792a6a56-278f-4a01-9997-d997fa126370``)
- The name of the incremental backup you are creating: ``backup1.1``
- The ``BACKUP_ID`` of the parent backup. In this case, the parent
is the regular backup, with an ID of
``6dc3a9b7-1f3e-4954-8582-3f2e4942cddd``
.. code-block:: console
$ trove backup-create INSTANCE_ID backup1.1 --parent BACKUP_ID
+-------------+--------------------------------------+
| Property | Value |
+-------------+--------------------------------------+
| created | 2014-03-19T14:09:13 |
| description | None |
| id | 1d474981-a006-4f62-b25f-43d7b8a7097e |
| instance_id | 792a6a56-278f-4a01-9997-d997fa126370 |
| locationRef | None |
| name | backup1.1 |
| parent_id | 6dc3a9b7-1f3e-4954-8582-3f2e4942cddd |
| size | None |
| status | NEW |
| updated | 2014-03-19T14:09:13 |
+-------------+--------------------------------------+
Note that this command returns both the ID of the database instance
you are incrementally backing up (``instance_id``) and a new ID for
the new incremental backup artifact you just created (``id``).
#. **Create your second incremental backup**
The name of your second incremental backup is ``backup1.2``. This
time, when you specify the parent, pass in the ID of the incremental
backup you just created in the previous step (``backup1.1``). In this
example, it is ``1d474981-a006-4f62-b25f-43d7b8a7097e``.
.. code-block:: console
$ trove backup-create INSTANCE_ID backup1.2 --parent BACKUP_ID
+-------------+--------------------------------------+
| Property | Value |
+-------------+--------------------------------------+
| created | 2014-03-19T14:09:13 |
| description | None |
| id | bb84a240-668e-49b5-861e-6a98b67e7a1f |
| instance_id | 792a6a56-278f-4a01-9997-d997fa126370 |
| locationRef | None |
| name | backup1.2 |
| parent_id | 1d474981-a006-4f62-b25f-43d7b8a7097e |
| size | None |
| status | NEW |
| updated | 2014-03-19T14:09:13 |
+-------------+--------------------------------------+
#. **Restore using incremental backups**
Now assume that your ``guest1`` database instance is damaged and you
need to restore it from your incremental backups. In this example,
you use the :command:`trove create` command to create a new database
instance called ``guest2``.
To incorporate your incremental backups, you simply use the
`--backup`` parameter to pass in the ``BACKUP_ID`` of your most
recent incremental backup. The Database service handles the
complexities of applying the chain of all previous incremental
backups.
.. code-block:: console
$ trove create guest2 10 --size 1 --backup BACKUP_ID
+-------------------+-----------------------------------------------------------+
| Property | Value |
+-------------------+-----------------------------------------------------------+
| created | 2014-03-19T14:10:56 |
| datastore | {u'version': u'mysql-5.5', u'type': u'mysql'} |
| datastore_version | mysql-5.5 |
| flavor | {u'id': u'10', u'links': |
| | [{u'href': u'https://10.125.1.135:8779/v1.0/ |
| | 626734041baa4254ae316de52a20b390/flavors/10', u'rel': |
| | u'self'}, {u'href': u'https://10.125.1.135:8779/ |
| | flavors/10', u'rel': u'bookmark'}]} |
| id | a3680953-eea9-4cf2-918b-5b8e49d7e1b3 |
| name | guest2 |
| status | BUILD |
| updated | 2014-03-19T14:10:56 |
| volume | {u'size': 1} |
+-------------------+-----------------------------------------------------------+

232
doc/source/user/backup-db.rst Normal file
View File

@ -0,0 +1,232 @@
=============================
Backup and restore a database
=============================
You can use Database services to backup a database and store the backup
artifact in the Object Storage service. Later on, if the original
database is damaged, you can use the backup artifact to restore the
database. The restore process creates a database instance.
This example shows you how to back up and restore a MySQL database.
#. **Backup the database instance**
As background, assume that you have created a database
instance with the following
characteristics:
- Name of the database instance: ``guest1``
- Flavor ID: ``10``
- Root volume size: ``2``
- Databases: ``db1`` and ``db2``
- Users: The ``user1`` user with the ``password`` password
First, get the ID of the ``guest1`` database instance by using the
:command:`trove list` command:
.. code-block:: console
$ trove list
+--------------------------------------+--------+-----------+-------------------+--------+-----------+------+
| id | name | datastore | datastore_version | status | flavor_id | size |
+--------------------------------------+--------+-----------+-------------------+--------+-----------+------+
| 97b4b853-80f6-414f-ba6f-c6f455a79ae6 | guest1 | mysql | mysql-5.5 | ACTIVE | 10 | 2 |
+--------------------------------------+--------+-----------+-------------------+--------+-----------+------+
Back up the database instance by using the :command:`trove backup-create`
command. In this example, the backup is called ``backup1``. In this
example, replace ``INSTANCE_ID`` with
``97b4b853-80f6-414f-ba6f-c6f455a79ae6``:
.. note::
This command syntax pertains only to python-troveclient version
1.0.6 and later. Earlier versions require you to pass in the backup
name as the first argument.
.. code-block:: console
$ trove backup-create INSTANCE_ID backup1
+-------------+--------------------------------------+
| Property | Value |
+-------------+--------------------------------------+
| created | 2014-03-18T17:09:07 |
| description | None |
| id | 8af30763-61fd-4aab-8fe8-57d528911138 |
| instance_id | 97b4b853-80f6-414f-ba6f-c6f455a79ae6 |
| locationRef | None |
| name | backup1 |
| parent_id | None |
| size | None |
| status | NEW |
| updated | 2014-03-18T17:09:07 |
+-------------+--------------------------------------+
Note that the command returns both the ID of the original instance
(``instance_id``) and the ID of the backup artifact (``id``).
Later on, use the :command:`trove backup-list` command to get this
information:
.. code-block:: console
$ trove backup-list
+--------------------------------------+--------------------------------------+---------+-----------+-----------+---------------------+
| id | instance_id | name | status | parent_id | updated |
+--------------------------------------+--------------------------------------+---------+-----------+-----------+---------------------+
| 8af30763-61fd-4aab-8fe8-57d528911138 | 97b4b853-80f6-414f-ba6f-c6f455a79ae6 | backup1 | COMPLETED | None | 2014-03-18T17:09:11 |
+--------------------------------------+--------------------------------------+---------+-----------+-----------+---------------------+
You can get additional information about the backup by using the
:command:`trove backup-show` command and passing in the ``BACKUP_ID``,
which is ``8af30763-61fd-4aab-8fe8-57d528911138``.
.. code-block:: console
$ trove backup-show BACKUP_ID
+-------------+----------------------------------------------------+
| Property | Value |
+-------------+----------------------------------------------------+
| created | 2014-03-18T17:09:07 |
| description | None |
| id | 8af...138 |
| instance_id | 97b...ae6 |
| locationRef | http://10.0.0.1:.../.../8af...138.xbstream.gz.enc |
| name | backup1 |
| parent_id | None |
| size | 0.17 |
| status | COMPLETED |
| updated | 2014-03-18T17:09:11 |
+-------------+----------------------------------------------------+
#. **Restore a database instance**
Now assume that your ``guest1`` database instance is damaged and you
need to restore it. In this example, you use the :command:`trove create`
command to create a new database instance called ``guest2``.
- You specify that the new ``guest2`` instance has the same flavor
(``10``) and the same root volume size (``2``) as the original
``guest1`` instance.
- You use the ``--backup`` argument to indicate that this new
instance is based on the backup artifact identified by
``BACKUP_ID``. In this example, replace ``BACKUP_ID`` with
``8af30763-61fd-4aab-8fe8-57d528911138``.
.. code-block:: console
$ trove create guest2 10 --size 2 --backup BACKUP_ID
+-------------------+----------------------------------------------+
| Property | Value |
+-------------------+----------------------------------------------+
| created | 2014-03-18T17:12:03 |
| datastore | {u'version': u'mysql-5.5', u'type': u'mysql'}|
|datastore_version | mysql-5.5 |
| flavor | {u'id': u'10', u'links': [{u'href': ...]} |
| id | ac7a2b35-a9b4-4ff6-beac-a1bcee86d04b |
| name | guest2 |
| status | BUILD |
| updated | 2014-03-18T17:12:03 |
| volume | {u'size': 2} |
+-------------------+----------------------------------------------+
#. **Verify backup**
Now check that the new ``guest2`` instance has the same
characteristics as the original ``guest1`` instance.
Start by getting the ID of the new ``guest2`` instance.
.. code-block:: console
$ trove list
+-----------+--------+-----------+-------------------+--------+-----------+------+
| id | name | datastore | datastore_version | status | flavor_id | size |
+-----------+--------+-----------+-------------------+--------+-----------+------+
| 97b...ae6 | guest1 | mysql | mysql-5.5 | ACTIVE | 10 | 2 |
| ac7...04b | guest2 | mysql | mysql-5.5 | ACTIVE | 10 | 2 |
+-----------+--------+-----------+-------------------+--------+-----------+------+
Use the :command:`trove show` command to display information about the new
guest2 instance. Pass in guest2's ``INSTANCE_ID``, which is
``ac7a2b35-a9b4-4ff6-beac-a1bcee86d04b``.
.. code-block:: console
$ trove show INSTANCE_ID
+-------------------+--------------------------------------+
| Property | Value |
+-------------------+--------------------------------------+
| created | 2014-03-18T17:12:03 |
| datastore | mysql |
| datastore_version | mysql-5.5 |
| flavor | 10 |
| id | ac7a2b35-a9b4-4ff6-beac-a1bcee86d04b |
| ip | 10.0.0.3 |
| name | guest2 |
| status | ACTIVE |
| updated | 2014-03-18T17:12:06 |
| volume | 2 |
| volume_used | 0.18 |
+-------------------+--------------------------------------+
Note that the data store, flavor ID, and volume size have the same
values as in the original ``guest1`` instance.
Use the :command:`trove database-list` command to check that the original
databases (``db1`` and ``db2``) are present on the restored instance.
.. code-block:: console
$ trove database-list INSTANCE_ID
+--------------------+
| name |
+--------------------+
| db1 |
| db2 |
| performance_schema |
| test |
+--------------------+
Use the :command:`trove user-list` command to check that the original user
(``user1``) is present on the restored instance.
.. code-block:: console
$ trove user-list INSTANCE_ID
+--------+------+-----------+
| name | host | databases |
+--------+------+-----------+
| user1 | % | db1, db2 |
+--------+------+-----------+
#. **Notify users**
Tell the users who were accessing the now-disabled ``guest1``
database instance that they can now access ``guest2``. Provide them
with ``guest2``'s name, IP address, and any other information they
might need. (You can get this information by using the
:command:`trove show` command.)
#. **Clean up**
At this point, you might want to delete the disabled ``guest1``
instance, by using the :command:`trove delete` command.
.. code-block:: console
$ trove delete INSTANCE_ID

176
doc/source/user/create-db.rst Normal file
View File

@ -0,0 +1,176 @@
.. _create_db:
============================
Create and access a database
============================
Assume that you have installed the Database service and populated your
data store with images for the type and versions of databases that you
want, and that you can create and access a database.
This example shows you how to create and access a MySQL 5.5 database.
Create and access a database
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#. **Determine which flavor to use for your database**
When you create a database instance, you must specify a nova flavor.
The flavor indicates various characteristics of the instance, such as
RAM and root volume size. You will need to create or
obtain new nova flavors that work for databases.
The first step is to list flavors by using the
:command:`openstack flavor list` command.
.. code-block:: console
$ openstack flavor list
Now take a look at the minimum requirements for various database
instances:
+--------------------+--------------------+--------------------+--------------------+
| Database | RAM (MB) | Disk (GB) | VCPUs |
+====================+====================+====================+====================+
| MySQL | 512 | 5 | 1 |
+--------------------+--------------------+--------------------+--------------------+
| Cassandra | 2048 | 5 | 1 |
+--------------------+--------------------+--------------------+--------------------+
| MongoDB | 1024 | 5 | 1 |
+--------------------+--------------------+--------------------+--------------------+
| Redis | 512 | 5 | 1 |
+--------------------+--------------------+--------------------+--------------------+
- If you have a custom flavor that meets the needs of the database
that you want to create, proceed to
:ref:`Step 2 <create-database-instance>` and use that flavor.
- If your environment does not have a suitable flavor, an
administrative user must create a custom flavor by using the
:command:`openstack flavor create` command.
**MySQL example.** This example creates a flavor that you can use
with a MySQL database. This example has the following attributes:
- Flavor name: ``mysql_minimum``
- Flavor ID: You must use an ID that is not already in use. In this
example, IDs 1 through 5 are in use, so use ID ``6``.
- RAM: ``512``
- Root volume size in GB: ``5``
- Virtual CPUs: ``1``
.. code-block:: console
$ openstack flavor create mysql-minimum --id 6 --ram 512 --disk 5 --vcpus 1
+----------------------------+---------------+
| Field | Value |
+----------------------------+---------------+
| OS-FLV-DISABLED:disabled | False |
| OS-FLV-EXT-DATA:ephemeral | 0 |
| disk | 5 |
| id | 6 |
| name | mysql-minimum |
| os-flavor-access:is_public | True |
| properties | |
| ram | 512 |
| rxtx_factor | 1.0 |
| swap | |
| vcpus | 1 |
+----------------------------+---------------+
.. _create-database-instance:
#. **Create a database instance**
This example creates a database instance with the following
characteristics:
- Name of the instance: ``mysql_instance_1``
- Database flavor: ``6``
In addition, this command specifies these options for the instance:
- A volume size of ``5`` (5 GB).
- The ``myDB`` database.
- The database is based on the ``mysql`` data store and the
``mysql-5.5`` datastore\_version.
- The ``userA`` user with the ``password`` password.
.. code-block:: console
$ trove create mysql_instance_1 6 --size 5 --databases myDB \
--users userA:password --datastore_version mysql-5.5 \
--datastore mysql
+-------------------+---------------------------------------------------------------------------------------t-----------------------------------------------------------------------------------------------------------------+
| Property | Value |
+-------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| created | 2014-05-29T21:26:21 |
| datastore | {u'version': u'mysql-5.5', u'type': u'mysql'} |
| datastore_version | mysql-5.5 |
| flavor | {u'id': u'6', u'links': [{u'href': u'https://controller:8779/v1.0/46d0bc4fc32e4b9e8520f8fc62199f58/flavors/6', u'rel': u'self'}, {u'href': u'https://controller:8779/flavors/6', u'rel': u'bookmark'}]} |
| id | 5599dad6-731e-44df-bb60-488da3da9cfe |
| name | mysql_instance_1 |
| status | BUILD |
| updated | 2014-05-29T21:26:21 |
| volume | {u'size': 5} |
+-------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
#. **Get the IP address of the database instance**
First, use the :command:`trove list` command to list all instances and
their IDs:
.. code-block:: console
$ trove list
+--------------------------------------+------------------+-----------+-------------------+--------+-----------+------+
| id | name | datastore | datastore_version | status | flavor_id | size |
+--------------------------------------+------------------+-----------+-------------------+--------+-----------+------+
| 5599dad6-731e-44df-bb60-488da3da9cfe | mysql_instance_1 | mysql | mysql-5.5 | BUILD | 6 | 5 |
+--------------------------------------+------------------+-----------+-------------------+--------+-----------+------+
This command returns the instance ID of your new instance.
You can now pass in the instance ID with the :command:`trove show` command
to get the IP address of the instance. In this example, replace
``INSTANCE_ID`` with ``5599dad6-731e-44df-bb60-488da3da9cfe``.
.. code-block:: console
$ trove show INSTANCE_ID
+-------------------+--------------------------------------+
| Property | Value |
+-------------------+--------------------------------------+
| created | 2014-05-29T21:26:21 |
| datastore | mysql |
| datastore_version | mysql-5.5 |
| flavor | 6 |
| id | 5599dad6-731e-44df-bb60-488da3da9cfe |
| ip | 172.16.200.2 |
| name | mysql_instance_1 |
| status | BUILD |
| updated | 2014-05-29T21:26:54 |
| volume | 5 |
+-------------------+--------------------------------------+
This command returns the IP address of the database instance.
#. **Access the new database**
You can now access the new database you just created (myDB) by using
typical database access commands. In this MySQL example, replace
``IP_ADDRESS`` with ``172.16.200.2``.
.. code-block:: console
$ mysql -u userA -p password -h IP_ADDRESS myDB

18
doc/source/user/index.rst Normal file
View File

@ -0,0 +1,18 @@
===========================
Database Service User Guide
===========================
The Database service provides scalable and reliable cloud provisioning
functionality for both relational and non-relational database engines.
Users can quickly and easily use database features without the burden of
handling complex administrative tasks.
.. toctree::
:maxdepth: 1
create-db.rst
backup-db.rst
backup-db-incremental.rst
manage-db-config.rst
set-up-replication.rst
set-up-clustering.rst

239
doc/source/user/manage-db-config.rst Normal file
View File

@ -0,0 +1,239 @@
=============================
Manage database configuration
=============================
You can manage database configuration tasks by using configuration
groups. Configuration groups let you set configuration options, in bulk,
on one or more databases.
This example assumes you have created a MySQL
database and shows you how to use a
configuration group to configure it. Although this example sets just one
option on one database, you can use these same procedures to set
multiple options on multiple database instances throughout your
environment. This can provide significant time savings in managing your
cloud.
Bulk-configure a database or databases
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#. **List available options**
First, determine which configuration options you can set. Different
data store versions have different configuration options.
List the names and IDs of all available versions of the ``mysql``
data store:
.. code-block:: console
$ trove datastore-version-list mysql
+--------------------------------------+-----------+
| id | name |
+--------------------------------------+-----------+
| eeb574ce-f49a-48b6-820d-b2959fcd38bb | mysql-5.5 |
+--------------------------------------+-----------+
Pass in the data store version ID with the
:command:`trove configuration-parameter-list` command to get the available
options:
.. code-block:: console
$ trove configuration-parameter-list DATASTORE_VERSION_ID
+--------------------------------+---------+---------+----------------------+------------------+
| name | type | min | max | restart_required |
+--------------------------------+---------+---------+----------------------+------------------+
| auto_increment_increment | integer | 1 | 65535 | False |
| auto_increment_offset | integer | 1 | 65535 | False |
| autocommit | integer | 0 | 1 | False |
| bulk_insert_buffer_size | integer | 0 | 18446744073709547520 | False |
| character_set_client | string | | | False |
| character_set_connection | string | | | False |
| character_set_database | string | | | False |
| character_set_filesystem | string | | | False |
| character_set_results | string | | | False |
| character_set_server | string | | | False |
| collation_connection | string | | | False |
| collation_database | string | | | False |
| collation_server | string | | | False |
| connect_timeout | integer | 1 | 65535 | False |
| expire_logs_days | integer | 1 | 65535 | False |
| innodb_buffer_pool_size | integer | 0 | 68719476736 | True |
| innodb_file_per_table | integer | 0 | 1 | True |
| innodb_flush_log_at_trx_commit | integer | 0 | 2 | False |
| innodb_log_buffer_size | integer | 1048576 | 4294967296 | True |
| innodb_open_files | integer | 10 | 4294967296 | True |
| innodb_thread_concurrency | integer | 0 | 1000 | False |
| interactive_timeout | integer | 1 | 65535 | False |
| join_buffer_size | integer | 0 | 4294967296 | False |
| key_buffer_size | integer | 0 | 4294967296 | False |
| local_infile | integer | 0 | 1 | False |
| max_allowed_packet | integer | 1024 | 1073741824 | False |
| max_connect_errors | integer | 1 | 18446744073709547520 | False |
| max_connections | integer | 1 | 65535 | False |
| max_user_connections | integer | 1 | 100000 | False |
| myisam_sort_buffer_size | integer | 4 | 18446744073709547520 | False |
| server_id | integer | 1 | 100000 | True |
| sort_buffer_size | integer | 32768 | 18446744073709547520 | False |
| sync_binlog | integer | 0 | 18446744073709547520 | False |
| wait_timeout | integer | 1 | 31536000 | False |
+--------------------------------+---------+---------+----------------------+------------------+
In this example, the :command:`trove configuration-parameter-list` command
returns a list of options that work with MySQL 5.5.
#. **Create a configuration group**
A configuration group contains a comma-separated list of key-value
pairs. Each pair consists of a configuration option and its value.
You can create a configuration group by using the
:command:`trove configuration-create` command. The general syntax
for this command is:
.. code-block:: console
$ trove configuration-create NAME VALUES --datastore DATASTORE_NAME
- *NAME*. The name you want to use for this group.
- *VALUES*. The list of key-value pairs.
- *DATASTORE_NAME*. The name of the associated data store.
Set *VALUES* as a JSON dictionary, for example:
.. code-block:: json
{"myFirstKey" : "someString", "mySecondKey" : 1}
This example creates a configuration group called ``group1``.
``group1`` contains just one key and value pair, and this pair sets
the ``sync_binlog`` option to ``1``.
.. code-block:: console
$ trove configuration-create group1 '{"sync_binlog" : 1}' --datastore mysql
+----------------------+--------------------------------------+
| Property | Value |
+----------------------+--------------------------------------+
| datastore_version_id | eeb574ce-f49a-48b6-820d-b2959fcd38bb |
| description | None |
| id | 9a9ef3bc-079b-476a-9cbf-85aa64f898a5 |
| name | group1 |
| values | {"sync_binlog": 1} |
+----------------------+--------------------------------------+
#. **Examine your existing configuration**
Before you use the newly-created configuration group, look at how the
``sync_binlog`` option is configured on your database. Replace the
following sample connection values with values that connect to your
database:
.. code-block:: console
$ mysql -u user7 -ppassword -h 172.16.200.2 myDB7
Welcome to the MySQL monitor. Commands end with ; or \g.
...
mysql> show variables like 'sync_binlog';
+---------------+-------+
| Variable_name | Value |
+---------------+-------+
| sync_binlog | 0 |
+---------------+-------+
As you can see, the ``sync_binlog`` option is currently set to ``0``
for the ``myDB7`` database.
#. **Change the database configuration using a configuration group**
You can change a database's configuration by attaching a
configuration group to a database instance. You do this by using the
:command:`trove configuration-attach` command and passing in the ID of the
database instance and the ID of the configuration group.
Get the ID of the database instance:
.. code-block:: console
$ trove list
+-------------+------------------+-----------+-------------------+--------+-----------+------+
| id | name | datastore | datastore_version | status | flavor_id | size |
+-------------+------------------+-----------+-------------------+--------+-----------+------+
| 26a265dd... | mysql_instance_7 | mysql | mysql-5.5 | ACTIVE | 6 | 5 |
+-------------+------------------+-----------+-------------------+--------+-----------+------+
Get the ID of the configuration group:
.. code-block:: console
$ trove configuration-list
+-------------+--------+-------------+---------------------+
| id | name | description |datastore_version_id |
+-------------+--------+-------------+---------------------+
| 9a9ef3bc... | group1 | None | eeb574ce... |
+-------------+--------+-------------+---------------------+
Attach the configuration group to the database instance:
.. note::
This command syntax pertains only to python-troveclient version
1.0.6 and later. Earlier versions require you to pass in the
configuration group ID as the first argument.
.. code-block:: console
$ trove configuration-attach DB_INSTANCE_ID CONFIG_GROUP_ID
#. **Re-examine the database configuration**
Display the ``sync_binlog`` setting again:
.. code-block:: console
mysql> show variables like 'sync_binlog';
+---------------+-------+
| Variable_name | Value |
+---------------+-------+
| sync_binlog | 1 |
+---------------+-------+
As you can see, the ``sync_binlog`` option is now set to ``1``, as
specified in the ``group1`` configuration group.
**Conclusion.** Using a configuration group to set a single option on
a single database is obviously a trivial example. However, configuration
groups can provide major efficiencies when you consider that:
- A configuration group can specify a large number of option values.
- You can apply a configuration group to hundreds or thousands of
database instances in your environment.
Used in this way, configuration groups let you modify your database
cloud configuration, on the fly, on a massive scale.
**Maintenance.** There are also a number of useful maintenance
features for working with configuration groups. You can:
- Disassociate a configuration group from a database instance, using
the :command:`trove configuration-detach` command.
- Modify a configuration group on the fly, using the
:command:`trove configuration-patch` command.
- Find out what instances are using a configuration group, using the
:command:`trove configuration-instances` command.
- Delete a configuration group, using the
:command:`trove configuration-delete` command. You might want to
do this if no instances use a group.

168
doc/source/user/set-up-clustering.rst Normal file
View File

@ -0,0 +1,168 @@
==========================
Set up database clustering
==========================
You can store data across multiple machines by setting up MongoDB
sharded clusters.
Each cluster includes:
- One or more *shards*. Each shard consists of a three member replica
set (three instances organized as a replica set).
- One or more *query routers*. A query router is the machine that your
application actually connects to. This machine is responsible for
communicating with the config server to figure out where the
requested data is stored. It then accesses and returns the data from
the appropriate shard(s).
- One or more *config servers*. Config servers store the metadata that
links requested data with the shard that contains it.
This example shows you how to set up a MongoDB sharded cluster.
.. note::
**Before you begin.** Make sure that:
- The administrative user has registered a MongoDB datastore type and
version.
- The administrative user has created an appropriate :ref:`flavor that
meets the MongoDB minimum requirements <create_db>`.
Set up clustering
~~~~~~~~~~~~~~~~~
#. **Create a cluster**
Create a cluster by using the :command:`trove cluster-create` command. This
command creates a one-shard cluster. Pass in:
- The name of the cluster.
- The name and version of the datastore you want to use.
- The three instances you want to include in the replication set for
the first shard. Specify each instance by using the ``--instance``
argument and the associated flavor ID and volume size. Use the
same flavor ID and volume size for each instance. In this example,
flavor ``7`` is a custom flavor that meets the MongoDB minimum
requirements.
.. code-block:: console
$ trove cluster-create cluster1 mongodb "2.4" \
--instance flavor=7,volume=2 --instance flavor=7,volume=2 \
--instance flavor=7,volume=2
+-------------------+--------------------------------------+
| Property | Value |
+-------------------+--------------------------------------+
| created | 2014-08-16T01:46:51 |
| datastore | mongodb |
| datastore_version | 2.4 |
| id | aa6ef0f5-dbef-48cd-8952-573ad881e717 |
| name | cluster1 |
| task_description | Building the initial cluster. |
| task_name | BUILDING |
| updated | 2014-08-16T01:46:51 |
+-------------------+--------------------------------------+
#. **Display cluster information**
Display information about a cluster by using the
:command:`trove cluster-show` command. Pass in the ID of the cluster.
The cluster ID displays when you first create a cluster. (If you need
to find it later on, use the :command:`trove cluster-list` command to list
the names and IDs of all the clusters in your system.)
.. code-block:: console
$ trove cluster-show CLUSTER_ID
+-------------------+--------------------------------------+
| Property | Value |
+-------------------+--------------------------------------+
| created | 2014-08-16T01:46:51 |
| datastore | mongodb |
| datastore_version | 2.4 |
| id | aa6ef0f5-dbef-48cd-8952-573ad881e717 |
| ip | 10.0.0.2 |
| name | cluster1 |
| task_description | No tasks for the cluster. |
| task_name | NONE |
| updated | 2014-08-16T01:59:33 |
+-------------------+--------------------------------------+
.. note::
**Your application connects to this IP address.** The :command:`trove cluster-show`
command displays the IP address of the query router.
This is the IP address your application uses to retrieve data from
the database.
#. **List cluster instances**
List the instances in a cluster by using the
:command:`trove cluster-instances` command.
.. code-block:: console
$ trove cluster-instances CLUSTER_ID
+--------------------------------------+----------------+-----------+------+
| ID | Name | Flavor ID | Size |
+--------------------------------------+----------------+-----------+------+
| 45532fc4-661c-4030-8ca4-18f02aa2b337 | cluster1-rs1-1 | 7 | 2 |
| 7458a98d-6f89-4dfd-bb61-5cf1dd65c121 | cluster1-rs1-2 | 7 | 2 |
| b37634fb-e33c-4846-8fe8-cf2b2c95e731 | cluster1-rs1-3 | 7 | 2 |
+--------------------------------------+----------------+-----------+------+
**Naming conventions for replication sets and instances.** Note
that the ``Name`` column displays an instance name that includes the
replication set name. The replication set names and instance names
are automatically generated, following these rules:
- **Replication set name.** This name consists of the cluster
name, followed by the string -rs\ *n*, where *n* is 1 for
the first replication set you create, 2 for the second replication
set, and so on. In this example, the cluster name is ``cluster1``,
and there is only one replication set, so the replication set name
is ``cluster1-rs1``.
- **Instance name.** This name consists of the replication set
name followed by the string -*n*, where *n* is 1 for the
first instance in a replication set, 2 for the second
instance, and so on. In this example, the instance names are
``cluster1-rs1-1``, ``cluster1-rs1-2``, and ``cluster1-rs1-3``.
#. **List clusters**
List all the clusters in your system, using the
:command:`trove cluster-list` command.
.. code-block:: console
$ trove cluster-list
+--------------------------------------+----------+-----------+-------------------+-----------+
| ID | Name | Datastore | Datastore Version | Task Name |
+--------------------------------------+----------+-----------+-------------------+-----------+
| aa6ef0f5-dbef-48cd-8952-573ad881e717 | cluster1 | mongodb | 2.4 | NONE |
| b8829c2a-b03a-49d3-a5b1-21ec974223ee | cluster2 | mongodb | 2.4 | BUILDING |
+--------------------------------------+----------+-----------+-------------------+-----------+
#. **Delete a cluster**
Delete a cluster, using the :command:`trove cluster-delete` command.
.. code-block:: console
$ trove cluster-delete CLUSTER_ID
Query routers and config servers
--------------------------------
Each cluster includes at least one query router and one config server.
Query routers and config servers count against your quota. When you
delete a cluster, the system deletes the associated query router(s) and
config server(s).

109
doc/source/user/set-up-replication.rst Normal file
View File

@ -0,0 +1,109 @@
===========================
Set up database replication
===========================
You can create a replica of an existing database instance. When you make
subsequent changes to the original instance, the system automatically
applies those changes to the replica.
- Replicas are read-only.
- When you create a replica, do not specify the ``--users`` or
``--databases`` options.
- You can choose a smaller volume or flavor for a replica than for the
original, but the replica's volume must be big enough to hold the
data snapshot from the original.
This example shows you how to replicate a MySQL database instance.
Set up replication
~~~~~~~~~~~~~~~~~~
#. **Get the instance ID**
Get the ID of the original instance you want to replicate:
.. code-block:: console
$ trove list
+-----------+------------+-----------+-------------------+--------+-----------+------+
| id | name | datastore | datastore_version | status | flavor_id | size |
+-----------+------------+-----------+-------------------+--------+-----------+------+
| 97b...ae6 | base_1 | mysql | mysql-5.5 | ACTIVE | 10 | 2 |
+-----------+------------+-----------+-------------------+--------+-----------+------+
#. **Create the replica**
Create a new instance that will be a replica of the original
instance. You do this by passing in the ``--replica_of`` option with
the :command:`trove create` command. This example creates a replica
called ``replica_1``. ``replica_1`` is a replica of the original instance,
``base_1``:
.. code-block:: console
$ trove create replica_1 6 --size=5 --datastore_version mysql-5.5 \
--datastore mysql --replica_of ID_OF_ORIGINAL_INSTANCE
#. **Verify replication status**
Pass in ``replica_1``'s instance ID with the :command:`trove show` command
to verify that the newly created ``replica_1`` instance is a replica
of the original ``base_1``. Note that the ``replica_of`` property is
set to the ID of ``base_1``.
.. code-block:: console
$ trove show INSTANCE_ID_OF_REPLICA_1
+-------------------+--------------------------------------+
| Property | Value |
+-------------------+--------------------------------------+
| created | 2014-09-16T11:16:49 |
| datastore | mysql |
| datastore_version | mysql-5.5 |
| flavor | 6 |
| id | 49c6eff6-ef91-4eff-91c0-efbda7e83c38 |
| name | replica_1 |
| replica_of | 97b4b853-80f6-414f-ba6f-c6f455a79ae6 |
| status | BUILD |
| updated | 2014-09-16T11:16:49 |
| volume | 5 |
+-------------------+--------------------------------------+
Now pass in ``base_1``'s instance ID with the :command:`trove show` command
to list the replica(s) associated with the original instance. Note
that the ``replicas`` property is set to the ID of ``replica_1``. If
there are multiple replicas, they appear as a comma-separated list.
.. code-block:: console
$ trove show INSTANCE_ID_OF_BASE_1
+-------------------+--------------------------------------+
| Property | Value |
+-------------------+--------------------------------------+
| created | 2014-09-16T11:04:56 |
| datastore | mysql |
| datastore_version | mysql-5.5 |
| flavor | 6 |
| id | 97b4b853-80f6-414f-ba6f-c6f455a79ae6 |
| ip | 172.16.200.2 |
| name | base_1 |
| replicas | 49c6eff6-ef91-4eff-91c0-efbda7e83c38 |
| status | ACTIVE |
| updated | 2014-09-16T11:05:06 |
| volume | 5 |
| volume_used | 0.11 |
+-------------------+--------------------------------------+
#. **Detach the replica**
If the original instance goes down, you can detach the replica. The
replica becomes a standalone database instance. You can then take the
new standalone instance and create a new replica of that instance.
You detach a replica using the :command:`trove detach-replica` command:
.. code-block:: console
$ trove detach-replica INSTANCE_ID_OF_REPLICA