Oracle Cloud Infrastructure Documentation

Managing Migration Jobs

In Oracle Cloud Infrastructure Database Migration, a migration job is the process of moving data from a source database to a target database. Run a validation pre-check on the migration before you run a job to ensure that it is configured properly. You can manage the jobs with several operations.

Validating a Migration

Before you can run a job with a migration resource in Oracle Cloud Infrastructure Database Migration, the migration resource must be validated.

  1. In the list of migrations on the Migrations page, select Validate from the Actions (three dots) menu for the migration you want to validate.
    You can also select Validate on the Migration Details page.
  2. In the Validate Migration dialog, click Validate.
  3. Click Jobs on the left side of the page to monitor the status of a validation job.

    In the Jobs table the validation job is listed with type Evaluation.

If you enabled the Cloud Pre-migration Advisor Tool (CPAT) to run during the validation job, the CPAT report and details about any failed checks are found in the Job Details page. See Configuring Validation Options and Checking the Interactive Validation Premigration Advisor Report for more information.

Checking the Interactive Validation Premigration Advisor Report

Database Migration provides you with an interactive validation report with its integration with the Cloud Premigration Advisor Tool (CPAT). Using CPAT, Database Migration analyzes the source database during a migration job, and advises you about database features and constructs that are problematic, based on the specified Oracle Cloud target. CPAT runs by default and provides you with the following features and benefits:

  • Warns you about any features used by your database that aren't supported in the target environment

  • Makes suggestions for remedial changes and/or parameters to use for the Data Pump export and import operations

  • Generates remedial scripts for failing checks that you can run against the source database

After a validation job runs, the job output displays the checks performed, descriptions of any problems, and actions you can take to resolve the issues.

To view or download the CPAT results

  1. On a migration resource detail page, click Jobs, then the job name, then Phases.

  2. Click the Validate pre-migration advisor phase name to open the Validation pre-migration advisor detail page.

    From this page you can download the CPAT report, view the report statistics, and drill down in the Checks list.

Checks List Operations

Filters: You can filter the checks listed using the Filters checkboxes on the left side.

Drill down on individual checks: Click a check name in the list to display details about that check from the CPAT report.

Check Details

The View check details panel shows you

  • Information about the check, including the issue that caused the result shown, its potential impact on the migration, any action you can take to mitigate the issue, and if applicable, the location of a fixup script you can run on the source database.

  • A Reviewed indicator, which lets you mark a check as "reviewed" so that you can see in the Validate premigration advisor list of checks whether you have completed whatever tasks you wanted to do with the check.

    Click the link in the check details to change it to a No or Yes value. The indicator does not have any impact on how the checks are processed; it is available for your convenience.

  • A list of Objects that were flagged by the check as problematic.

    Some checks will show a read-only list of objects and some checks let you interactively update the objects listed.

Running Fixup Scripts

The location of the fixup script is shown on the View check details panel for an individual check.

The Fixup script location specifies where the script is located on the source database.

Running the fixup script against the source database requires sys admin privileges.

In multitenant architecture, fixup scripts should be run on the CDB. Running them on the PDB will produce an error.

Excluding Problematic Objects

After a validation run, every object listed in the View check details pane shows a No in the Is excluded column.

To exclude objects from the next validation run, you can check the boxes next to objects in the list and click Exclude selected, or you can choose Exclude all to exclude all objects that were listed in the check.

Any objects you choose to exclude will show a Yes in the Is excluded column. Objects marked Yes are ignored by CPAT in the next validation run, and they will not appear in the Objects list the next time you run the validation.

The migration's Selected Objects configuration is also updated to reflect this change. You will see a new row with the exclusion rule in the Selected Objects on the Migration details page. If you want to include this object again you must remove the rule in the Selected Objects list.

Note that Exclude all will exclude all of the objects on the page displayed, plus any objects from pages not displayed. However, if you check the first box in the checkbox column and click Exclude all, only the objects listed on the current page are excluded.

Note

Excluding tables does not exclude them from CPAT analysis. Schemas can be excluded from CPAT if the entire schema was excluded. The presence of an Oracle Cloud unsupported table can lead to Blocker status in the CPAT report.

See Selecting objects for Oracle Migration for information about explicitly including and excluding objects.

Running a Migration Job

After a migration resource is validated you can run migration jobs with it in Oracle Cloud Infrastructure Database Migration.

  1. In the list of migrations on the Migrations page, select Start from the Actions (three dots) menu for the migration you want to run.
    You can also select Start on the Migration Details page.
  2. (Optional) In the confirmation dialog, select a phase after which to require user input to continue the migration job.
  3. Click Start.

Pausing and Resuming a Job

When you start a migration job, you can configure it to pause at a specified phase, and then you can resume the job when you are ready.

When you start a migration job, a confirmation dialog opens, and there you can configure the job to pause at any point by selecting a phase in Require User Input After.

When the phase you selected to pause after completes, the job will enter a Waiting state until you resume (or terminate) the job.

If you pause after the phase Monitor Replication Lag, the transaction replication continues during the Waiting state. It will stop upon resume.

To start the job where it left off, do one of the following:

  • In the Jobs table on the Migration Details page, select Resume from the Actions (three dots) menu for the job you want to resume.

  • Click Resume on the Job Details page.

At this time you can select another phase after which to pause the job again.

Viewing Job Details

On the Migration Details page you can view a list of the jobs a migration resource has performed in Oracle Cloud Infrastructure Database Migration, which includes the following information:

  • Name: Name of the job

  • State: State of the job resource, which can be any one of the following:

    • Accepted: The job is pending execution.

    • In Progress: The validation job or migration job is currently running.

    • Unknown: The status cannot be retrieved and Database Migration is waiting for recovery to continue. No action is required.

    • Terminated: Unfeasible to reach, similar to Canceled.

    • Failed: For a validation job, the precheck failed, no user action required. For a migration job, the job failed and it is waiting for user action (abort or resume the job).

    • Succeeded: The job has completed successfully.

    • Waiting: A migration job is paused and waiting for user input.

    • Canceling: A migration job is in the process of being stopped following an Abort action.

    • Canceled: A migration job has stopped following an Abort action. You can run a new job on a migration resource once a job reaches this state.

  • Type: Migration or Evaluation

  • Status Details: Displays a supporting message with additional details regarding the State.

    For example, if a validation job fails, with State=Failed, Status Details informs you that the job failed and Database Migration auto-terminated the job.

    If the Unknown state is displayed, a Status Details informs you that Database Migration is unable to retrieve the latest status of the job and is waiting for downtime recovery.

  • Created: Time stamp when the job was created

Select a job from the Jobs table to view its details.

On the Job Details page you can view the job information, including:

  • OCID: The resource's unique Oracle Cloud ID

  • Created: The date and time when the migration was created

Below the Job Information box, you can view information about resources associated with the job, such as Metrics (see Database Migration Metrics), Phases ( see Database Migration Job Phases), and Unsupported Objects.

Viewing parameter files for online Oracle migrations

When an online migration gets into Needs Attention state due to a failed migration job using the GoldenGate Service integration, then you may choose to view and edit the Extract and Replicat parameter files and then resume the online Oracle migration.

Note

This feature is applicable only when you use the inbuilt GoldenGate.

Job Details - Phases

You can view the GoldenGate process (Extract, Replicat) parameter files if they have been created to set up replication for your online migration. On a migration resource detail page, you can click Jobs, then the job name, then Phases, and see the phases of the job that have failed.

Click the View parameter files option to view the current replication (Extract, Replicat) parameter files.

Note

You may or may not be able to view both the Extract, Replicat parameter files depending on the current state of the replication setup for your online migration. You can view the parameter file during or after the Prepare phase is concluded. If the parameter files are not created, then you cannot view them. Similarly, you can view the Replicat parameter files during or after the Prepare replication target phase.
The Parameter files panel displays the parameter files currently in use.
  • Details such as Type and creation details.
  • Click View parameter file to view the Extract or Replicat files in read-only mode.
You can modify the relevant GoldenGate parameter file for the failed phase.
Note

This capability is applicable only for some phases wherein the file is displayed only if the GoldenGate Extract or Replicat is available.

After modifying the parameter files, resume the online migration in this failed state.

Editing parameter files for online Oracle migrations

When an online migration job gets into Needs Attention state due to a failed migration job, using the GoldenGate Service integration, then you may choose to view and edit the Extract and Replicat parameter files and then resume the online Oracle migration.

Note

You can only view the Extract/Replicat parameter files, if your replication process is Active. You can edit only if the respective process Extract/Replicat is not active at that time and is in the Needs Attention state.
The Oracle Cloud Infrastructure Database Migration service provides you a comprehensive feature to edit your replication parameter files whenever applicable during the migration process. It has the following features:
  • You can view and edit the current Extract or Replicat parameter file belonging to the replication setup for your online migration.
  • Any updates that you perform to the replication parameter files are versioned for your convenience.
  • Whenever you edit on the Extract or Replicat parameter files, the original factory default version is always retained for you to revert for your reference.
  • When you perform edits to either Extract or Replicat parameter files, after saving it, it is immediately applied to the replication setup.
  • You can resume the migration after saving the file, from the failed process.

Job Details - Phases

On a migration resource detail page, you can click Jobs, then the job name, then Phases, and see the phase of the job that has failed.

Click the Edit parameter file option to view the current GoldenGate Extract and Replicat parameter files.
Note

You can edit the parameter depending on the phase and the current state of the GoldenGate process (Extract or Replicat).

The Parameter files panel displays the parameter files currently in use.

  1. Details such as Type and creation details.
  2. Click Edit parameter file to edit the Extract or Replicat files.
  3. Edit the parameter file using a free-form editor.
  4. If you perform an invalid parameter file edit, then GoldenGate rejects the edit with the error displayed on the screen.
  5. Click Save as new and make current option to save this new version of the file and access it from the list available in the Show all files option. The new version is saved and applied to GoldenGate and marked as In use.
  6. Click Cancel if you do not want to save the edited file.
Click the Show all files option to view the details of the files such as Name, Type, and Created details. The file currently being used is shown as In use. The following types of files are available in this option:
  • You can switch between any of these two edited versions or the original (factory) parameter file.
  • The original (factory) parameter file is provided by Oracle.
  • From the action menu (three dots), select Edit and make current to switch between the files. You can view, edit, and save the file or you can view and save the file.
  • You can switch back to the factory (original) parameter file.
  • The original (factory) parameter file provided by Oracle is never deleted and you can use it when needed.
You can modify the relevant GoldenGate parameter file for the failed phase.
Note

This capability is applicable only for some phases such as Prepare, Prepare replication target, Monitor replication lag, and Switchover, wherein the file is displayed only if the GoldenGate Extract or Replicat is available.

After modifying the parameter files, resume the online migration in this failed state.

Monitoring Job Status

In Oracle Cloud Infrastructure Database Migration, there are several places in the Console from which you can monitor the status of a migration job to varying degrees.

Job Details page

On the Migration Details page, you can click Jobs, and see information about the jobs run with this resource.

You can click Download Log to view the log generated by Database Migration Service.

Below the job information details you can click the Metrics, Phases, and Unsupported Objects to get more information about the migration job.

Job Details - Phases

On a migration resource detail page, you can click Jobs, then the job name, then Phases, and see the phases of the job that have completed, are pending, and are currently running (labeled Started).

For any phase that has some error or warning text (or log) to display, the phase name is displayed as a clickable hyperlink, and the phase's action items menu includes View Details. Clicking on the phase name link or View details action opens a View phase details panel which displays the details of the error or warning

If there is a log available for download, an option appears in the action menu to allow download. You can also download logs using a button in the View phase details panel. The View phase details panel displays the following information:
  • Name: Name of the phase
  • Status: Status of the phase. A failed status informs you that the job failed.
  • Duration: Time elapsed from the beginning of the phase till the point where the error occurred.
  • Issue: The issue causing the job failure.
  • Action: The action you can perform to resolve the error.
  • Error messages: The validation or migration errors causing the job failure.

Download Log downloads the Data Pump log. Applies to jobs run in migration mode in the Export Initial Load and Import Initial Load phases.

The Validate pre-migration advisor phase is a special case, because this link opens the Validation pre-migration advisor detail page, from which you can download the Cloud Pre-migration Advisor Tool (CPAT) report, view the CPAT report statistics, and drill down in the Checks list.

For more information about the CPAT report and interactive details page, see Checking the Interactive Validation Premigration Advisor Report.

For details about the migration work flow phases, see Database Migration Job Phases.

For information about metrics, see Database Migration Metrics.

Preparing for Application Switchover

The following procedure ensures zero data loss during a read-write application switchover:

Both the source and target databases are opened read-write during the logical migration work flow. The following conditions apply:

  • For read-only applications, switchover can happen immediately after GoldenGate Replicat has applied all outstanding source transactions, allowing for zero application downtime for those services.

  • Read-write applications require assurance that all transactions have been applied on the target before switching the application over to ensure zero data loss.

If your application is read-write, you must do the following to ensure zero data loss:

  1. Pause the migration job after phase ODMS_MONITOR_REPLICATION_LAG.

    This phase monitors Oracle GoldenGate Extract and Replicat operations until Replicat has caught up on the target database; end-to-end (E2E) replication lag should be less than 30 seconds.

  2. After phase ODMS_MONITOR_REPLICATION_LAG completes and the migration job pauses, stop the workload on the source database (start of downtime).

  3. Resume the migration job, scheduling another pause after phase ODMS_SWITCHOVER.

    This phase does the following:

    1. Ensures replication E2E lag is still less than 30 seconds

    2. Ensures that Extract has captured outstanding transactions on the source database

    3. Stops Extract

    4. Ensures Replicat has applied all remaining trail file data

    5. Stops Replicat

  4. After phase ODMS_SWITCHOVER has completed, you can start the workload on the target database (end of downtime).

Terminating a Job

You can terminate a migration job while it is running or paused.

  1. In the list of jobs on the Migration Details page, select Abort from the Actions (three dots) menu of the job you want to delete.

    You can also click Abort on the Job Details page.

  2. In the Abort Job dialog, click Abort.

Deleting a Job

  1. In the list of Jobs on the Migration Details page, select Delete from the Actions (three dots) menu of the job you want to delete.
    You can also click Delete on the Job Details page.
  2. In the Delete dialog, click Delete.

Managing Tags for Jobs

Tags help you locate resources within your tenancy. In Oracle Cloud Infrastructure Database Migration, you can add and view a migration job's tags from the Migration Details page and from the Job Details page.

On the Migration Details page, select Jobs under Resources on the left side of the page.

In the Jobs table, from the job's Actions (three dots) menu, select Add Tags or View Tags.

On the Job Details page, you can select Add Tags above the Job Information box, or click the Tags tab to view and edit tags.

Learn more about tagging at Managing Tags and Tag Namespaces.

Using the Job API

You can use the following operations to manage migration jobs:

For information about using the API and signing requests, see REST APIs and Security Credentials. For more information about SDKs, see Software Development Kits and Command Line Interface.