Merge pull request #5 from mongodb-developer/revamp-prerequisites

dfreniche · web-flow · commit 04e37089a0c8 · 2024-09-25T14:29:04.000+02:00
Revamped prerequisites, improved instructions overall
diff --git a/docs/10-intro.mdx b/docs/10-intro.mdx
@@ -13,7 +13,7 @@ import TabItem from '@theme/TabItem';
 ||- Importing a Relational DB: import the Schema|
 ||- Map the relational schema to a MongoDB schema|
 ||- Migrate the data to MongoDB|
-|Prerequisites| See [Prerequisites](/docs/prerequisites/)|
+|Prerequisites| See [Prerequisites](/docs/category/-prerequisites/)|
 |Time to complete|1 hour|
 
 These labs are meant to be presented by one of our amazing instructors, but you can also do them on your own.
diff --git a/docs/20-prerequisites.mdx b/docs/20-prerequisites.mdx
diff --git a/docs/20-prerequisites/10-postgres.mdx b/docs/20-prerequisites/10-postgres.mdx
@@ -0,0 +1,44 @@
+---
+sidebar_position: 20
+---
+
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
+# 👐 PostgreSQL Database
+
+In this lab you will be migrating data from a PostgreSQL relational database. You have a few options to set up this database.
+
+### Option 1: Use a pre-configured 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.
+
+### Option 2: Load the schema and data into your own PostgreSQL server
+
+If you already have a PostgreSQL server set up, you can import the schema and data used in this lab. Download the file 
+[1-library-schema-and-data.sql](https://github.com/mongodb-developer/relational-migrator-lab/blob/main/docker/sample-postgres-library/init/1-library-schema-and-data.sql)
+file and load it using psql or [pgAdmin](https://www.pgadmin.org/download/).
+
+### Option 3: Run a PostgreSQL container using Docker
+
+If you don't have an existing PostgreSQL server but have Docker installed, you can easily load a container pre-configured with 
+PostgreSQL and the sample database:
+
+1. Clone or download the code from this lab's [Github repo](https://github.com/mongodb-developer/relational-migrator-lab).
+2. Open a terminal window and navigate to the repo root
+3. Build the Docker image by running the command: 
+```
+docker build -f ./docker/sample-postgres-library/Dockerfile -t sample-postgres-library .
+```
+4. Start the Docker container by running the command:
+```
+docker run -p 5432:5432 sample-postgres-library
+```
+The PostgreSQL server can be accessed at localhost:5432 with a username of `postgres` and a password of `postgres`.
+
+### Option 4: Load an SQL file
+Choose this option if you just want a quick hands-on experience and you don't need to run actual migration.
+Download the file [library-schema.sql](https://github.com/mongodb-developer/relational-migrator-lab/blob/main/resource/library-schema.sql)
+and upload this file to the Relational Migrator later, at the **create a project** step. 
+
+This is just the schema of the database, without actual data, so, you will not be able to perform an actual migration since you do not have a source database. But you can model the schema and play around with the Relational Migrator.
diff --git a/docs/20-prerequisites/20-mongodb.mdx b/docs/20-prerequisites/20-mongodb.mdx
@@ -0,0 +1,39 @@
+---
+sidebar_position: 20
+---
+
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
+# 👐 MongoDB Database
+
+As we'll be importing data from a Relational Database into MongoDB, you'll need to have a MongoDB database. You have a 
+few options to set up this database.
+
+### Option 1: New MongoDB Atlas cluster
+
+The easiest way to run MongoDB is to use MongoDB Atlas, our cloud-hosted database offering.
+You can set a MongoDB Atlas account and a free forever M0 Cluster.
+
+To get yours, follow the instructions on the [Intro Lab:](https://mongodb-developer.github.io/intro-lab/docs/mongodb-atlas/what-is-mongodb)
+- [Create your Account](https://mongodb-developer.github.io/intro-lab/docs/mongodb-atlas/create-account)
+- [Deploy a Database Cluster](https://mongodb-developer.github.io/intro-lab/docs/mongodb-atlas/create-cluster)
+
+Be sure to [open up the cluster to allow connections from your local computer](https://www.mongodb.com/docs/guides/atlas/network-connections/#overview), and configure a database user with the readWriteAnyDatabase role. 
+
+### Option 2: Use an existing cluster
+
+If you have an existing MongoDB Atlas, Enterprise or Community cluster, you can use it as the migration target. Make sure you
+know the URI for the cluster, and have a database user with the readWriteAnyDatabase role. 
+
+### Option 3: Run a MongoDB container using Docker
+
+
+If you don't have an existing PostgreSQL server but have Docker installed, you can easily load a container pre-configured with 
+MongoDB by running the following command:
+
+```
+docker run -p 27017:27017 mongo
+```
+
+This will launch an empty MongoDB community cluster on localhost:27017, suitable to use for this lab. 
+You can connect with no username or password. Since this command does not use Docker volumes, any data will be lost when the container is stopped.
diff --git a/docs/20-prerequisites/30-relational-migrator.mdx b/docs/20-prerequisites/30-relational-migrator.mdx
@@ -0,0 +1,14 @@
+---
+sidebar_position: 20
+---
+
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
+# 👐 MongoDB Relational Migrator
+
+Download and install MongoDB Relational Migrator
+
+Now you will need to go to the [MongoDB Relational Migrator downloads page](https://www.mongodb.com/try/download/relational-migrator), select your OS, download and install it. Once installed, 
+run it and it will be running on a browser at http://127.0.0.1:8278/.
+
+<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" />
diff --git a/docs/20-prerequisites/_category_.json b/docs/20-prerequisites/_category_.json
@@ -0,0 +1,7 @@
+{
+    "label": "👐 Prerequisites",
+    "link": {
+        "type": "generated-index",
+        "description": "Prerare everything you need to complete this Lab."
+    }
+}
diff --git a/docs/50-create-project/50-create-new-project.mdx b/docs/50-create-project/50-create-new-project.mdx
@@ -11,8 +11,9 @@ Ensure Relational Migrator is installed and running (normally at http://127.0.0.
 
 <Screenshot url="https://www.mongodb.com/products/tools/relational-migrator" src="img/50-image-001.png" alt="Screenshot of the connect modal" />
 
-## Select an option
-1. Click **Connect to live database**
-2. Click **Load schema from a file** if you NOT have access to a source database.
+## Select one of the three options
+- Click **Connect to live database** if you are running the origin DB in the cloud, Docker or using your own hardware.
+- Click **Load schema from a file** if you don't have access to a source database and just want to work with the schema (you won't have any data to import though).
+- Click **Use a sample schema** to play around with a test schema, without any data. This does not require connecting to a real DB. We won't use this one in this Lab.
 
 <Screenshot url="https://www.mongodb.com/products/tools/relational-migrator" src="img/50-image-002.png" alt="Screenshot of the connect modal" />
diff --git a/docs/50-create-project/60-connect-database.mdx b/docs/50-create-project/60-connect-database.mdx
@@ -1,20 +1,20 @@
 import Screenshot from "@site/src/components/Screenshot";
 
-# 👐 Connect Database
+# 👐 Connect to the Database
 
-## Select PostgreSQL as Database
+## Select PostgreSQL as Database Type
 
 <Screenshot url="https://www.mongodb.com/products/tools/relational-migrator" src="img/60-image-000.png" alt="Selecting PostgreSQL as Database" />
 
 ## Enter connection details
 
 Enter the details for the PostgreSQL database you will be migrating from.
 
- - If your instructor has configured a server for you to use, ask them for the host name, username and password.
+ - If your instructors have configured a server for you to use, ask them for the host name, username and password. It's important to click on the `SSL` tab and active SSL.
  - If you followed the steps to configure PostgreSQL in a docker container, the hostname will be `localhost`, username `postgres` and password `postgres`. 
 
-Click Test Connection to ensure your details are correct.
+Click `Test Connection` to ensure your details are correct.
 
-Click Connect to proceed to the next step.
+Click `Connect` to proceed to the next step.
 
 <Screenshot url="https://www.mongodb.com/products/tools/relational-migrator" src="img/60-image-001.png" alt="Screenshot of the connect modal" />
diff --git a/docs/50-create-project/70-select-tables.mdx b/docs/50-create-project/70-select-tables.mdx
@@ -2,6 +2,6 @@ import Screenshot from "@site/src/components/Screenshot";
 
 # 👐 Select Tables
 
-We want to migrate data from all of the tables, so check all of them and then click Next. 
+We want to migrate data from all of the tables, so check all of them and then click `Next`.
 
 <Screenshot url="https://www.mongodb.com/products/tools/relational-migrator" src="img/70-image-001.png" alt="Screenshot of the connect modal" />
diff --git a/docs/50-create-project/80-define-initial-schema.mdx b/docs/50-create-project/80-define-initial-schema.mdx
@@ -1,15 +1,15 @@
 import Screenshot from "@site/src/components/Screenshot";
 
-# 👐 Define Initial Schema
+# 👐 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. 
 
-Select “Start with a recommended MongoDB schema”
+Select `Start with a recommended MongoDB schema`
 
 You are asked which of the tables should represented as a collection in MongoDB. 
 
-Select the five collections that we want:
+Select the five collections that we want as they are the main Entities in our schema.
 
 - authors
 - books
@@ -21,4 +21,4 @@ Any tables you did not check will be embedded in other collections.
 
 <Screenshot url="https://www.mongodb.com/products/tools/relational-migrator" src="img/80-image-001.png" alt="Screenshot of the connect modal" />
 
-- Click Next, then give your project a name. 
+Click `Next`, then give your project a name. 
diff --git a/docs/50-create-project/_category_.json b/docs/50-create-project/_category_.json
@@ -0,0 +1,7 @@
+{
+    "label": "👐 Create a Project",
+    "link": {
+        "type": "generated-index",
+        "description": "Create your Project in Relational Migrator."
+    }
+}
diff --git a/docs/80-Edit Mapping Rules/10-edit-mapping-books-book-attribute.mdx b/docs/80-Edit Mapping Rules/10-edit-mapping-books-book-attribute.mdx
@@ -1,16 +1,35 @@
 import Screenshot from "@site/src/components/Screenshot";
 
-# 👐 Edit mapping to books collection (from book_attribute table) 
+# 👐 Clean book attributes up  
 
 
-We want to clean up the book_attributes array in our MongoDB schema.
+We want to clean up the book_attributes array in our MongoDB schema. We want an array of objects containing attributes, modelled a key value pairs. something like:
+
+```json
+{
+    "_id": 838383, // book id
+    "attributes": [
+        {
+            "key": "price",
+            "value": 11
+        },
+        {
+            "key": "pages",
+            "value": 236
+        },
+        // ...
+    ] 
+}
+```
 
 - On the MongoDB diagram view, click the `books` collection
 - On the relational mappings list on the right, click on the edit icon of `book_attribute` embedded array mapping rule.
 - Change the Field name from `bookAttributes` to `attributes`
-- Uncheck `bookId`
+- Uncheck `bookId`. We just want all the attributes, which are key/value pairs.
 - Click `Save and close`
 
+Here we've implemented the [Attribute Pattern](https://www.mongodb.com/developer/products/mongodb/attribute-pattern/) for MongoDB.
+
 
 <Screenshot url="https://www.mongodb.com/products/tools/relational-migrator" src="img/150-image-001.png" alt="Screenshot of the connect modal" />
 
diff --git a/docs/80-Edit Mapping Rules/20-edit-mapping-books-book-genre.mdx b/docs/80-Edit Mapping Rules/20-edit-mapping-books-book-genre.mdx
@@ -1,8 +1,8 @@
 import Screenshot from "@site/src/components/Screenshot";
 
-# 👐 Edit mapping to books collection (from book_genre table)
+# 👐 Add genres to books (not only genre ids)
 
-We want to modify the MongoDB schema so that each book's genres are represented as an array of strings. 
+We want to modify the MongoDB schema so that each book's genres are represented as an array of strings. We'll have data duplication, as genres will get copied on each book. This is a good strategy if the duplicated data does not change often.
 
 - On the MongoDB diagram view, click the `books` collection
 - On the relational mappings list on the right, click on the edit icon of `book_genre` embedded array
diff --git a/docs/80-Edit Mapping Rules/30-add-mapping-books-authors.mdx b/docs/80-Edit Mapping Rules/30-add-mapping-books-authors.mdx
@@ -1,9 +1,9 @@
 import Screenshot from "@site/src/components/Screenshot";
 
-# 👐 Add mapping to books collection (from authors table)
+# 👐 Add authors details to the books collection
 
 We want to modify the MongoDB schema so that each book contains an array of its authors.
-In this step we will embed the book details into the empty array from the join table. 
+In this step we will embed the book details into the empty array from the join table (which right now only contains `authorId` and `bookId`)
 
 - On the MongoDB diagram view, click the `books` collection
 - On the relational mappings list on the right, click `+ Add`
@@ -14,5 +14,7 @@ In this step we will embed the book details into the empty array from the join t
 - Click `Save and close` 
 
 
+
+
 <Screenshot url="https://www.mongodb.com/products/tools/relational-migrator" src="img/130-image-001.png" alt="Screenshot of the connect modal" />
 
diff --git a/docs/80-Edit Mapping Rules/40-edit-mapping-books-author-book.mdx b/docs/80-Edit Mapping Rules/40-edit-mapping-books-author-book.mdx
@@ -1,6 +1,6 @@
 import Screenshot from "@site/src/components/Screenshot";
 
-# 👐 Edit mapping to books collection (from author_book table)
+# 👐 Remove unused ids from author details in books collection
 
 We want to modify the MongoDB schema so that each book contains an array of its authors.
 In this step we will remove the redundant ID fields from the join table. 
@@ -11,7 +11,7 @@ In this step we will remove the redundant ID fields from the join table.
 - In the list of fields, uncheck `authorId` and `bookId`, leaving all fields unchecked. 
 - Click `Save and close`
 
-
+What we have now is an implementation of the [Extended reference pattern](https://www.mongodb.com/blog/post/building-with-patterns-the-extended-reference-pattern)
 
 <Screenshot url="https://www.mongodb.com/products/tools/relational-migrator" src="img/140-image-001.png" alt="Screenshot of the connect modal" />
 
diff --git a/docs/80-Edit Mapping Rules/50-add-mapping-books-reviews.mdx b/docs/80-Edit Mapping Rules/50-add-mapping-books-reviews.mdx
@@ -1,6 +1,6 @@
 import Screenshot from "@site/src/components/Screenshot";
 
-# 👐 Add mapping to books collection (from reviews table)
+# 👐 Add last three reviews to each book (from reviews table)
 
 We want to modify the MongoDB schema so that each book contains an array of its latest three reviews.
 This is actually an implementation of the [Subset Pattern](https://www.mongodb.com/blog/post/building-with-patterns-the-subset-pattern).
diff --git a/docs/80-Edit Mapping Rules/60-edit-mapping-authors-alias.mdx b/docs/80-Edit Mapping Rules/60-edit-mapping-authors-alias.mdx
@@ -1,6 +1,6 @@
 import Screenshot from "@site/src/components/Screenshot";
 
-# 👐 Edit mapping to authors collection (from author_alias table)
+# 👐 Add aliases to authors
 
 We want to modify the MongoDB schema so that each author's aliases are represented as an array of strings. 
 
diff --git a/static/img/download-relational-migrator.png b/static/img/download-relational-migrator.png
