DOCSP-41417-add-db2-support-content (#158)

ianf-mongodb · mmaville-mdb · web-flow · commit e0b1515ddd93 · 2024-08-20T09:13:00.000-04:00
* DOCSP-41417-add-db2-support-content * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Apply suggestions from code review Co-authored-by: Matt Maville <150086858+mmaville-mdb@users.noreply.github.com> * * * * * * * * * * --------- Co-authored-by: Matt Maville <150086858+mmaville-mdb@users.noreply.github.com>
diff --git a/snooty.toml b/snooty.toml
@@ -47,3 +47,14 @@ job = "sync job" #this will be updated to migration job in the near future.
 job_plural = "sync jobs" #this will be updated to migration jobs in the near future.
 migrator-api = "REST API Documentation"
 migrator-api-endpoints = "Endpoints"
+
+[[banners]]
+targets = [
+        "jobs/prerequisites/db2.txt",
+        "jobs/prerequisites/sybase.txt"
+        ]
+variant = "warning"
+value = """\
+        DB2 and Sybase 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. 
+        """
+
diff --git a/source/connection-strings/relational-database-connection-strings.txt b/source/connection-strings/relational-database-connection-strings.txt
@@ -25,6 +25,7 @@ Relational Migrator can connect to the following relational database systems:
 - `PostgreSQL <#postgresql>`__
 - `SQL Server <#sql-server>`__
 - `Sybase ASE <#sybase-ase>`__
+- `DB2 <#db2>`__
 
 Relational Migrator's connection form contains fields where you can specify a
 username and password for the connection. The form obscures passwords
@@ -214,4 +215,41 @@ The general form for a Sybase ASE connection string is:
    To learn more about Sybase ASE connection strings, see:
 
    - `Sybase ASE Connection String Docs <https://infocenter.sybase.com/help/index.jsp?topic=/com.sybase.infocenter.dc01776.1601/doc/html/san1357754914053.html>`__
-   - `Connectingstrings.com <https://www.connectionstrings.com/sybase-adaptive/>`__
+   - `Connectingstrings.com <https://www.connectionstrings.com/sybase-adaptive/>`__
+
+DB2
+---
+
+The general form for a DB2 connection string is:
+
+.. code-block::
+
+   jdbc:db2://<hostname>:<port>/<database>;
+
+For example, consider the following connection string:
+
+.. code-block::
+
+   jdbc:db2://localhost:50000/mydb2database;
+
+The preceding connection string specifies these connection
+details:
+
+.. list-table::
+   :header-rows: 1
+
+   * - Property
+     - Value
+   * - Host
+     - ``localhost``
+   * - Port
+     - ``50000``
+   * - Database
+     - ``mydb2database``
+
+.. note::
+
+   To learn more about DB2 connection strings, see:
+
+   - `DB2 Connection URL Syntax <https://www.ibm.com/docs/en/db2woc?topic=programmatically-jdbc>`__
+   - `Connection Configuration Properties <https://www.ibm.com/docs/en/db2/11.5?topic=SSEPGG_11.5.0/com.ibm.db2.luw.apdv.java.doc/src/tpc/imjcc_r0052342.htm>`__
diff --git a/source/includes/fact-driver-download-locations.rst b/source/includes/fact-driver-download-locations.rst
@@ -0,0 +1,5 @@
+- `MySQL: latest 8.3.x version, Platform Independent Version <https://dev.mysql.com/downloads/connector/j/>`_
+
+- `Oracle: 21.6.0.0 of ojdbc11.jar from the Oracle 21c <https://www.oracle.com/database/technologies/appdev/jdbc-downloads.html>`_
+
+- `DB2: latest 3.x or 4.x db2jcc.jar <https://www.ibm.com/support/pages/db2-jdbc-driver-versions-and-downloads>`_
diff --git a/source/installation/install-on-a-local-machine/install-mac.txt b/source/installation/install-on-a-local-machine/install-mac.txt
@@ -26,11 +26,9 @@ Steps
 
 #. (Optional) To connect to Oracle or MySQL drivers, download and place the drivers into your Relational Migrator directory.
 
-   a. To download and install MySQL or Oracle drivers, see the following:
-      
-      - `MySQL: latest 8.3.x version, Platform Independent Version <https://dev.mysql.com/downloads/connector/j/>`_
-
-      - `Oracle: 21.6.0.0 of ojdbc11.jar from the Oracle 21c <https://www.oracle.com/database/technologies/appdev/jdbc-downloads.html>`_
+   a. To download and install MySQL, Oracle or DB2 drivers, see the following:
+   
+      .. include:: /includes/fact-driver-download-locations.rst
 
    b. Copy the driver files to ``/Library/Application Support/MongoDB/Relational Migrator/Drivers``.
 
diff --git a/source/installation/install-on-a-local-machine/install-on-a-local-machine.txt b/source/installation/install-on-a-local-machine/install-on-a-local-machine.txt
@@ -44,6 +44,10 @@ If you are migrating from an Oracle database:
 - (Optional) To migrate tables that contain the ``XMLType`` type, you must also download the 
   `xdb.jar <https://www.oracle.com/database/technologies/appdev/jdbc-drivers-archive.html>`__ driver. 
 
+If you are migrating from a DB2 database:
+
+- Download `db2jcc.jar for DB2 <https://www.ibm.com/support/pages/db2-jdbc-driver-versions-and-downloads>`_. 
+
 Get Started
 -----------
 
diff --git a/source/installation/install-on-a-local-machine/install-rhel.txt b/source/installation/install-on-a-local-machine/install-rhel.txt
@@ -35,11 +35,9 @@ Steps
 #. (Optional) To connect to Oracle or MySQL drivers, download and place the drivers 
    into your Relational Migrator directory.
 
-   a. To download and install MySQL or Oracle drivers, see the following:
+   a. To download and install MySQL, Oracle or DB2 drivers, see the following:
 
-      - `MySQL: latest 8.3.x version, Platform Independent Version <https://dev.mysql.com/downloads/connector/j/>`_
-
-      - `Oracle: 21.6.0.0 of ojdbc11.jar from the Oracle 21c <https://www.oracle.com/database/technologies/appdev/jdbc-downloads.html>`_
+      .. include:: /includes/fact-driver-download-locations.rst
 
    b. Copy the driver files to ``/opt/mongodb-relational-migrator/lib/app/lib``.
 
diff --git a/source/installation/install-on-a-local-machine/install-ubuntu.txt b/source/installation/install-on-a-local-machine/install-ubuntu.txt
@@ -35,11 +35,9 @@ Steps
 #. (Optional) To connect to Oracle or MySQL drivers, download and place the drivers 
    into your Relational Migrator directory.
 
-   a. To download and install MySQL or Oracle drivers, see the following:
+   a. To download and install MySQL, Oracle or DB2 drivers, see the following:
 
-      - `MySQL: latest 8.3.x version, Platform Independent Version <https://dev.mysql.com/downloads/connector/j/>`_
-
-      - `Oracle: 21.6.0.0 of ojdbc11.jar from the Oracle 21c <https://www.oracle.com/database/technologies/appdev/jdbc-downloads.html>`_
+      .. include:: /includes/fact-driver-download-locations.rst
 
    b. Copy the driver files to ``/opt/mongodb-relational-migrator/lib/app/lib``.
 
diff --git a/source/installation/install-on-a-local-machine/install-windows.txt b/source/installation/install-on-a-local-machine/install-windows.txt
@@ -34,11 +34,9 @@ Steps
 #. (Optional) To connect to Oracle or MySQL drivers, download and place the drivers 
    into your Relational Migrator directory.
 
-   a. To download and install MySQL or Oracle drivers, see the following:
+   a. To download and install MySQL, Oracle or DB2 drivers, see the following:
 
-      - `MySQL: latest 8.3.x version, Platform Independent Version <https://dev.mysql.com/downloads/connector/j/>`_
-
-      - `Oracle: 21.6.0.0 of ojdbc11.jar from the Oracle 21c <https://www.oracle.com/database/technologies/appdev/jdbc-downloads.html>`_
+      .. include:: /includes/fact-driver-download-locations.rst
 
    b. Copy the driver files to ``c:\Users\<username>\AppData\Local\MongoDB\Relational Migrator\Data\Drivers``.
 
diff --git a/source/jobs/creating-jobs.txt b/source/jobs/creating-jobs.txt
@@ -75,7 +75,9 @@ Steps
           - Leaving database name blank loads schemas from the default database.
         * - Sybase ASE
           - Leaving database name blank loads schemas from the default database.
-  
+        * - DB2
+          - You must enter a database name.
+
       2e. Enter a username in the :guilabel:`Username` text box. 
 
       2f. Enter a password in the :guilabel:`Password` text box. 
diff --git a/source/jobs/prerequisites.txt b/source/jobs/prerequisites.txt
@@ -45,6 +45,10 @@ first sync job:
      - :icon-lg:`Checkmark`
      - 
 
+   * - :ref:`DB2 <rm-prereq-db2>`
+     - :icon-lg:`Checkmark`
+     - 
+
 .. toctree::
    :titlesonly:
    :hidden:
@@ -54,3 +58,4 @@ first sync job:
    /jobs/prerequisites/postgres
    /jobs/prerequisites/sql-server
    /jobs/prerequisites/sybase
+   /jobs/prerequisites/db2
diff --git a/source/jobs/prerequisites/db2.txt b/source/jobs/prerequisites/db2.txt
@@ -0,0 +1,73 @@
+.. _rm-prereq-db2:
+
+=========================================
+Configure Migration Prerequisites for DB2
+=========================================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+To run sync jobs from a DB2 source database, the target database requires
+creating a specific schema and a specific table within the schema in the 
+database you are migrating. If Relational Migrator determines the database 
+needs configuration changes, it automatically generates a SQL script with 
+the required changes. It is recommended to have a Database Administrator (DBA) 
+review the commands in this script and perform their execution on the database server.
+
+Before you Begin
+----------------
+
+Download and install the DB2 jdbc driver to the correct Relational Migrator
+directory. For details, see the :ref:`local-machine-install` for 
+your operating system.
+
+About this Task
+---------------
+
+- This page covers the details of the SQL scripts automatically 
+  generated by Relational Migrator.
+
+- Relational Migrator automatically detects configuration settings when 
+  connecting to your database and generates the appropriate SQL 
+  statements.
+
+- Relational Migrator does not create any indexes on your DB2 instance to 
+  facilitate sync jobs. The create index creation permission is not 
+  required.
+
+- Creating the required schema and table have no impact on database performance.
+
+- Relational Migrator does not support ``BLOB``, ``CBLOB`` or ``DBCLOB`` columns 
+  of DB2 tables. If this feature is important to you, create or upvote the 
+  feature request on `feedback.mongodb.com <https://feedback.mongodb.com/forums/952450-relational-migrator>`__.
+  
+- Relation Migrator only supports snapshot sync jobs for DB2 connections.
+
+Steps
+-----
+
+.. procedure::
+   :style: normal
+
+   .. step:: Create the ``ASNCDC`` schema
+
+      Use the following statements to create the schema: 
+
+      .. code-block:: sql
+         :copyable: true
+
+         CREATE SCHEMA "ASNCDC";
+
+   .. step:: Create the ``IBMSNAP_REGISTER`` table in the ``ASNCDC`` schema
+
+      Use the following statements to create the table:
+
+      .. code-block:: sql
+         :copyable: true
+
+         CREATE TABLE "ASNCDC"."IBMSNAP_REGISTER" 
+         (SYNCHPOINT INTEGER, CD_NEW_SYNCHPOINT INTEGER);
+   
diff --git a/source/projects/create-project-live-connection.txt b/source/projects/create-project-live-connection.txt
@@ -44,6 +44,7 @@ Steps
    - PostgreSQL
    - SQL Server
    - Sybase ASE
+   - DB2
 
 #. Enter the connection details to create the JDBC URI for your relational database.
 
@@ -77,6 +78,9 @@ Steps
          * - Sybase ASE
            - The database name is required. 
 
+         * - DB2
+           - The database name is required. 
+        
    d. Enter a user name in the :guilabel:`Username` text box.
 
    e. Enter a password in the :guilabel:`Password` text box.
diff --git a/source/projects/create-project-loading-schema-files.txt b/source/projects/create-project-loading-schema-files.txt
@@ -108,6 +108,11 @@ to generate DDL files from your relational system.
 
       Importing DDL files with Sybase ASE is not supported.
 
+   .. tab:: DB2
+      :tabid: db2-ddl
+
+      Importing DDL files with DB2 is not supported.
+
 Steps
 -----
 
