DOCSP-44350 Merge app analysis docs

snooty.toml

@@ -19,6 +19,7 @@ toc_landing_pages = [
 "installation/kafka-deployments/migrator-with-kafka",
 "installation/file-location",
 "database-connections/database-connections",
+"app-analysis",
 "projects",
 "mapping-rules/introduction",
 "mapping-rules/mapping-rule-options/introduction",
@@ -58,3 +59,12 @@ variant = "warning"
 value = """\
         DB2 database support is currently in public preview. Users looking for production-grade migration assistance, please contact your account representative to engage in a guided evaluation. 
         """
+
+[[banners]]
+targets = [
+        "app-analysis.txt",
+        ]
+variant = "warning"
+value = """\
+        Pre-Migration Analysis is currently in public preview. Users looking for production-grade migration assistance, please contact your account representative to engage in a guided evaluation. 
+        """

source/app-analysis.txt

@@ -0,0 +1,55 @@
+.. _rm-app-analysis:
+
+======================
+Pre-Migration Analysis
+======================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+After connecting to a supported relational database, run Pre-Migration 
+Analysis to identify potential data and configuration risks before attempting
+data migration. The resulting report summarizes necessary actions to take
+before migrating your data.
+
+.. important::
+
+   Relational Migrator supports Pre-Migration Analysis for Microsoft SQL
+   Server, MySQL, Oracle, and PostgreSQL. Pre-Migration Analysis isn't
+   supported for databases connected through a JDBC driver. For more
+   information on supported databases and versions, see 
+   :ref:`supported-databases`.
+
+Types of Risks
+--------------
+
+Pre-Migration Analysis groups potential risks into the following types:
+
+- Unsupported source database features
+- Data type incompatibilities
+- Schema mapping risks
+- Migration performance risks
+
+After :ref:`running analysis <rm-run-app-analysis>`, the report lists each
+identified risk, its severity, and suggested remediation actions.
+
+For a list of all risks Relational Migrator reports on, see the
+:ref:`Migration Risk Reference <rm-app-analysis-risk-reference>`
+
+
+Get Started
+-----------
+
+- :ref:`Connect to a Database <rm-save-relational-connection>`
+- :ref:`Run Pre-Migration Analysis <rm-run-app-analysis>`
+
+.. toctree::
+   :hidden:
+   :titlesonly:
+
+   Run Pre-Migration Analysis </app-analysis/run-analysis>
+   Analysis Report </app-analysis/analysis-report>
+   Risk Reference </app-analysis/risk-reference>

source/app-analysis/analysis-report.txt

@@ -0,0 +1,138 @@
+.. _rm-analysis-report:
+
+=================================
+The Pre-Migration Analysis Report
+=================================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+The analysis report lists the migration risks detected in your database, and
+provides suggested mitigation actions for each one. To see all the potential
+migration risks that Relational Migrator can detect, see the :ref:`Migration
+Risk Reference <rm-app-analysis-risk-reference>`.
+
+Summary
+-------
+
+The :guilabel:`Summary` section lists the overall migration readiness of your
+database, and provides a breakdown of the metrics that affect that readiness
+level.
+
+Detection Breakdown
+~~~~~~~~~~~~~~~~~~~
+
+The Detection Breakdown shows how many detections have Actions Required,
+are Potential Risks, or are strictly Informational.
+
+.. image:: /img/app-analysis/app-analysis-detection-breakdown.png
+   :alt: A screenshot of the detection breakdown, with the migration readiness level and number of detections.
+
+Database Object Overview 
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+The Database Object Overview shows detections for Tables, Stored Procedures,
+Triggers, and Views. Table risks are further categorized as Data Type, Schema,
+Unsupported Feature, or Performance.
+
+.. note::
+
+   Pre-Migration Analysis doesn't analyze the SQL code of stored
+   procedures, views, and triggers. If your database has procedures that may
+   present an issue, please contact your account representative.
+
+.. image:: /img/app-analysis/app-analysis-db-objects.png
+   :alt: A screenshot of the database object overview, with the number of detections of each type.
+
+Once you've addressed the migration risks, you can run Pre-Migration Analysis
+again by clicking :guilabel:`Rerun analysis` to confirm that there aren't any
+more issues.
+
+Database
+--------
+
+The :guilabel:`Database` section lists all detected risks for your relational
+database. If you use the :guilabel:`Status` column of the table to mark
+resolved risks, they are hidden from the list. Check :guilabel:`Include
+resolved detections` to show them.
+
+You can switch between tabs for more information on different types of 
+detections.
+
+The All detections tab
+~~~~~~~~~~~~~~~~~~~~~~
+
+This is the default tab, and shows all detections in a single table. You can
+use the dropdown to switch between :guilabel:`Show all`, :guilabel:`Tasks
+only`, :guilabel:`Risks only`, and :guilabel:`Notes only`. 
+
+The Tables tab
+~~~~~~~~~~~~~~
+
+The :guilabel:`Tables` tab lists detections for each table. The
+:guilabel:`Overview and Analysis` toggle shows detections. Switch it to
+:guilabel:`Columns` to see the column definitions for the selected table.
+
+The Stored Procedures tab
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. note::
+
+   Pre-Migration Analysis doesn't analyze stored procedure SQL code 
+   for risks.
+
+The :guilabel:`Stored Procedures` tab shows each procedure. Switch the 
+:guilabel:`Overview and Analysis` toggle to :guilabel:`SQL code`
+to see the code for the selected procedure.
+
+The Triggers tab
+~~~~~~~~~~~~~~~~
+
+.. note::
+
+   Pre-Migration Analysis doesn't analyze trigger SQL code for
+   risks, because MongoDB doesn't natively support triggers. Consider using
+   :ref:`Query Converter <rm-query-converter>` to convert your SQL to
+   :atlas:`Atlas Triggers </atlas-ui/triggers/>`, in order to replicate
+   existing behavior.
+
+The :guilabel:`Triggers` tab shows each trigger. Switch the 
+:guilabel:`Overview and Analysis` toggle to :guilabel:`SQL code`
+to see the code for the selected trigger.
+
+The Views tab
+~~~~~~~~~~~~~
+
+.. note::
+
+   Pre-Migration Analysis doesn't analyze view definitions for
+   risks, because views must be converted to MQL. Consider using :ref:`Query
+   Converter <rm-query-converter>` to migrate views.
+
+The :guilabel:`Views` tab shows each view. Switch the 
+:guilabel:`Overview and Analysis` toggle to :guilabel:`SQL code`
+to see the SQL definition for the selected view.
+
+The Incompatible features tab
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The :guilabel:`Incompatible features` tab lists incompatible features in your
+source database that either don't have a MongoDB equivalent, or work
+differently enough that Relational Migrator can't automatically migrate them.
+
+Prerequisites
+-------------
+
+The :guilabel:`Prerequisites` section lists necessary tasks to prepare your
+database for migration. This is a targeted list of recommendations based on the
+information gathered during Pre-Migration Analysis. For general information on
+database prerequisites, see :ref:`rm-prerequisites`.
+
+Resources
+---------
+
+The :guilabel:`Planning Resources` section lists links to MongoDB blogs and
+documentation content about data modeling and migration.