Skip to content

Commit 768de89

Browse files
jocelyn-mendez1jocelyn-mendez1
authored
DOCSP-30417 Project Migration (#23)
* DOCSP-30417 rename and import * DOCSP-30417 delete and export * DOCSP-30417 manage relational model * DOCSP-30417 manage relational model * DOCSP-30417 sample schema * DOCSP-30417 schema file * DOCSP-30417 live database * DOCSP-30417 configure settings * DOCSP-30417 configure settings * DOCSP-30417 remove image * DOCSP-30417 live connection and schema file feedback * DOCSP-30417 sample schema and import * DOCSP-30417 nit fix * DOCSP-30417 nit fix
1 parent 92b88c1 commit 768de89

14 files changed

+866
-11
lines changed

‎.vscode/settings.json

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{
2+
"esbonio.sphinx.confDir": ""
3+
}

‎source/jobs/creating-jobs.txt

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ need to be the same as the credentials used when creating your project.
2323
Before you Begin
2424
----------------
2525

26-
- :ref:`Create one or more mapping rules <rm-create-mapping-rules>` in your
26+
- :ref:`Create one or more mapping rules <create-rule-relational>` in your
2727
Relational Migrator project.
2828
- Prepare a :ref:`MongoDB URI <rm-mongodb-database-connection-strings>` and
2929
credentials that have read/write permissions on your destination database.
@@ -149,4 +149,4 @@ see the follow Debezium reference links, which are internally utilized by Relati
149149
* `MySQL <https://debezium.io/documentation/reference/stable/connectors/mysql.html#setting-up-mysql>`__
150150
* `Oracle <https://debezium.io/documentation/reference/stable/connectors/oracle.html#_preparing_the_database>`__
151151
* `PostgreSQL <https://debezium.io/documentation/reference/stable/connectors/postgresql.html#setting-up-postgresql>`__
152-
* `SQL Server <https://debezium.io/documentation/reference/stable/connectors/sqlserver.html#setting-up-sqlserver>`__
152+
* `SQL Server <https://debezium.io/documentation/reference/stable/connectors/sqlserver.html#setting-up-sqlserver>`__

‎source/mapping-rules/new-rules-from-relational.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
.. _rm-create-mapping-rules:
1+
.. _create-rule-relational:
22

33
===========================
44
Create Rule From Relational

‎source/mapping-rules/new-rules-to-mongodb.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
.. _rm-create-rule-to-mdb:
1+
.. _create-rule-mongodb:
22

33
======================
44
Create Rule To MongoDB

‎source/projects/configure-settings.txt

Lines changed: 107 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,112 @@
44
Configuring Project Settings
55
============================
66

7+
.. default-domain:: mongodb
78

9+
.. contents:: On this page
10+
:local:
11+
:backlinks: none
12+
:depth: 1
13+
:class: singlecol
814

9-
.. _rm-key-handling-setting:
15+
After you create a Relational Migrator project, you can configure settings for that
16+
project.
17+
18+
.. note::
19+
20+
To learn how to create a Relational Migrator project, see
21+
:ref:`Creating a Project <rm-create-project-live>`.
22+
23+
Open Project Settings Dialog
24+
----------------------------
25+
26+
To open the :guilabel:`Project Settings` dialog:
27+
28+
1. From the Relational Migrator home page, click the target project.
29+
30+
#. From the project view, the gear icon next to your project's name.
31+
32+
Configurable Project Settings
33+
-----------------------------
34+
35+
You can configure the following settings for your project:
36+
37+
Key Handling Options
38+
~~~~~~~~~~~~~~~~~~~~
39+
40+
Specifies how the ``_id`` field is populated when new documents are
41+
inserted into a collection. You can choose one of the following options:
42+
43+
- :guilabel:`Wrapped Inherited Primary Key`
44+
45+
- Your ``_id`` field is populated with an object where the key is the
46+
name of your primary key field and the value is the value of your
47+
primary key field.
48+
49+
For example, if your relational table row has a primary key of
50+
``personId = 1``, after migration your MongoDB ``_id``field is
51+
``_id: { personId: 1 }``.
52+
53+
54+
- :guilabel:`Single Inherited Primary Key`
55+
56+
- Your ``_id`` field is populated with the value of the primary key
57+
field. The name of your primary key field is not included in the ``_id``.
58+
59+
For example, if your relational table row has a primary key of ``personId=1``,
60+
after migration your MongoDB ``_id`` field is ``_id: 1``.
61+
62+
63+
- :guilabel:`Autogenerated ObjectId`
64+
65+
- Your ``_id`` field is populated with an autogenerated random
66+
`ObjectId <https://www.mongodb.com/docs/manual/reference/bson-types/#std-label-objectid>`__.
67+
68+
You may choose to keep the original primary key as a different field
69+
in the collection.
70+
71+
For example, if your relational table row has a primary key of ``personId = 1``,
72+
after migration your MongoDB ``_id`` field is ``_id: ObjectId("62472f3d5849820a91d7b52f")``.
73+
74+
75+
Key Handling Behavior
76+
`````````````````````
77+
78+
- If your relational table has more than one field in its primary key
79+
and you select the :guilabel:`single` strategy, collections receiving data
80+
from that table use the :guilabel:`wrapped` key handling strategy. The
81+
:guilabel:`single` strategy only works for tables that have a single primary
82+
key.
83+
84+
- If your relational table does not have a primary key, collections
85+
receiving data from that table use the :guilabel:`generated` strategy even if
86+
you select a different global strategy.
87+
88+
Global Casing
89+
~~~~~~~~~~~~~
90+
91+
You can choose one of the following options:
92+
93+
- :guilabel:`Keep Original`: Keep the original casing used in your relational
94+
database table name.
95+
96+
- :guilabel:`Override with Global Casing`: Override the original table name
97+
with a global casing convention.
98+
99+
- ``camelCase``
100+
- ``TitleCase``
101+
- ``kebab-case``
102+
- ``snake_case``
103+
- ``UPPER_SNAKE_CASE``
104+
105+
.. note::
106+
107+
Changing this setting after creating a project only impacts mappings
108+
created after the setting change. Mappings created prior to changing
109+
this setting are not affected.
110+
111+
Suggested Mappings
112+
~~~~~~~~~~~~~~~~~~
113+
114+
Enabling :guilabel:`Suggested mappings` allows Relational Migrator to automatically
115+
suggest mapping rules based upon your relational schema.

‎source/projects/create-project-live-connection.txt

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,3 +3,154 @@
33
=================================================
44
Create a Project By Connecting to a Live Database
55
=================================================
6+
7+
.. default-domain:: mongodb
8+
9+
.. contents:: On this page
10+
:local:
11+
:backlinks: none
12+
:depth: 1
13+
:class: singlecol
14+
15+
You can create a project using a live database connection.
16+
Creating a project is the first step in the migration process.
17+
When creating a project with a live connection you:
18+
19+
- Provide the connection details for your source relational system.
20+
21+
- Provide the connection details for your destination MongoDB deployment.
22+
23+
- Select the database, schema, and tables that are part of the migration.
24+
25+
About this Task
26+
---------------
27+
28+
Creating a project with live a live connection is the recommended process for starting a new Relational Migrator project.
29+
30+
Steps
31+
-----
32+
33+
1. Click :guilabel:`New Project` at the top-right of the Relational Migrator home screen.
34+
35+
#. Click the :guilabel:`Connect database` button.
36+
37+
#. Select a database type. Relational Migrator supports migrating from the following
38+
database types:
39+
40+
- MySQL
41+
- Oracle
42+
- PostgreSQL
43+
- SQL Server
44+
45+
#. Enter the connection details to create the JDBC URI for your relational database.
46+
47+
a. Enter a host IP or DNS name in the :guilabel:`Host` text box.
48+
49+
b. Enter a port number in the :guilabel:`Port` text box.
50+
51+
c. Enter a database name in the :guilabel:`Database` text field. Depending on your
52+
relational database, this behavior varies:
53+
54+
.. list-table::
55+
:header-rows: 1
56+
:widths: 25 75
57+
58+
* - Database Type
59+
- Behavior
60+
61+
* - Oracle
62+
- The database name is required. You also need to specify a :guilabel:`Service ID`
63+
or :guilabel:`SID`.
64+
65+
* - SQL Server
66+
- Leaving database name blank loads all databases.
67+
68+
* - MySQL
69+
- Leaving database name blank loads all databases.
70+
71+
* - Postgres
72+
- Leaving database name blank loads schemas from the default database.
73+
74+
d. Enter a user name in the :guilabel:`Username` text box.
75+
76+
e. Enter a password in the :guilabel:`Password` text box.
77+
78+
f. (Optional) Click the :guilabel:`Save a password for this session` check box to
79+
avoid reentering your password in the project.
80+
81+
g. Click the :guilabel:`SSL` toggle switch to enable or disable SSL and select an SSL mode.
82+
83+
h. Click :guilabel:`Connect`.
84+
85+
Connection and SSL details depend on the database type you are connecting to.
86+
In addition to the generic connection properties listed above, you may also
87+
need to select an ``Identifier`` for Oracle and ``Authentication`` for SQL Server.
88+
89+
.. note::
90+
91+
If you want to specify the JDBC URI manually, click the :guilabel:`Enter URI manually`
92+
toggle switch on the :guilabel:`Connect to the database screen`. For
93+
details see, :ref:`Relational Database Connection Strings <rm-relational-database-connection-strings>`.
94+
95+
#. From the :guilabel:`Select tables` screen, indicate the tables you want to migrate
96+
and click :guilabel:`Next`.
97+
98+
The following table explains the different ways you can select tables to migrate:
99+
100+
.. list-table::
101+
:header-rows: 1
102+
:widths: 25 75
103+
104+
* - Target
105+
- Action
106+
107+
* - All tables within a database
108+
- Click the check mark for the target database.
109+
110+
* - All tables within a schema
111+
- Expand the target database and click the check mark for the target schema.
112+
113+
* - Specific tables within a schema
114+
- Expand the target database and schema. Select the target tables individually.
115+
116+
* - Specific table names
117+
- Use the :guilabel:`Filter` bar above the :guilabel:`Relational Schema` list.
118+
119+
#. Choose a :guilabel:`Global casing` option for collection names.
120+
121+
This option affects the names of your collections created from the tables in
122+
your relational database:
123+
124+
- :guilabel:`Keep Original`: Keep the original casing used in your relational
125+
database table name.
126+
127+
- :guilabel:`Override with Global Casing`: Override the original table name
128+
with a global casing convention.
129+
130+
- ``camelCase``
131+
- ``TitleCase``
132+
- ``kebab-case``
133+
- ``snake_case``
134+
- ``UPPER_SNAKE_CASE``
135+
136+
#. Choose an :guilabel:`Initial mappings` option for your MongoDB schema.
137+
138+
- :guilabel:`Start with a MongoDB schema that matches your relational schema`: Creates your
139+
initial project with a new document mapping rule for each table.
140+
141+
- :guilabel:`Start with a recommended MongoDB schema`: Relational Migrator chooses
142+
mapping rules for you.
143+
144+
- :guilabel:`Start with an empty MongoDB schema`: Creates your initial project
145+
with no mapping rules.
146+
147+
#. Enter a name for your project.
148+
149+
#. Click :guilabel:`Done`.
150+
151+
Next Steps
152+
----------
153+
154+
- :ref:`Create Mapping Rules From Relational <create-rule-relational>`
155+
156+
- :ref:`Create Mapping Rules To MongoDB <create-rule-mongodb>`

0 commit comments

Comments
 (0)