DOCSP-39033 Database Connection Management (#178)

* Topic stubs

* Rebuild

* Rebuild

* Copy edits

* Draft

* Tabbed procedure

* Wording and syntax

* Rendering fix

* Checking link rendering

* Rendering

* Rendering check

* Rendering

* Rendering

* Formatting

* Test connection step

* Partial tabbing

* Tabs

* Whitespace

* Typo

* Typo

* Whitespace

* Wording from sync job to migration job

* self hosted wording to on premises

* Step nesting

* Typo fix

* Rendering check after splitting out service user procedure

* Wording and indentation fixes

* Fixed permissions typo

* Fixed broken syntax example

* Rendering test for step includes

* Moved credentials into table includes for clarity

* Clarified Atlas cluster steps

* Indentation

* Removed unused file, updated relational connection topic

* Copy edits

* Updated SQL fields with database field behavior

* Updated wording

* Changed markup to procedure

* Updated ref to saved relational connection

* Copy edits

* Tab UI copy edits

* Removed extra step in includes

* Fixed orphaned topic

* Moved SSL steps into settings tables

* SSL cert field descriptions

* SSL cert field descriptions

* SSL cert field descriptions

* Pointed users towards SSL config properties

* Copy edits

* Updated a ref to be more specific

* Updated saved password behavior

* External review feedback

* Updated overview screenshot

* Updated summaries of when users create new connections

* Removed Atlas tab from the include version of MDB connection steps

* Fixing build warning

* Consistent wording

* Cleaned up connect step

* Iconography

* Fixing some ref line breaks

* Clarified effect of deleting a relational connection

* Clarified effect of deleting a relational connection

* Clarified effect of deleting a relational connection

* Note around available database types for existing projects

* Updated relational connection management to point out use case for staging to prod environments

* Internal review feedback

* Fixed broken link

* Rebuild after merging in upstream

* Fixed a few lingering mentions of sync jobs

* Updated UI description for connection bar

* Internal review feedback

Author: nvillahermosa-mdb

snooty.toml

@@ -18,6 +18,7 @@ toc_landing_pages = [
 "installation/install-on-an-unattended-server/rhel-centos-server-installation/rhel-centos-server-installation",
 "installation/kafka-deployments/migrator-with-kafka",
 "installation/file-location",
+"database-connections/database-connections",
 "projects/projects",
 "mapping-rules/mapping-rules",
 "mapping-rules/mapping-rule-options/mapping-rule-options",

source/connection-strings/connection-strings.txt

@@ -10,9 +10,10 @@ Connection Strings
    :depth: 1
    :class: singlecol
 
-Relational Migrator uses connection strings to connect to both 
+Database connections use connection strings to connect to both 
 the relational and MongoDB databases. You can create connection strings:
 
+- Using the UI when you create a MongoDB or relational :ref:`Database Connection <rm-database-connections>`.
 - Using the UI when you create a project.
 - Using the UI when you create a migration job.
 - By manually providing the Uniform Resource Identifier (URI).

source/connection-strings/mongodb-database-connection-strings.txt

@@ -12,129 +12,45 @@ MongoDB Database Connection Strings
 
 .. include:: /includes/uri-usage-disclaimer.rst
 
-To start a migration job, Relational Migrator must connect to your MongoDB 
-database. Relational Migrator requires a username and password which has ``readWrite`` 
-access in the target database. This page describes 
-the procedure to make an authenticated user account and the Uniform Resource 
-Identifier (URI) formats for defining connections to your target 
-MongoDB database. 
+This page describes the Uniform Resource Identifier (URI) formats for defining
+connections to your MongoDB database. 
 
-About this Task
----------------
+Relational Migrator supports all connection string options except
+:urioption:`appName`. It overrides ``appName`` when connecting to your MongoDB
+deployment. For details on MongoDB connection string options, see 
+:manual:`Connection Strings <mongodb-uri>`.
 
-- Relational Migrator supports all connection string options except 
-  :urioption:`appName`. Relational Migrator overrides the ``appName`` 
-  connection string option when connecting to your MongoDB deployment. 
-  For details on MongoDB connection string options, see 
-  :ref:`<mongodb-uri>`.
+MongoDB User
+------------
 
-- Relational Migrator can use both Atlas and on-premises URIs. This page 
-  provides separate instructions for each deployment type.
+For both Atlas and on-premises deployments, create a separate
+:ref:`MongoDB user <rm-mongodb-service-user>` for Relational Migrator with
+:authrole:`readWrite` access to your MongoDB database.
 
-Atlas
------
-
-Connect to Your Deployment
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-To provision user accounts in Atlas you need to be 
-`logged in to the Atlas GUI <https://cloud.mongodb.com/v2/>`__.
-
-Create a New User
-~~~~~~~~~~~~~~~~~
-
-#. In the :guilabel:`Security` section of the left navigation, click :guilabel:`Database Access`.
-#. Click :guilabel:`Add New Database User`.
-#. In the :guilabel:`Authentication Method` section of the :guilabel:`Add New Database User` modal window, select the box labeled :guilabel:`Password`.
-#. Under :guilabel:`Password Authentication`, enter the username ``migrator-service`` for the new user in the top text field.
-#. Enter the password ``password`` for the new user in the lower text field.
-#. Under :guilabel:`Database User Privileges`, click :guilabel:`Built-in Role`.
-#. Select :guilabel:`Read and write to any database`.
-#. Click :guilabel:`Add User`.
-
-Connection URI
-~~~~~~~~~~~~~~
-
-Using the previously created account credentials, format the connection
-URI for the target database. In this case ``MongoEnterprises``.
-
-.. code-block::
-
-   mongodb+srv://migrator-service:[email protected]/MongoEnterprises
-
-On-Premises
------------
-
-In this example, use ``mongosh`` to provision a user account that 
-connects to the ``MongoEnterprises`` database.
-
-This examples assume your deployment is running on ``localhost`` and the 
-default port of ``27017``.
-
-Connect to Your Deployment
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-When connecting to your deployment, your user account requires the 
-`createRole <https://www.mongodb.com/docs/manual/reference/method/db.createRole/>`__
-permission in both the ``admin`` and ``MongoEnterprises`` databases.
-Copy the following code with your admin credentials into a terminal to 
-connect to your deployment with ``mongosh``.
+Atlas Connection URI
+--------------------
 
 .. code-block::
 
-   mongosh "mongodb://myadminuser:myadminpassword@localhost:27017/admin"
+   mongodb+srv://username:[email protected]/database
 
-For details on ``mongosh`` connections see : 
-`Connecting to your MongoDB Deployment <https://www.mongodb.com/docs/mongodb-shell/connect/>`__.
-
-Create a New User
-~~~~~~~~~~~~~~~~~
-
-In ``mongosh``, run the following command to create a 
-user in the ``admin`` database:
+For example, to use an account named ``migrator-service`` to connect to the
+``MongoEnterprises`` database:
 
 .. code-block::
 
-   use admin
-
-   db.createUser(
-      { user: "migrator-service",
-         pwd: "password",
-         roles:[{role: "readWrite" , db:"MongoEnterprises"}]
-      }
-   )
+   mongodb+srv://migrator-service:[email protected]/MongoEnterprises
 
-Create the same user in the user in the ``MongoEnterprises`` database:
+On-Premises Connection URI
+--------------------------
 
 .. code-block::
 
-   use MongoEnterprises
-   db.createUser(
-      { user: "migrator-service",
-         pwd: "password",
-         roles:[{role: "readWrite" , db:"MongoEnterprises"}]
-      }
-   )
-
-These commands:
-
-- Create a new user ``migrator-service`` with the password ``password`` 
-  in the ``admin`` and ``MongoEnterprises`` databases.
-- Apply the ``readWrite`` system role to the ``MongoEnterprises``
-  database for the user ``migrator-service``.
+   mongodb://username:password@host:port/database
 
-Connection URI
-~~~~~~~~~~~~~~
-
-Using the previously created account credentials, format the connection
-URI for the target database. In this case ``MongoEnterprises``.
+For example, to use an account named ``migrator-service`` to connect to the
+``MongoEnterprises`` database:
 
 .. code-block::
 
-   mongodb://migrator-service:password@localhost:27017/MongoEnterprises
-
-Results
--------
-
-The MongoDB connection URI is optionally specified as part of the process for
-creating a Relational Migrator project or when creating a migration job.
+   mongodb://migrator-service:password@localhost:27017/MongoEnterprises

source/connection-strings/relational-database-connection-strings.txt

@@ -31,6 +31,8 @@ Relational Migrator's connection form contains fields where you can specify a
 username and password for the connection. The form obscures passwords
 and is more secure than specifying plaintext credentials in the URI.
 
+.. _rm-mysql-connection-string:
+
 MySQL
 -----
 
@@ -68,6 +70,8 @@ details:
    - `MySQL Connection URL Syntax <https://dev.mysql.com/doc/connector-j/en/connector-j-reference-jdbc-url-format.html>`__
    - `Connection Configuration Properties <https://dev.mysql.com/doc/connector-j/en/connector-j-reference-configuration-properties.html>`__
 
+.. _rm-oracle-connection-string:
+
 Oracle
 ------
 
@@ -104,6 +108,8 @@ details:
 
    - `Oracle JDBC Developer's Guide and Reference <https://docs.oracle.com/en/database/oracle/oracle-database/23/jjdbc/JDBC-Thin-features.html>`__
    - `Connection String Attributes <https://docs.oracle.com/cd/E85694_01/ODPNT/ConnectionConnectionString.htm#GUID-DF4ED9A3-1AAF-445D-AEEF-016E6CD5A0C0__BABBAGJJ>`__
+   
+.. _rm-postgresql-connection-string:
 
 PostgreSQL
 ----------
@@ -140,6 +146,8 @@ The preceding connection string specifies these connection details:
 
    - `PostgreSQL Connection Configuration Properties <https://jdbc.postgresql.org/documentation/use/>`__
 
+.. _rm-sql-connection-string:
+
 SQL Server
 ----------
 
@@ -201,6 +209,8 @@ the default ``dbo`` schema in all databases.
 If you specify the ``databaseName`` property, you can see tables from
 all schemas within the specified database.
 
+.. _rm-sybase-connection-string:
+
 Sybase ASE
 ----------
 
@@ -215,7 +225,9 @@ The general form for a Sybase ASE connection string is:
    To learn more about Sybase ASE connection strings, see:
 
    - `Sybase ASE Connection String Docs <https://infocenter.sybase.com/help/index.jsp?topic=/com.sybase.infocenter.dc01776.1601/doc/html/san1357754914053.html>`__
-   - `Connectingstrings.com <https://www.connectionstrings.com/sybase-adaptive/>`__
+   - `ConnectionStrings.com <https://www.connectionstrings.com/sybase-adaptive/>`__
+
+.. _rm-db2-connection-string:
 
 DB2
 ---

source/database-connections/database-connections.txt

@@ -0,0 +1,46 @@
+.. _rm-database-connections:
+
+====================
+Database Connections
+====================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+Relational Migrator uses JDBC connection strings and associated user
+credentials to access your relational database and MongoDB deployment.
+You can save this information as a database connection.
+
+Use Cases
+---------
+
+You can save connection settings for relational and MongoDB databases
+when creating projects and migration jobs. You can use these saved database
+connections for any task that requires connecting to a relational or MongoDB
+database.
+
+Get Started
+-----------
+
+To create, view, and manage saved connections, go to the Relational 
+Migrator :guilabel:`Connections` page.
+
+- :ref:`rm-create-project-live`
+- :ref:`rm-create-jobs`
+- :ref:`rm-save-relational-connection`
+- :ref:`rm-save-mongodb-connection`
+
+
+.. toctree::
+   :titlesonly:
+   :hidden:
+
+   Save a MongoDB Connection </database-connections/save-mongodb-connection>
+   Save a Relational Connection </database-connections/save-relational-connection>
+   Manage Connections </database-connections/manage-database-connections>
+   Connection Strings </connection-strings/connection-strings>

source/database-connections/manage-database-connections.txt

@@ -0,0 +1,86 @@
+.. _rm-manage-connections:
+
+===========================
+Manage Database Connections
+===========================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+You can copy, edit, or delete database connections from the Relational Migrator
+:guilabel:`Connections` page. Saved connections are listed by their environment
+tag. You can mouse over the :icon-fa5:`info-circle` icon for a connection to
+see a list of projects that use that connection.
+
+Copy a Connection
+-----------------
+
+You can copy an existing connection. This can be useful if you want multiple
+connections to the same server that each connect to different databases, or if
+you have similar connection information for a staging database and a 
+production database.
+
+Copying a connection creates a duplicate with ``-Copy`` appended to the
+connection name.
+
+
+Steps
+~~~~~
+
+To copy a connection:
+
+#. Click the :icon-fa4:`copy` button.
+
+#. Make any desired changes.
+
+#. Click :guilabel:`Save`.
+
+
+
+Edit a Connection
+-----------------
+
+You can edit an existing connection to change any settings except for the
+database type. This can be useful for:
+
+- Renaming the connection
+- Adding changing, or removing the :guilabel:`Environment tag`
+- Changing authentication credentials or SSL settings
+
+
+Steps
+~~~~~
+
+To edit a connection:
+
+#. Click the :icon-lg:`Edit` button.
+
+#. Make any desired changes, such as renaming the connection or changing the database.
+
+#. Click :guilabel:`Save`.
+
+
+
+Delete a Connection
+-------------------
+
+You can delete a connection that you no longer need. Deleting a relational
+database connection causes any projects using that connection to fall back to
+Relational Migrator's last copy of the database contents. Mapping rules remain
+in place.
+
+Steps
+~~~~~
+
+To delete a connection:
+
+#. Click the :icon-fa5:`trash` button.
+
+   A warning dialog displays and lists any projects that use the connection.
+
+#. Click :guilabel:`Delete` to confirm.