From 26635039306bf113bbc60e69c225a50a7cc6c98b Mon Sep 17 00:00:00 2001
From: Dariusz Krol <d.krol@samsung.com>
Date: Tue, 29 Jan 2019 21:11:35 +0100
Subject: [PATCH] Add documentation for managing databases and users

New entry added as an RST file with examples showing how to
create and manage users and databases on Trove instances
using Trove API.

Change-Id: I565f3b4d7c215c9508de127f1781638531d6fb45
Signed-off-by: Dariusz Krol <dkrol3@gmail.com>
Signed-off-by: Dariusz Krol <d.krol@samsung.com>
---
 doc/source/user/index.rst               |   1 +
 doc/source/user/manage-db-and-users.rst | 150 ++++++++++++++++++++++++
 2 files changed, 151 insertions(+)
 create mode 100644 doc/source/user/manage-db-and-users.rst

diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst
index 4392664b10..e65cd5d65c 100644
--- a/doc/source/user/index.rst
+++ b/doc/source/user/index.rst
@@ -11,6 +11,7 @@ handling complex administrative tasks.
    :maxdepth: 1
 
    create-db.rst
+   manage-db-and-users.rst
    backup-db.rst
    backup-db-incremental.rst
    manage-db-config.rst
diff --git a/doc/source/user/manage-db-and-users.rst b/doc/source/user/manage-db-and-users.rst
new file mode 100644
index 0000000000..38a80442dc
--- /dev/null
+++ b/doc/source/user/manage-db-and-users.rst
@@ -0,0 +1,150 @@
+=============================================
+Manage databases and users on Trove instances
+=============================================
+
+Assume that you installed Trove service and uploaded images with datastore
+of your choice.
+This section shows how to manage users and databases in a MySQL 5.7 instance.
+
+Add new database and user to an existing Trove instance
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Trove provides API to manage users and databases on
+datastores including relational (e.g. MySQL, PostgreSQL) and non-relational
+(e.g. Redis, Cassandra). Once a Trove instance with a datastore of choice is
+active you can use Trove API to create new databases and/or users.
+
+.. code-block:: console
+
+  $ openstack database user list db-instance
+
+    +------+------+-----------+
+    | Name | Host | Databases |
+    +------+------+-----------+
+    | test | %    | testdb    |
+    +------+------+-----------+
+
+  $ openstack database user create db-instance newuser userpass --databases testdb
+
+  $ openstack database user list db-instance
+
+    +---------+------+-----------+
+    | Name    | Host | Databases |
+    +---------+------+-----------+
+    | newuser | %    | testdb    |
+    | test    | %    | testdb    |
+    +---------+------+-----------+
+
+
+  $ mysql -h 172.24.4.199 -u newuser -p testdb
+    Enter password:
+
+    mysql> show databases;
+
+    +--------------------+
+    | Database           |
+    +--------------------+
+    | information_schema |
+    | testdb             |
+    +--------------------+
+
+    2 rows in set (0.00 sec)
+
+
+  $ openstack database db create db-instance newdb
+
+
+  $ openstack database db list db-instance
+
+    +--------+
+    | Name   |
+    +--------+
+    | newdb  |
+    | sys    |
+    | testdb |
+    +--------+
+
+  $ mysql -h 172.24.4.199 -u newuser -p newdb
+
+    Enter password:
+    ERROR 1044 (42000): Access denied for user 'newuser'@'%' to database 'newdb'
+
+
+Manage access to databases
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+With Trove API you can grant and revoke database access rights for existing users.
+
+.. code-block:: console
+
+  $ openstack database user grant access db-instance newuser newdb
+
+
+  $ openstack database user show access db-instance newuser
+
+    +--------+
+    | Name   |
+    +--------+
+    | newdb  |
+    | testdb |
+    +--------+
+
+  $ mysql -h IP_ADDRESS -u newuser -p newdb
+    Enter password:
+
+
+  $ openstack database user show access db-instance test
+
+    +--------+
+    | Name   |
+    +--------+
+    | testdb |
+    +--------+
+
+  $ mysql -h IP_ADDRESS -u test -p newdb
+    Enter password:
+
+    ERROR 1044 (42000): Access denied for user 'test'@'%' to database 'newdb'
+
+
+  $ openstack database user revoke access db-instance newuser newdb
+
+
+  $ mysql -h IP_ADDRESS -u newuser -p newdb
+    Enter password:
+
+    ERROR 1044 (42000): Access denied for user 'newuser'@'%' to database 'newdb'
+
+
+Delete databases
+~~~~~~~~~~~~~~~~
+
+Lastly, Trove provides API for deleting databases.
+
+.. code-block:: console
+
+  $ openstack database db list db-instance
+
+    +--------+
+    | Name   |
+    +--------+
+    | newdb  |
+    | sys    |
+    | testdb |
+    +--------+
+
+  $ openstack database db delete db-instance testdb
+
+  $ openstack database db list db-instance
+
+    +--------+
+    | Name   |
+    +--------+
+    | newdb  |
+    | sys    |
+    +--------+
+
+  $ mysql -h IP_ADDRESS -u test -p testdb
+    Enter password:
+
+    ERROR 1049 (42000): Unknown database 'testdb'
\ No newline at end of file