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.
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
-
On a migration resource detail page, click Jobs, then the job name, then Phases.
-
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.
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.
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 Oracle migration 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.
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.
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.
- Details such as Type and creation details.
- Click View parameter file to view the Extract or Replicat files in read-only mode.
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 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.
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 the migration is in the Needs Attention state.
- 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.
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.
- Details such as Type and creation details.
- Click Edit parameter file to edit the Extract or Replicat files.
- Edit the parameter file using a free-form editor.
- If you perform an invalid parameter file edit, then GoldenGate rejects the edit with the error displayed on the screen.
- 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.
- Click Cancel if you do not want to save the edited file.
- 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.
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
- 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 Oracle migration phases.
For information about metrics, see Database Migration Metrics.
Preparing for application switchover
This process is currently applicable for Oracle to Oracle online migrations.
When both the source and target databases are open in a read-write mode 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 minimum data loss.
If you have an active source database with a lot of active transactions and if your application is read-write, then you must do the following to ensure minimum data loss:
- If your source database is occupied with the application usage, incoming transactions, you can decide when to do the application switchover. OCI Database Migration Service ensures that the data is replicated from where you resume the migration.
Pause the migration job after the Monitor replication lag phase.
This phase monitors Oracle GoldenGate Extract and Replicat operations until Replicat has caught up on the target database.
-
After the Monitor replication lag phase completes and the migration job pauses, stop the workload on the source database (start of downtime).
-
You can initiate a switchover by resuming a migration which is at a Waiting state after the monitor replication phase.Note
OCI Database Migration Service pauses a migration after the monitor replication phase. This gives you an option to resume the migration. However, if you do not pause the migration, OCI Database Migration Service automatically performs the switchover. When you resume the migration after the Monitor replication lag phase, the Switchover phase will be initiated.Note
For production loads, Oracle recommends you to pause the migration after the Monitor replication lag phase.When you Resume the migration, OCI Database Migration Service performs the following tasks:- Inserts a barrier transaction in the source database.
- Actively monitors the Extract and Replicat processes.
- Shuts off the Extract & Replicat processes.
- Checks if the barrier transaction was replicated to the Target database. This will also trigger the object types such as reload sequences, audit trails, materialized views, unsupported objects by Oracle GoldenGate, and the tables that you want to deliberately exclude from replication will be reloaded.
-
After phase 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.
-
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.
-
In the Abort Job dialog, click Abort.
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:
- EvaluateMigration
- StartMigration
- GetJob
- UpdateJob
- DeleteJob
- ResumeJob
- AbortJob
- GetJobOutputConten
- ListJobs
- ListJobOutputs
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.