Merge pull request #36 from mongodb-developer/add-pre-migration-analysis

Add pre migration analysis

Author: dfreniche

docs/0-intro.mdx

@@ -1,18 +1,16 @@
 ---
-sidebar_position: 10
+sidebar_position: 01
 ---
 # 📘 Introduction
 
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-
 |Workshop goals|Migrate a relational DB into MongoDB Atlas|
 |-|-|
-|What you'll learn|- What is the [MongoDB Relational Migrator](https://www.mongodb.com/products/tools/relational-migrator)?|
-||- How to install it|
-||- Importing a relational DB: import the schema|
-||- Map the relational schema to a MongoDB schema|
-||- Migrate the data to MongoDB|
+|What you'll learn| What is the [MongoDB Relational Migrator](https://www.mongodb.com/products/tools/relational-migrator)?|
+|| How to run a pre-migration analysis |
+|| How to import the relational schema|
+|| Add mapping rules to convert the relational schema to a MongoDB schema|
+|| How to convert your SQL queries and stored procedures |
+|| How to migrate the data to MongoDB|
 |Prerequisites| See [Dev Environment](/docs/category/dev-environment/)|
 |Time to complete|1.5 hour|
 

docs/05-what-is-the-mongodb-relational-migrator.mdx

@@ -0,0 +1,8 @@
+---
+sidebar_position: 05
+---
+import Screenshot from "@site/src/components/Screenshot";
+
+# 📘 What is the MongoDB Relational Migrator
+
+The [Relational Migrator](https://www.mongodb.com/products/tools/relational-migrator) is a free tool that streamlines migrating data from RDBMS to MongoDB, significantly lowering the effort and risk of a migration initiative.

docs/10-dev-env/1-dev-env-setup.mdx

@@ -21,6 +21,11 @@ Let it run for a few minutes as it prepares a Docker container with all the requ
 
 <details>
   <summary>🦹 __Run this lab locally__</summary>
+
+  :::info
+  Again: during the lab, we will use GitHub Codespaces. The following instructions are here just in case you can't use Codespaces or if you really, really, really want to try a local installation.
+  :::
+
   #
   # 1. MongoDB Database
 
@@ -62,19 +67,17 @@ Let it run for a few minutes as it prepares a Docker container with all the requ
 
   Download and install MongoDB Relational Migrator. 
 
-  - Go to the [MongoDB Relational Migrator downloads page](https://www.mongodb.com/try/download/relational-migrator), select your OS and download it
-  - Install the MongoDB Relational Migrator 
-  - Start it 
+  - Open the [MongoDB Relational Migrator downloads page](https://www.mongodb.com/try/download/relational-migrator)
+  - Select your platform (OS / Architecture if applies) and download it.
+  - Install the MongoDB Relational Migrator. 
+  - Launch it. 
   - It should open a browser at the address http://127.0.0.1:8278/
+  - You should see an icon to launch/quit the Relational Migrator.
 
-  <Screenshot url="https://www.mongodb.com/products/tools/relational-migrator" src="img/download-relational-migrator.png" alt="Screenshot of the download page for Relational Migrator" />
+  <Screenshot url="https://www.mongodb.com/try/download/relational-migrator" src="img/download-relational-migrator.png" alt="Screenshot of the download page for Relational Migrator" />
 
   ---
 
-  There are more advanced ways to install the MongoDB Relational Migrator. You can check them out in [the installation docs page](https://www.mongodb.com/docs/relational-migrator/installation/). These won't be covered during this Lab.
-
-</details>
-
-
-
+  There are other, more advanced ways to install the MongoDB Relational Migrator. You can check them out in [the installation docs page](https://www.mongodb.com/docs/relational-migrator/installation/). These won't be covered during this Lab.
 
+</details>

docs/10-dev-env/10-postgres.mdx

@@ -13,7 +13,7 @@ In this lab you will be migrating data from a PostgreSQL relational database.
 If you are participating in an instructor-led lab, they may have already set up this database for you. Ask your instructor for the connection URI and credentials.
 
 :::caution
-In an intructor-led lab you will use the provisioned PostgreSQL database, no need to do anything else.
+In an intructor-led lab you will use the provisioned PostgreSQL database, no need to do anything else. The rest of the Lab assumes you have a PostgreSQL database running and accessible.
 :::
 
 <details>

docs/30-schema-in-postgresql.mdx

@@ -2,9 +2,11 @@ import Screenshot from "@site/src/components/Screenshot";
 
 # 📘 Schema in PostgreSQL
 
-The following screenshot shows an entity-relationship diagram of the relational database we wish to migrate. This is a library management app that stores information about books, where a book can have many authors, an author can write many books, and users can borrow books and leave reviews. You can have many copies of the same book and those are what users borrow and return. All this is registered in the `operations` collection. A library user can have many addresses.
-
-This is the sample schema we use during our [Developer Days's Intro Lab](https://mongodb-developer.github.io/intro-lab/docs/importing-data/intro).
+The following screenshot shows an entity-relationship diagram of the relational database we wish to migrate. This is a library management app that stores information about books (table `books`), where a book can have many authors (table `authors`) and an author can write many books (`author_book` link table). Users can leave reviews (`reviews` table). You can have many copies of the same book. Users borrow and return books (this is registered in the `operations` table). A library user can have many addresses (`user_addresses` table).
 
 [![Screenshot of the PostgreSQL ERD](/img/30-image-001.png)](/img/30-image-001.png)
-_Click to enlarge in a new tab / window_
+_Click to enlarge in a new tab / window_
+
+:::info
+This is the sample schema we use during our [Developer Days's Intro Lab](https://mongodb-developer.github.io/intro-lab/docs/importing-data/intro).
+:::

docs/40-desired-schema-mongodb.mdx

@@ -4,7 +4,7 @@ import Screenshot from "@site/src/components/Screenshot";
 
 Since MongoDB is a document database, you have more flexibility in how you model your data. When migrating from
 a relational database to MongoDB, it's important to consider how your data is accessed, and model the data such 
-that data that is frequently accessed together is stored together by using embedded documents and arrays. 
+that __data that is frequently accessed together is stored together__ by using __embedded documents__ and __arrays__. 
 
 The following screenshot shows the MongoDB schema we will be creating in this lab.
 

docs/50-create-project/50-create-new-project.mdx

@@ -1,14 +1,30 @@
 import Screenshot from "@site/src/components/Screenshot";
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
 
 # 👐 Creating a New Project
 
-Ensure the Relational Migrator is installed and running (in your codespace or locally at http://127.0.0.1:8278/).
+Ensure the Relational Migrator is installed and running (either in your codespace or locally at http://127.0.0.1:8278/).
 
+## Create a New Project
 
-## Click on New Project
+<Tabs groupId="Create a New Project">
+  <TabItem value="FirstTime" label="First Time using Relational Migrator">
 
+    If you're running the Relational Migrator for the first time, you will see a welcome screen. We will `Start from scratch` and click on `Connect database`.
 
-<Screenshot url="http://127.0.0.1:8278" src="img/50-image-001.png" alt="Screenshot of the connect modal" />
+    <Screenshot url="http://127.0.0.1:8278" src="img/50-image-000.png" alt="Create a New Project clicking on Connect database" />
+
+  
+  </TabItem>
+  <TabItem value="AlreadyUsed" label="I already have a project!">
+
+    Click on the `New Project` button in the top right corner of the Relational Migrator UI.
+
+    <Screenshot url="http://127.0.0.1:8278" src="img/50-image-001.png" alt="Create a New Project clicking on New Project" />
+  
+  </TabItem>
+</Tabs>
 
 ## Select one of the three options
 - 👐 Click **Connect database** under "Connect to live database" if you are running the source database in the cloud, Docker or using your own hardware. This is what we will use during an instructor-led hands-on lab.

docs/50-create-project/60-connect-database.mdx

@@ -4,7 +4,7 @@ import Screenshot from "@site/src/components/Screenshot";
 
 ## Add a new connection
 
-We can store the credentials of our database so in the next session we can connect quickly. In this case, we'll create a new connection selecting "Add a new connection". 
+We can store the credentials of our database so in the next session we can quickly re-connect. In this case, we'll create a new connection selecting "Add a new connection". 
 
 ## Select PostgreSQL as Database Type
 
@@ -16,15 +16,15 @@ Then we'll select PostgreSQL as our source database.
 
 Enter the details for the PostgreSQL database you will be migrating from.
 
-- It's important to click on the `SSL` tab and activate SSL (SSL mode Prefer is fine), otherwise we won't be able to connect to cloud hosted databases.
+- It's important to click on the `SSL` tab and activate `Use SSL` (`SSL mode` Prefer is fine), otherwise we won't be able to connect to cloud hosted databases.
 - If your instructors have configured a server for you to use, ask them for the host name, username and password. 
+:::info
+👐 If you have followed the steps to configure PostgreSQL in Instruqt / GitHub Codespaces, the hostname will be `localhost`, username `postgres` and password `postgres`. 
+:::
 - Click back on the `General` tab and enter the database name as `library`.
-- Click `Test Connection` to ensure your details are correct.
+- Check the `Save password` box if you want to save the password for future connections.
+- Click `Test Connection` to ensure your details are correct. You should see a message saying "PostgreSQL database connection successful."
 - Click `Connect` to proceed to the next step.
-- You can give your connection a name and a tag to make it simpler to remember later
+- You can give your connection a name and a tag to make it simpler to remember later.
 
 <Screenshot url="http://127.0.0.1:8278" src="img/60-image-001.png" alt="Screenshot of the connect modal" />
-
-:::info
-🦸‍♂️ If you have followed the steps to configure PostgreSQL in a docker container, the hostname will be `localhost`, username `postgres` and password `postgres`. 
-:::

docs/50-create-project/80-define-initial-schema.mdx

@@ -2,13 +2,19 @@ import Screenshot from "@site/src/components/Screenshot";
 
 # 👐 Define the Initial Schema
 
-Relational Migrator gives you three options on how your MongoDB schema should be created. Regardless of which option you choose, you can manually modify your schema later. 
+Relational Migrator gives you three options on how your initial MongoDB schema will be created. Regardless of which option you choose, you can manually modify your schema later. 
+
+| Option      | What it does     | 
+| :------------- | :---------- | 
+| Start with a MongoDB schema that matches your relational schema | Maps each table exactly to one collection, including link tables (for 1:n relationships). We're just replicating the existing schema, which won't take advantage of the Document Model.  | 
+| Start with a recommended MongoDB schema   | Will try to understand your schema and embed 1:n relationships. | 
+| Start with an empty MongoDB schema   | Your MongoDB schema will be empty. You'll create all the mappings yourself. | 
 
 Select `Start with a recommended MongoDB schema`
 
-You are asked which tables should represented as a collection in MongoDB. 
+You can see which tables will be mapped to a collection in MongoDB: those marked as `TOP-LEVEL`.
 
-Select the following six collections as they are the main entities in our schema:
+Select the following six collections as `TOP-LEVEL` since they are the main entities in our schema:
 
 - authors
 - books
@@ -19,7 +25,7 @@ Select the following six collections as they are the main entities in our schema
 
 Any tables you did not check will be embedded in other collections. 
 
-<Screenshot url="http://127.0.0.1:8278" src="img/80-image-001.png" alt="Screenshot of the connect modal" />
+<Screenshot url="http://127.0.0.1:8278" src="img/80-image-001.png" alt="Defining the initial schema" />
 
 Select the casing you'd like for your collections - the default is camelCase.
 

docs/50-create-project/_category_.json

@@ -2,6 +2,6 @@
     "label": "👐 Create a Project",
     "link": {
         "type": "generated-index",
-        "description": "Create your Project in Relational Migrator."
+        "description": "Create your Project in the MongoDB Relational Migrator and start with an initial schema."
     }
 }