diff --git a/docs/0-intro.mdx b/docs/0-intro.mdx index 1ca4f6d..976db02 100644 --- a/docs/0-intro.mdx +++ b/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| diff --git a/docs/05-what-is-the-mongodb-relational-migrator.mdx b/docs/05-what-is-the-mongodb-relational-migrator.mdx new file mode 100644 index 0000000..69b266a --- /dev/null +++ b/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. diff --git a/docs/10-dev-env/1-dev-env-setup.mdx b/docs/10-dev-env/1-dev-env-setup.mdx index 23905e8..3f45876 100644 --- a/docs/10-dev-env/1-dev-env-setup.mdx +++ b/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
🦹 __Run this lab locally__ + + :::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. - + --- - 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. - -
- - - + 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. + \ No newline at end of file diff --git a/docs/10-dev-env/10-postgres.mdx b/docs/10-dev-env/10-postgres.mdx index 6f8e02e..6dd8752 100644 --- a/docs/10-dev-env/10-postgres.mdx +++ b/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. :::
diff --git a/docs/30-schema-in-postgresql.mdx b/docs/30-schema-in-postgresql.mdx index 757dcfa..e0d8871 100644 --- a/docs/30-schema-in-postgresql.mdx +++ b/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_ \ No newline at end of file +_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). +::: \ No newline at end of file diff --git a/docs/40-desired-schema-mongodb.mdx b/docs/40-desired-schema-mongodb.mdx index 20ef509..d411f22 100644 --- a/docs/40-desired-schema-mongodb.mdx +++ b/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. diff --git a/docs/50-create-project/50-create-new-project.mdx b/docs/50-create-project/50-create-new-project.mdx index 6155509..7f4cf89 100644 --- a/docs/50-create-project/50-create-new-project.mdx +++ b/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 + + + 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`. - + + + + + + + Click on the `New Project` button in the top right corner of the Relational Migrator UI. + + + + + ## 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. diff --git a/docs/50-create-project/60-connect-database.mdx b/docs/50-create-project/60-connect-database.mdx index 30aa3d4..99dc7dc 100644 --- a/docs/50-create-project/60-connect-database.mdx +++ b/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. - -:::info -πŸ¦Έβ€β™‚οΈ If you have followed the steps to configure PostgreSQL in a docker container, the hostname will be `localhost`, username `postgres` and password `postgres`. -::: \ No newline at end of file diff --git a/docs/50-create-project/80-define-initial-schema.mdx b/docs/50-create-project/80-define-initial-schema.mdx index 6dd5ee2..33e9922 100644 --- a/docs/50-create-project/80-define-initial-schema.mdx +++ b/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. - + Select the casing you'd like for your collections - the default is camelCase. diff --git a/docs/50-create-project/_category_.json b/docs/50-create-project/_category_.json index 7e77ae1..13843b4 100644 --- a/docs/50-create-project/_category_.json +++ b/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." } } \ No newline at end of file diff --git a/docs/55-pre-migration-analysis.mdx b/docs/55-pre-migration-analysis.mdx new file mode 100644 index 0000000..bf6767b --- /dev/null +++ b/docs/55-pre-migration-analysis.mdx @@ -0,0 +1,48 @@ +import Screenshot from "@site/src/components/Screenshot"; + +# πŸ‘ Pre migration analysis + +:::info +This feature is in Preview at this moment, so features / UI could change. Also, review the results as they could be improved in the future. +::: + +Get a detailed risk assessment and tailored recommendations to migrate your application successfully. + +## Generate the report + +We can generate a report of the schema we are about to migrate. This is useful to understand the structure of the data and how it will be represented in MongoDB. + +- To do that, click on the `Pre-Migration Analysis` tab. +- Then click on `Run analysis`. + + + +## Review the Summary + +You'll see a summary of the analysis, which includes: +- The _Predicted migration readiness level_, that will give you a rough idea of how ready your schema is for migration. +- The number of tables, stored procedures, triggers and views in the relational schema. +- The size of the database. + +## Review the Database + +If you click in `Database`, you can see all detected risks in the `Impact analysis` tab. + +From there, you can review the Tables in detail, including number of rows, columns, types, etc. + + + +You can also check the Stored procedures, Trriggers and Views and even review the SQL code. + + + +## Migration Prerequisites + +In the `Migration prerequisites` tab, you can the prerequisites for the migration. In this case, we see that `Postgres Write-Ahead Logging (WAL) logical replication must be enabled in Postgres before running a Continuous migration job.` + + + + +## Resources + +More information and documentation to help you plan your migration. \ No newline at end of file diff --git a/static/img/110-image-001.png b/static/img/110-image-001.png index f015cc6..b5ea659 100644 Binary files a/static/img/110-image-001.png and b/static/img/110-image-001.png differ diff --git a/static/img/120-image-001.png b/static/img/120-image-001.png index f8bd1d7..ab872d8 100644 Binary files a/static/img/120-image-001.png and b/static/img/120-image-001.png differ diff --git a/static/img/130-image-001.png b/static/img/130-image-001.png index e8b4e31..a658cfc 100644 Binary files a/static/img/130-image-001.png and b/static/img/130-image-001.png differ diff --git a/static/img/140-image-001.png b/static/img/140-image-001.png index 0a09094..95f6b2c 100644 Binary files a/static/img/140-image-001.png and b/static/img/140-image-001.png differ diff --git a/static/img/150-image-002.png b/static/img/150-image-002.png index 6172ea3..9ca26ce 100644 Binary files a/static/img/150-image-002.png and b/static/img/150-image-002.png differ diff --git a/static/img/170-image-001.png b/static/img/170-image-001.png index a38cec3..3171411 100644 Binary files a/static/img/170-image-001.png and b/static/img/170-image-001.png differ diff --git a/static/img/180-image-001.png b/static/img/180-image-001.png index cabf26d..c9ba24c 100644 Binary files a/static/img/180-image-001.png and b/static/img/180-image-001.png differ diff --git a/static/img/190-image-001.png b/static/img/190-image-001.png index 643c400..c0af414 100644 Binary files a/static/img/190-image-001.png and b/static/img/190-image-001.png differ diff --git a/static/img/200-image-001.png b/static/img/200-image-001.png index 7ca2956..b264925 100644 Binary files a/static/img/200-image-001.png and b/static/img/200-image-001.png differ diff --git a/static/img/210-image-001.png b/static/img/210-image-001.png index beccb68..294868d 100644 Binary files a/static/img/210-image-001.png and b/static/img/210-image-001.png differ diff --git a/static/img/210-image-005.png b/static/img/210-image-005.png index 287993d..fc300c0 100644 Binary files a/static/img/210-image-005.png and b/static/img/210-image-005.png differ diff --git a/static/img/220-image-006.png b/static/img/220-image-006.png index a1e36b9..842ee66 100644 Binary files a/static/img/220-image-006.png and b/static/img/220-image-006.png differ diff --git a/static/img/220-image-012.png b/static/img/220-image-012.png index c50b404..6393928 100644 Binary files a/static/img/220-image-012.png and b/static/img/220-image-012.png differ diff --git a/static/img/220-image-013.png b/static/img/220-image-013.png index 3b308b9..14b5e6f 100644 Binary files a/static/img/220-image-013.png and b/static/img/220-image-013.png differ diff --git a/static/img/50-image-000.png b/static/img/50-image-000.png new file mode 100644 index 0000000..8b40932 Binary files /dev/null and b/static/img/50-image-000.png differ diff --git a/static/img/65-pre-migration-001.png b/static/img/65-pre-migration-001.png new file mode 100644 index 0000000..f13cfe1 Binary files /dev/null and b/static/img/65-pre-migration-001.png differ diff --git a/static/img/65-pre-migration-002.png b/static/img/65-pre-migration-002.png new file mode 100644 index 0000000..24539ba Binary files /dev/null and b/static/img/65-pre-migration-002.png differ diff --git a/static/img/65-pre-migration-003.png b/static/img/65-pre-migration-003.png new file mode 100644 index 0000000..8b8428e Binary files /dev/null and b/static/img/65-pre-migration-003.png differ diff --git a/static/img/65-pre-migration-004.png b/static/img/65-pre-migration-004.png new file mode 100644 index 0000000..8a71d8e Binary files /dev/null and b/static/img/65-pre-migration-004.png differ diff --git a/static/img/90-image-001.png b/static/img/90-image-001.png index 71e329b..630f85c 100644 Binary files a/static/img/90-image-001.png and b/static/img/90-image-001.png differ diff --git a/static/img/convert-sprocs.png b/static/img/convert-sprocs.png index 8608a0b..28025e3 100644 Binary files a/static/img/convert-sprocs.png and b/static/img/convert-sprocs.png differ diff --git a/static/img/convert-sql-queries.png b/static/img/convert-sql-queries.png index 2f6dd52..8627d6c 100644 Binary files a/static/img/convert-sql-queries.png and b/static/img/convert-sql-queries.png differ diff --git a/static/img/download-relational-migrator.png b/static/img/download-relational-migrator.png index dd5a415..ea0be64 100644 Binary files a/static/img/download-relational-migrator.png and b/static/img/download-relational-migrator.png differ diff --git a/static/img/generate-app-code.png b/static/img/generate-app-code.png index 94d6b8a..c464a13 100644 Binary files a/static/img/generate-app-code.png and b/static/img/generate-app-code.png differ