Managing configuration groups for Cloud Databases with the trove command-line tool


Settings for Cloud Databases instances can be saved and managed in configuration groups using the Cloud Databases API or the python-troveclient command-line interace for the API.

This article describes the commands that can be run with python-troveclient to manage configuration groups.

Configuration groups and configuration parameters

A configuration group is a collection of settings that can be saved and applied to one or more instances in Cloud Databases.

A configuration group consists or one or more configuration parameters, which represent options that can be applied to a datastore (the database running in an instance). For example, a configuration group could have a configuration parameter of max_connections set to 80, or could set the default time zone for the instance with the default_time_zone parameter.

Installing python-troveclient

The python-troveclient package installs the trove command using the Python package manager tool pip.

Full installation instructions for the trove tool are in the Cloud Databases getting started guide.

Further documentation for the trove tool can be found on the python-troveclient project site.

To see a full list of commands after python-troveclient is installed, run:

trove help

Command options

Some options used by the commands in this article require further explanation or have specific requirements.

value_pairs

The value_pairs option represents one or more parameter name and value pairs. The entry should be in JSON object format, enclosed in single quotes with no spaces (curly brackets enclosing one or more key pairs representing configuration values, with commas separating multiple pairs).

The name of the parameter should be enclosed in quotes, as should any string or character value type.

For example, one name and value pair would look like this:

'{"collation_server":"latin1_swedish_ci"}'

And to list two or more pairs in the same option, separate them with a comma like this:

'{"collation_server":"latin1_swedish_ci","max_connections":5000}'

Note that you may need to use the configuration-parameter-show command to get the value type of a parameter to make sure you set it correctly. If you need to set the key_buffer_size parameter, for example, that's an integer representing bytes. If you you want to set it to 100 megabytes, you would need to set its value to an integer representing that many bytes (104857600).

datastore_type

The datastore_type option refers to a valid datastore (database engine) type that can be run on an instance. It's best to use the ID of the datastore type as listed in the output of the datastore-list command, though often the name of the datastore type will work as well.

trove datastore-list

datastore_version

The datastore_version option refers to a valid version of a datastore that can be run on an instance. It's best to use the ID of the datastore version as listed in the output of the datastore-version-list command, though often the name of the datastore version will work as well.

trove datastore-version-list <datastore>

Configuration groups and parameters are associated with a datastore version they can be applied to.

config_id

The config_id option refers to the ID of an existing configuration group. You can see a list of configuration groups and their IDs with the configuration-list command.

trove configuration-list

instance_id

The instance_id option refers to the ID of an existing instance. You can see a list of instances and their IDs with the list command.

trove list

flavor

The flavor option refers to the ID of an instance flavor, which typically refers to the size of the instance determined by its allocation memory (for example, the "1GB flavor" refers to an instance with 1GB of memory). You can see a list of flavors and their IDs with the flavor-list command.

trove flavor-list

Creating and removing configuration groups

Create a new configuration group

Use the configuration-create command to create a new configuration group.

trove configuration-create <name> <value_pairs> [--datastore <datastore_type>] [--datastore_version <datastore_version>] [--description <description>]

For example, a configuration group named Stagingconfig could be created with the following key value pairs:

Key Value
collation_server latin1_swedish_ci
max_connections 80

To create the configuration group, you would run the command:

trove configuration-create Stagingconfig '{"collation_server":"latin1_swedish_ci","max_connections":5000}' --description "Config for Staging datastore" --datastore MySQL --datastore_version 5.1 

The output would display a list of the new configuration group's properties.

+----------------------+-----------------------------------------------------------------------+
|       Property       |                                 Value                                 |
+----------------------+-----------------------------------------------------------------------+
| datastore_version_id |                  4f83ff38-3ef3-4a27-8b4c-330dc59857ca                 |
|     description      |                                  Config for Staging |
|          id          |                  b52de6cc-5c4f-4deb-afbc-f7190ee7573b                 |$
|         name         |                             Stagingconfig                             |
|        values        | {u'collation_server': u'latin1_swedish_ci', u'max_connections': 80} |
+----------------------+-----------------------------------------------------------------------+

For a detailed example of creating and applying a configuration group, see setting the time zone for a Cloud Databases instance.

Delete a configuration group

Use the configuration-delete command to delete a configuration group.

trove configuration-delete <config_id>

Applying configuration groups to instances

A configuration group can be assigned when an instance is created or it can be assigned to an existing instance. If applied to a running instance the configuration parameters can affect the datastore's behavior immediately, though some configuration changes require that the datastore be restarted.

Apply a configuration group to an existing instance

Use the configuration-attach command to assign a configuration group to an existing instance.

trove configuration-attach <config_id> <instance_id>

You can confirm that the configuration group was applied by fetching instance details with the show command.

trove show <instance_id> 

The show command returns the properties of the instance, including an applied configuration group's ID.

+-------------------+------------------------------------------------------------------+
|      Property     |                              Value                               |
+-------------------+------------------------------------------------------------------+
|   configuration   |               b52de6cc-5c4f-4deb-afbc-f7190ee7573b               |
|      created      |                       2014-03-15T21:44:05                        |
|     datastore     |                              MySQL                               |
| datastore_version |                               5.1                                |
|       flavor      |                                1                                 |
|      hostname     | 6a169ada29c30d2338e0395d277a817a2f7a37e5.qa.rackspaceclouddb.com |
|         id        |               aab79eba-9eba-4ac3-94fc-e4aaf46b4efb               |
|        name       |                            CloudDBdev                            |
|       status      |                              ACTIVE                              |
|      updated      |                       2014-03-15T21:44:55                        |
|       volume      |                                1                                 |
+-------------------+------------------------------------------------------------------+

Create a new instance with a configuration group

Use the create command to create a new instance using a custom configuration group.

trove create <name> <flavor> [--size <size>] [--databases <databases> [<databases> ...]] [--users <users> [<users> ...]] [--backup <backup>] [--availability_zone <availability_zone>] [--configuration <config_id>]

To create an instance named CloudDB using the 1GB instance flavor (flavor ID 1), a 1 GB volume size, and a configuration group named Devconfig with an ID of 26f6f753-3853-4bf5-9bfe-1765966ad2f6, we would run the command:

trove create CloudDB 1 --size 1 --configuration 26f6f753-3853-4bf5-9bfe-1765966ad2f6

The output displays the properties of the new instance.

+-------------------+------------------------------------------------------------------+
|      Property     |                              Value                               |
+-------------------+------------------------------------------------------------------+
|   configuration   |               26f6f753-3853-4bf5-9bfe-1765966ad2f6               |
|      created      |                       2014-03-15T21:37:32                        |
|     datastore     |                              MySQL                               |
| datastore_version |                               5.1                                |
|       flavor      |                                1                                 |
|      hostname     | 9bcc18abea9a8b97bc8889ff901a446f297a86ac.qa.rackspaceclouddb.com |
|         id        |               a920662c-0074-4369-83d4-e2e159f2ed6c               |
|        name       |                             CloudDB                              |
|       status      |                              BUILD                               |
|      updated      |                       2014-03-15T21:37:32                        |
|       volume      |                                1                                 |
+-------------------+------------------------------------------------------------------+

Remove the configuration group from an instance

The configuration-detach command will clear the configuration assigned to an instance and restore the instance to its datastore's default configuration.

trove configuration-detach <instance_id>

Modifying configuration groups

When changing a configuration group's parameters, you can either change only specific parameters without affecting others in the set or replace the whole configuration set with new values.

Change a subset of the parameters of a configuration group

Use the configuration-patch command to change only the specified parameters for a configuration group.

trove configuration-patch <config_id> <value_pairs>

For example, to update configuration parameter max_connections to 80 for the configuration group Stagingconfig, you could run the command using Stagingconfig's ID:

trove configuration-patch b52de6cc-5c4f-4deb-afbc-f7190ee7573b '{"max_connections":80}'

To verify that the configuration group got updated, use the command

trove configuration-show <config_id>

The command returns the properties of the configuration group.

+----------------------+---------------------------------------------------------------------+
|       Property       |                                Value                                |
+----------------------+---------------------------------------------------------------------+
| datastore_version_id |                 4f83ff38-3ef3-4a27-8b4c-330dc59857ca                |
|     description      |                                 None                                |
|          id          |                 b52de6cc-5c4f-4deb-afbc-f7190ee7573b                |
|         name         |                            Stagingconfig                            |
|        values        | {u'collation_server': u'latin1_swedish_ci', u'max_connections': 80} |
+----------------------+---------------------------------------------------------------------+

Note that the other parameter set on the group, collation_server, is unaffected by the change.

Replace all parameters of a configuration group

Use the configuration-update command to replace all existing parameters of a configuration group with the supplied values. Any existing values that are not included in the command will be removed from the group.

trove configuration-update <config_id> <value_pairs> [--name <name>] [--description <description>]

For example, we might start with an existing group with two values set, character_set_server and max_connections, as in the following table.

Key Value
character_set_server utf8
max_connections 80

If we run configuration-update to set a value for just character_set_server, the max_connections parameter will be removed.

trove configuration-update b52de6cc-5c4f-4deb-afbc-f7190ee7573b '{"character_set_server":"latin1"}' --description UpdatedStagingConfig

After that command runs, the output will show that the only value pair set is for character_set_server.

+----------------------+--------------------------------------+
|       Property       |                Value                 |
+----------------------+--------------------------------------+
| datastore_version_id | 4f83ff38-3ef3-4a27-8b4c-330dc59857ca |
|     description      |         UpdatedStagingConfig         |
|          id          | b52de6cc-5c4f-4deb-afbc-f7190ee7573b |
|         name         |            Stagingconfig             |
|        values        | {u'character_set_server': u'latin1'} |
+----------------------+--------------------------------------+

Listing configuration groups

View all defined and available configuration groups

Use the configuration-list command to list all configuration groups currently defined and available.

trove configuration-list

The output would look like:

+--------------------------------------+--------------------+---------------------------+--------------------------------------+
|                  id                  |        name        |        description        |         datastore_version_id         |
+--------------------------------------+--------------------+---------------------------+--------------------------------------+
| 0e860b09-60fe-433b-8ead-b9e5371a370c | test_configuration | configuration description | 4f83ff38-3ef3-4a27-8b4c-330dc59857ca |
| 26f6f753-3853-4bf5-9bfe-1765966ad2f6 |     Devconfig      |        Config for dev env | 4f83ff38-3ef3-4a27-8b4c-330dc59857ca |
| 321934e8-693e-41ed-ace8-de56747c3275 |     devconfig      |     Config for dev env    | 4f83ff38-3ef3-4a27-8b4c-330dc59857ca |
| b52de6cc-5c4f-4deb-afbc-f7190ee7573b |   Stagingconfig    |    UpdatedStagingConfig   | 4f83ff38-3ef3-4a27-8b4c-330dc59857ca |
+--------------------------------------+--------------------+---------------------------+--------------------------------------+

View all instances associated with a configuration group

Use the configuration-instances command to list all instances a configuration group is assigned to.

trove configuration-instances <config_id>

The output would look like:

+--------------------------------------+----------------+
|                  id                  |      name      |
+--------------------------------------+----------------+
| a920662c-0074-4369-83d4-e2e159f2ed6c |    CloudDB     |
| c46a0bba-6c15-4db5-ad7b-832ee2c0b59d | CloudDBStaging |
+--------------------------------------+----------------+

Viewing configuration details

View details of a configuration group

Use the configuration-show command to view the details of a configuration group, including name, ID, the datastore version ID it's associated with, and any defined parameters.

trove configuration-show <config_id>

The output would look like:

+----------------------+-----------------------------------------------------------------------+
|       Property       |                                 Value                                 |
+----------------------+-----------------------------------------------------------------------+
| datastore_version_id |                  4f83ff38-3ef3-4a27-8b4c-330dc59857ca                 |
|     description      |                                  Config for Staging env                                 |
|          id          |                  b52de6cc-5c4f-4deb-afbc-f7190ee7573b                 |
|         name         |                             Stagingconfig                             |
|        values        | {u'collation_server': u'latin1_swedish_ci', u'max_connections': 50} |
+----------------------+-----------------------------------------------------------------------+

View properties for a single configuration parameter that can be configured for a datastore version

Use the configuration-parameter-show command to view the properties of a configuration parameter for a datastore version.

trove configuration-parameter-show <datastore_version> <parameter_name>

The output will display the parameter's value range, value type, and whether a restart of the instance would be required in order for a parameter change to take effect.

The output for the innodb_buffer_pool_size parameter for MySQL 5.1 would look like this:

+------------------+-------------------------+
|     Property     |          Value          |
+------------------+-------------------------+
|       max        |       68719476736       |
|       min        |            0            |
|       name       | innodb_buffer_pool_size |
| restart_required |           True          |
|       type       |         integer         |
+------------------+-------------------------+

View all configuration parameters that can be configured for a datastore version

Use the configuration-parameter-list command to view a list of all parameters that can be configured for a datastore version.

trove configuration-parameter-list <datastore_version>

The output would look like:

+--------------------------------+---------+---------+----------------------+------------------+
|              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       |
+--------------------------------+---------+---------+----------------------+------------------+

View the default configuration settings for a specific instance

Use the configuration-default command to view the default configuration settings for an instance.

trove configuration-default <instance_id>

The output would look like:

+---------------------------+-----------------------------+
|          Property         |            Value            |
+---------------------------+-----------------------------+
|          basedir          |             /usr            |
|      connect_timeout      |              15             |
|          datadir          |        /var/lib/mysql       |
|   default_storage_engine  |            innodb           |
|   ignore-builtin-innodb   |              1              |
|           innodb          |            FORCE            |
|  innodb_buffer_pool_size  |             125M            |
|   innodb_data_file_path   |    ibdata1:10M:autoextend   |
|   innodb_file_per_table   |              1              |
|   innodb_log_buffer_size  |              4M             |
|    innodb_log_file_size   |             50M             |
| innodb_log_files_in_group |              2              |
|      join_buffer_size     |              1M             |
|      key_buffer_size      |             40M             |
|        local-infile       |              0              |
|         log_error         |  /var/log/mysql/mysqld.log  |
|     max_allowed_packet    |             16M             |
|      max_connections      |              85             |
|    max_heap_table_size    |             12M             |
|    max_user_connections   |              75             |
|       myisam-recover      |            BACKUP           |
|      open_files_limit     |             3276            |
|        plugin-load        |     ha_innodb_plugin.so     |
|            port           |             3306            |
|     query_cache_limit     |              1M             |
|      query_cache_size     |              8M             |
|      query_cache_type     |              1              |
|      read_buffer_size     |             512K            |
|    read_rnd_buffer_size   |             512K            |
|   skip-external-locking   |              1              |
|     skip_name_resolve     |              1              |
|           socket          | /var/run/mysqld/mysqld.sock |
|      sort_buffer_size     |              1M             |
|   table_definition_cache  |             200             |
|      table_open_cache     |             200             |
|     thread_cache_size     |              4              |
|        thread_stack       |             192K            |
|       tmp_table_size      |             12M             |
|           tmpdir          |           /var/tmp          |
|            user           |            mysql            |
|        wait_timeout       |             120             |
+---------------------------+-----------------------------+


Was this content helpful?




© 2011-2013 Rackspace US, Inc.

Except where otherwise noted, content on this site is licensed under a Creative Commons Attribution-NonCommercial-NoDerivs 3.0 Unported License


See license specifics and DISCLAIMER