Skip to content

Commit c68bb43

Browse files
ianf-mongodbianf-mongodb
authored
DOCSP-30626 Connection String Drawer (#10)
* DOCSP-30626 Connection Strings Drawer
1 parent 53ab0a5 commit c68bb43

File tree

4 files changed

+328
-2
lines changed

4 files changed

+328
-2
lines changed

‎source/connection-strings/connection-strings.txt

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,18 @@
22
Connection Strings
33
==================
44

5+
Relational Migrator uses connection strings to connect to both
6+
the relational and MongoDB databases. You can create connection strings:
7+
8+
- Using the UI when you create a project.
9+
- Using the UI when you create a sync job.
10+
- By manually providing the Uniform Resource Identifier (URI).
11+
12+
To learn how to manually create your connection string URIs, see:
13+
14+
- :ref:`rm-relational-database-connection-strings`
15+
- :ref:`rm-mongodb-database-connection-strings`
16+
517
.. toctree::
618
:titlesonly:
719
:hidden:

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

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,125 @@
1+
.. _rm-mongodb-database-connection-strings:
2+
13
===================================
24
MongoDB Database Connection Strings
35
===================================
6+
7+
.. include:: /includes/uri-usage-disclaimer.rst
8+
9+
To start a migration job, Relational Migrator must connect to your MongoDB
10+
database. Relational Migrator requires a username and password which has ``readWrite``
11+
access in the target database. This page describes
12+
the procedure to make an authenticated user account and the Uniform Resource
13+
Identifier (URI) formats for defining connections to your target
14+
MongoDB database.
15+
16+
Relational Migrator can use both Atlas and on-premises URIs. This page
17+
provides separate instructions for each deployment type.
18+
19+
Atlas
20+
-----
21+
22+
Connect to Your Deployment
23+
~~~~~~~~~~~~~~~~~~~~~~~~~~
24+
25+
To provision user accounts in Atlas you need to be
26+
`logged in to the Atlas GUI <https://cloud.mongodb.com/v2/>`__.
27+
28+
Create a New User
29+
~~~~~~~~~~~~~~~~~
30+
31+
#. In the :guilabel:`Security` section of the left navigation, click :guilabel:`Database Access`.
32+
#. Click :guilabel:`Add New Database User`.
33+
#. In the :guilabel:`Authentication Method` section of the :guilabel:`Add New Database User` modal window, select the box labeled :guilabel:`Password`.
34+
#. Under :guilabel:`Password Authentication`, enter the username ``migrator-service`` for the new user in the top text field.
35+
#. Enter the password ``password`` for the new user in the lower text field.
36+
#. Under :guilabel:`Database User Privileges`, click :guilabel:`Built-in Role`.
37+
#. Select :guilabel:`Read and write to any database`.
38+
#. Click :guilabel:`Add User`.
39+
40+
Connection URI
41+
~~~~~~~~~~~~~~
42+
43+
Using the previously created account credentials, format the connection
44+
URI for the target database. In this case ``MongoEnterprises``.
45+
46+
.. code-block::
47+
48+
mongodb+srv://migrator-service:[email protected]/MongoEnterprises
49+
50+
On-Premises
51+
-----------
52+
53+
In this example, use ``mongosh`` to provision a user account that
54+
connects to the ``MongoEnterprises`` database.
55+
56+
This examples assume your deployment is running on ``localhost`` and the
57+
default port of ``27017``.
58+
59+
Connect to Your Deployment
60+
~~~~~~~~~~~~~~~~~~~~~~~~~~
61+
62+
When connecting to your deployment, your user account requires the
63+
`createRole <https://www.mongodb.com/docs/manual/reference/method/db.createRole/>`__
64+
permission in both the ``admin`` and ``MongoEnterprises`` databases.
65+
Copy the following code with your admin credentials into a terminal to
66+
connect to your deployment with ``mongosh``.
67+
68+
.. code-block::
69+
70+
mongosh "mongodb://myadminuser:myadminpassword@localhost:27017/admin"
71+
72+
For details on ``mongosh`` connections see :
73+
`Connecting to your MongoDB Deployment <https://www.mongodb.com/docs/mongodb-shell/connect/>`__.
74+
75+
Create a New User
76+
~~~~~~~~~~~~~~~~~
77+
78+
In ``mongosh``, run the following command to create a
79+
user in the ``admin`` database:
80+
81+
.. code-block::
82+
83+
use admin
84+
85+
db.createUser(
86+
{ user: "migrator-service",
87+
pwd: "password",
88+
roles:[{role: "readWrite" , db:"MongoEnterprises"}]
89+
}
90+
)
91+
92+
Create the same user in the user in the ``MongoEnterprises`` database:
93+
94+
.. code-block::
95+
96+
use MongoEnterprises
97+
db.createUser(
98+
{ user: "migrator-service",
99+
pwd: "password",
100+
roles:[{role: "readWrite" , db:"MongoEnterprises"}]
101+
}
102+
)
103+
104+
These commands:
105+
106+
- Create a new user ``migrator-service`` with the password ``password``
107+
in the ``admin`` and ``MongoEnterprises`` databases.
108+
- Apply the ``readWrite`` system role to the ``MongoEnterprises``
109+
database for the user ``migrator-service``.
110+
111+
Connection URI
112+
~~~~~~~~~~~~~~
113+
114+
Using the previously created account credentials, format the connection
115+
URI for the target database. In this case ``MongoEnterprises``.
116+
117+
.. code-block::
118+
119+
mongodb://migrator-service:password@localhost:27017/MongoEnterprises
120+
121+
Results
122+
-------
123+
124+
The MongoDB connection URI is optionally specified as part of the process for
125+
creating a Relational Migrator project or when creating a sync job.

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

Lines changed: 191 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,194 @@
1+
.. _rm-relational-database-connection-strings:
2+
13
======================================
24
Relational Database Connection Strings
35
======================================
6+
7+
.. include:: /includes/uri-usage-disclaimer.rst
8+
9+
To analyze a schema or start a migration job, Relational Migrator must connect
10+
to your relational database. To connect to your source database,
11+
Relational Migrator requires a JDBC-formatted connection string. This document
12+
describes the URI formats for defining connections to relational
13+
database systems.
14+
15+
Relational Migrator can connect to the following relational database systems:
16+
17+
- `MySQL <#mysql>`__
18+
- `Oracle <#oracle>`__
19+
- `PostgreSQL <#postgresql>`__
20+
- `SQL Server <#sql-server>`__
21+
22+
Relational Migrator's connection form contains fields where you can specify a
23+
username and password for the connection. The form obscures passwords
24+
and is more secure than specifying plaintext credentials in the URI.
25+
26+
MySQL
27+
-----
28+
29+
The general form for a MySQL connection string is:
30+
31+
.. code-block::
32+
33+
jdbc:mysql://<host:port>/<database>?<properties>
34+
35+
For example, consider the following connection string:
36+
37+
.. code-block::
38+
39+
jdbc:mysql://host1:3306/test
40+
41+
The preceding connection string specifies these connection
42+
details:
43+
44+
.. list-table::
45+
:header-rows: 1
46+
47+
* - Property
48+
- Value
49+
* - Host
50+
- ``host1``
51+
* - Port
52+
- ``3306``
53+
* - Database
54+
- ``test``
55+
56+
.. note::
57+
58+
To learn more about MySQL connection strings, see:
59+
60+
- `MySQL Connection URL Syntax <https://dev.mysql.com/doc/connector-j/8.0/en/connector-j-reference-jdbc-url-format.html>`__
61+
- `Connection Configuration Properties <https://dev.mysql.com/doc/connector-j/8.0/en/connector-j-reference-configuration-properties.html>`__
62+
63+
Oracle
64+
------
65+
66+
The general form for an Oracle connection string is:
67+
68+
.. code-block::
69+
70+
jdbc:oracle:thin:@<host:port>:SID
71+
72+
For example, consider the following connection string:
73+
74+
.. code-block::
75+
76+
jdbc:oracle:thin:@prodHost:1521:ORCL
77+
78+
The preceding connection string specifies these connection
79+
details:
80+
81+
.. list-table::
82+
:header-rows: 1
83+
84+
* - Property
85+
- Value
86+
* - Host
87+
- ``prodHost``
88+
* - Port
89+
- ``1521``
90+
* - SID (System Identifier)
91+
- ``ORCL``
92+
93+
.. note::
94+
95+
To learn more about Oracle connection strings, see:
96+
97+
- `Oracle JDBC Developer's Guide and Reference <https://docs.oracle.com/cd/B28359_01/java.111/b31224/jdbcthin.htm>`__
98+
- `Connection String Attributes <https://docs.oracle.com/cd/E85694_01/ODPNT/ConnectionConnectionString.htm#GUID-DF4ED9A3-1AAF-445D-AEEF-016E6CD5A0C0__BABBAGJJ>`__
99+
100+
PostgreSQL
101+
----------
102+
103+
The general form for a PostgreSQL connection string is:
104+
105+
.. code-block::
106+
107+
jdbc:postgresql://<host:port>/<database>?<properties>
108+
109+
For example, consider the following connection string:
110+
111+
.. code-block::
112+
113+
jdbc:postgresql://localhost:5432/pg-demo
114+
115+
The preceding connection string specifies these connection details:
116+
117+
.. list-table::
118+
:header-rows: 1
119+
120+
* - Property
121+
- Value
122+
* - Host
123+
- ``localhost``
124+
* - Port
125+
- ``5432``
126+
* - Database
127+
- ``pg-demo``
128+
129+
.. note::
130+
131+
To learn more about PostgreSQL connection strings, see:
132+
133+
- `PostgreSQL Connection Configuration Properties <https://jdbc.postgresql.org/documentation/use/>`__
134+
135+
SQL Server
136+
----------
137+
138+
The general form for a SQL Server connection string is:
139+
140+
.. code-block::
141+
142+
jdbc:sqlserver://[serverName[\instanceName][:portNumber]][;property=value[;property=value]]
143+
144+
For example, consider the following connection string:
145+
146+
.. code-block::
147+
148+
jdbc:sqlserver://localhost:1433;databaseName=test
149+
150+
The preceding connection string specifies these connection details:
151+
152+
.. list-table::
153+
:header-rows: 1
154+
155+
* - Property
156+
- Value
157+
* - Host
158+
- ``localhost``
159+
* - Port
160+
- ``1433``
161+
* - databaseName
162+
- ``test``
163+
164+
**Using Windows Integrated Authentication**
165+
166+
To enable Windows Integrated Authentication, add ``integratedSecurity=true;`` to the URI options.
167+
Leave the :guilabel:`Username` and :guilabel:`Password` fields blank. Windows Integrated Authentication connects
168+
to the database using the credentials of the user who launched the Relational Migrator executable.
169+
170+
**Using TLS**
171+
172+
JDBC connections to SQL Server use Transport Layer Security (TLS) by default.
173+
The encrypt property controls TLS. To disable it, set ``encrypt=false;``.
174+
When TLS is enabled, the driver tries to validate the server's certificate by default.
175+
To implicitly trust the server certificate, set ``trustServerCertificate=true;``.
176+
177+
.. note::
178+
179+
To learn more about SQL Server connection strings, see:
180+
181+
- `Setting Connection Properties <https://learn.microsoft.com/en-us/sql/connect/jdbc/setting-the-connection-properties>`__
182+
- `SQL Docs: Building the Connection URL <https://docs.microsoft.com/en-us/sql/connect/jdbc/building-the-connection-url?view=sql-server-ver15>`__.
183+
- `Connecting to SQL Server with the JDBC Driver <https://docs.microsoft.com/en-us/sql/connect/jdbc/connecting-to-sql-server-with-the-jdbc-driver?view=sql-server-ver15>`__
184+
185+
databaseName Property Behavior
186+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
187+
188+
In a SQL Server connection string, use the ``databaseName`` property to
189+
specify the database to connect to. If you omit the ``databaseName``
190+
property, the connection still succeeds but you can only see objects in
191+
the default ``dbo`` schema in all databases.
192+
193+
If you specify the ``databaseName`` property, you can see tables from
194+
all schemas within the specified database.

‎source/includes/uri-usage-disclaimer.rst

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
.. note::
22

3-
URI's are optional, you can use connection string forms to
4-
enter your connection details instead of manually providing a URI.
3+
URIs in Relational Migrator are optional. You can use the connection
4+
string forms to enter your connection details instead of manually
5+
providing URIs.

0 commit comments

Comments
 (0)