Merge pull request #188 from nvillahermosa-mdb/DOCSP-45339-oracle-migration-prereqs

DOCSP-45339 Update Oracle migration prerequisites

Author: nvillahermosa-mdb

source/includes/fact-data-prep-oracle-step1.rst

@@ -4,18 +4,22 @@ instance. Alternatively, you can use an existing Oracle
 service account to connect to Relational Migrator with 
 the appropriate permissions.
 
+.. tip::
+
+   To migrate data from a multi-tenant container database, `create tablespaces
+   and a Common User <https://oracle-base.com/articles/12c/multitenant-manage-users-and-privileges-for-cdb-and-pdb-12cr1>`__.
+
 a. Create a service account:
 
    .. code-block:: sql
       :copyable: true
 
       CREATE USER '<user>'@'localhost' IDENTIFIED BY '<password>';
 
-#. Grant select permissions to the service account:
+#. Confirm that the service account owns the tables in the migration job.
 
-   The required permission for the service account depend on whether 
-   the tables are owned by the service account used to run the migration job.
-   To check table ownership run the following query:
+   Required permissions depend on whether the service account owns the tables
+   used in the migration job. To check table ownership, run the following query:
 
    .. code-block:: sql
       :copyable: true
@@ -25,6 +29,19 @@ a. Create a service account:
       WHERE TABLE_NAME ='<table_name>'
       ORDER BY OWNER, TABLE_NAME;
 
+#. Grant permissions to the service account.
+
+   .. important::
+      
+      If you're migrating a multi-tenant container database as a
+      common user, append ``CONTAINER=ALL`` when granting permissions. For
+      example:
+
+      .. code-block:: sql
+         :copyable: false
+      
+         GRANT CREATE SESSION TO <user> CONTAINER=ALL;
+   
    If the service account *is* the table owner:
 
    .. code-block:: sql

source/includes/fact-short-sync-job-desc.rst

@@ -1,3 +1,3 @@
-- Snapshot migration jobs migrate all the data and then stops.
-- Continuous migration job run a snapshot and then enter a CDC stage to 
-  continuously replicate data changes.
+- Snapshot migration jobs migrate all data once, and then stop.
+- Continuous migration jobs run a snapshot migration and then enter a CDC stage, which 
+  continuously replicates data changes.

source/jobs/prerequisites/oracle.txt

@@ -10,13 +10,12 @@ Configure Migration Prerequisites for Oracle
    :depth: 1
    :class: singlecol
 
-To run migration jobs from an Oracle source database, the database may require 
-some configuration changes. 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. The 
-Oracle configurations depend on the type of migration job:
+When you migrate data from an Oracle source database, Relational Migrator 
+automatically checks your database for needed configuration changes and 
+generates a SQL script to implement them. Have a Database Administrator (DBA)
+review the script and run the commands on the database server.
+
+Oracle configuration depends on the type of migration job:
 
 .. include:: /includes/fact-short-sync-job-desc.rst
 
@@ -28,13 +27,15 @@ About this Task
 
 - If you're migrating from an Oracle 12c instance, you must run commands as 
   the SYSDBA role.
-- In Oracle 12c the concept of a pluggable database was introduced. Some
-  of these commands can be run on PDB(plugable database) while commands 
-  such as enabling ``ARCHIVELOG`` must be run on the
-  CDB(container/master database). For details on each architecture, 
-  see `Overview of Container Databases and Pluggable Databases
-  <https://oracle-base.com/articles/12c/multitenant-overview-container-database-cdb-12cr1>`__.
-- Supplemental logging is not allowed in Oracle Express editions.
+- Oracle 12c introduced the concept of a pluggable database (PDB). Some
+  commands can be run on a PDB, while commands like enabling ``ARCHIVELOG``
+  must be run on the container/master database (CDB). For details on each
+  architecture, see `Overview of Container Databases and Pluggable Databases <https://oracle-base.com/articles/12c/multitenant-overview-container-database-cdb-12cr1>`__.
+- Some commands differ based on whether the database is single or
+  multi-tenant. In a multi-tenant database, permissions must
+  include the suffix ``CONTAINER=ALL``.
+- You can't run a continuous migration job against Oracle Database Express 
+  Edition (XE), because XE doesn't support the necessary logs.
 
 Steps
 -----
@@ -61,8 +62,10 @@ Steps
 
             .. include:: /includes/fact-data-prep-oracle-step1.rst
 
-            c. Grant additional permissions to the service account 
-               to run continuous migration jobs:
+            d. Grant additional permissions to the service account 
+               to run continuous migration jobs. 
+               
+               Append ``CONTAINER=ALL`` if you're migrating a multi-tenant container database.
 
                .. code-block:: sql
                   :copyable: true
@@ -86,46 +89,48 @@ Steps
                   GRANT SELECT ON V$ARCHIVED_LOG TO <user>;
                   GRANT SELECT ON V$ARCHIVE_DEST_STATUS TO <user>;
                   GRANT SELECT ON V$TRANSACTION TO <user>;
+                  GRANT SELECT ON V_$MYSTAT TO <user>;
+                  GRANT SELECT ON V_$STATNAME TO <user>; 
 
-         .. step:: Turn on ``LogMiner`` at the database level
-            
-            To run continous jobs against Oracle, you must enable 
-            ``LogMiner`` at the database level. The following code-block
-            is an example of automatically-generated code, which you 
-            can run manually by substituting your database name:
-
-            .. code-block:: sql
-                :copyable: true
-
-                ALTER SYSTEM SET db_recovery_file_dest_size = 10G;
-                ALTER SYSTEM SET db_recovery_file_dest = '/opt/oracle/oradata/recovery_area' SCOPE=spfile;
-                SHUTDOWN IMMEDIATE;
-                STARTUP MOUNT
-                ALTER DATABASE ARCHIVELOG;
-                ALTER DATABASE OPEN;
+         .. step:: Turn on archive logging
 
-            .. tip::
+            a. To see if archive logging is already enabled, run the following query:
+
+               .. code-block:: sql
+                  :copyable: true
 
-                To check if ``LogMiner`` is already enabled, run the 
-                following query:
+                  SELECT LOG_MODE FROM V$DATABASE;
 
-                .. code-block:: sql
-                   :copyable: true
+               This outputs ``ARCHIVELOG`` if logging is enabled, or
+               ``NOARCHIVELOG`` if it isn't.
+            
+            #. If archive logging isn't already enabled,  enable it. 
+            
+               Relational Migrator can automatically generate code to enable
+               logging. The following code is an example. If you're migrating a
+               multi-tenant database, run these commands on the container/
+               master database.
+
+               .. code-block:: sql
+                  :copyable: true
 
-                    SELECT LOG_MODE FROM V$DATABASE; 
+                  ALTER SYSTEM SET db_recovery_file_dest_size = 10G;
+                  ALTER SYSTEM SET db_recovery_file_dest = '/opt/oracle/oradata/recovery_area' scope=spfile;
+                  SHUTDOWN IMMEDIATE;
+                  STARTUP MOUNT
+                  ALTER DATABASE ARCHIVELOG;
+                  ALTER DATABASE OPEN;
 
          .. step:: Enable supplemental logging
 
-            a. To run continuous migration jobs against Oracle, you must 
-               enable supplemental logging at the database level:
+            a. Enable supplemental logging on the database:
 
                .. code-block:: sql
                   :copyable: true
 
                   ALTER DATABASE ADD SUPPLEMENTAL LOG DATA; 
 
-            #. You must also enable supplemental logging for every 
-               table in the migration:
+            #. Enable supplemental logging for every table in the migration:
 
                .. code-block:: sql
                   :copyable: true