From 4d99ae4bb343ef62b6640038930b72f3fc577ad4 Mon Sep 17 00:00:00 2001 From: chenxing Date: Fri, 13 Oct 2017 09:49:04 +0800 Subject: [PATCH] Add Database service user guide import the trove user guide from openstack-manuals Closes-Bug: #1731209 Change-Id: I939e88bfb88234045b0a8b00ee0d6d623c6b10d1 --- doc/source/index.rst | 7 +- doc/source/user/backup-db-incremental.rst | 127 ++++++++++++ doc/source/user/backup-db.rst | 232 +++++++++++++++++++++ doc/source/user/create-db.rst | 176 ++++++++++++++++ doc/source/user/index.rst | 18 ++ doc/source/user/manage-db-config.rst | 239 ++++++++++++++++++++++ doc/source/user/set-up-clustering.rst | 168 +++++++++++++++ doc/source/user/set-up-replication.rst | 109 ++++++++++ 8 files changed, 1073 insertions(+), 3 deletions(-) create mode 100644 doc/source/user/backup-db-incremental.rst create mode 100644 doc/source/user/backup-db.rst create mode 100644 doc/source/user/create-db.rst create mode 100644 doc/source/user/index.rst create mode 100644 doc/source/user/manage-db-config.rst create mode 100644 doc/source/user/set-up-clustering.rst create mode 100644 doc/source/user/set-up-replication.rst diff --git a/doc/source/index.rst b/doc/source/index.rst index d3217843f6..ccadc82a50 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -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 diff --git a/doc/source/user/backup-db-incremental.rst b/doc/source/user/backup-db-incremental.rst new file mode 100644 index 0000000000..cd08792532 --- /dev/null +++ b/doc/source/user/backup-db-incremental.rst @@ -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} | + +-------------------+-----------------------------------------------------------+ + diff --git a/doc/source/user/backup-db.rst b/doc/source/user/backup-db.rst new file mode 100644 index 0000000000..cb7f26f2b2 --- /dev/null +++ b/doc/source/user/backup-db.rst @@ -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 + diff --git a/doc/source/user/create-db.rst b/doc/source/user/create-db.rst new file mode 100644 index 0000000000..30c6cd27ac --- /dev/null +++ b/doc/source/user/create-db.rst @@ -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 ` 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 + diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst new file mode 100644 index 0000000000..4392664b10 --- /dev/null +++ b/doc/source/user/index.rst @@ -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 diff --git a/doc/source/user/manage-db-config.rst b/doc/source/user/manage-db-config.rst new file mode 100644 index 0000000000..d9f4711d92 --- /dev/null +++ b/doc/source/user/manage-db-config.rst @@ -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. + diff --git a/doc/source/user/set-up-clustering.rst b/doc/source/user/set-up-clustering.rst new file mode 100644 index 0000000000..5097a5bfdf --- /dev/null +++ b/doc/source/user/set-up-clustering.rst @@ -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 `. + +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). diff --git a/doc/source/user/set-up-replication.rst b/doc/source/user/set-up-replication.rst new file mode 100644 index 0000000000..18610471d0 --- /dev/null +++ b/doc/source/user/set-up-replication.rst @@ -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