Manage migration jobs

Preview — Database Migration Service for homogeneous SQL Server migrations

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

In the Google Cloud console, you can perform actions in bulk for migration jobs that have the same status. You can perform actions on a single migration job both in the Google Cloud console and by using Google Cloud CLI.

You can perform any of the following actions on your migration job:

Action	Description
Start	Start migration jobs is that aren't in the Running or Starting state. See Migration job statuses.
Stop	Stop a running migration job. The data movement is paused. The migration job status first changes to Stopping and then to Stopped. You can resume, delete, or promote a stopped migration job.
Resume	If you stop a migration job during the incremental load, you can resume it later. When you resume a migration job, Database Migration Service picks up all transaction log files that accumulate when the migration job is stopped.
Restart	You can restart a migration job that encountered an error and can't proceed with data replication. The result of restarting a migration job depends on why it failed: Failed migration jobs that can't recover from the error re-try the whole migration process, including the initial load of the full backup file. If the replication has failed because of an error on one or more source or destination databases, then restarting the migration wipes all data from the destination databases. If you create a new folder for another database after starting the migration and add it to databases selected for migration, then restarting the migration also replicates the new databases into the destination instance.
Delete	A migration job can be deleted. The outcome depends on the status of the job: If the migration job is in the Completed status, then the record is deleted from the migration job list. If the migration job is in any other status, then there's an option to choose to delete the destination Cloud SQL instance/primary pair.
Promote	During the migration process, your destination database is put into a read-only state where it is fully managed by Database Migration Service. When you want to switch your application to the migrated destination database, promoting the migration job updates the destination database into a standalone replica. See Promote a migration.

Start a migration job

When your migration job is fully created (that is, it isn't saved in a draft state), you can start it at any time to begin migrating data.

To start a migration job, perform the following steps:

Console

1. In the Google Cloud console, go to the Migration jobs page.

   Go to Migration jobs

2. In the Jobs tab, click the display name of the migration job that you want to start.

   The migration job details page opens.

3. Click Start.
4. In the dialog, click Start.

gcloud

Before using any of the command data below, make the following replacements:

• MIGRATION_JOB_ID with your migration job identifier.

  If you don't know the identifier, you can use the gcloud database-migration migration-jobs list command to list all migration jobs in a given region and view their identifiers.

• REGION with the identifier of the region where your connection profile is saved.

Execute the following command:

Linux, macOS, or Cloud Shell

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud database-migration migration-jobs \
start MIGRATION_JOB_ID \
  --region=REGION

Windows (PowerShell)

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud database-migration migration-jobs `
start MIGRATION_JOB_ID `
  --region=REGION

Windows (cmd.exe)

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud database-migration migration-jobs ^
start MIGRATION_JOB_ID ^
  --region=REGION

Result

The action is performed in an asynchronous manner. As such, this command returns an Operation entity that represents a long-running operation:

done: false
metadata:
  '@type': type.googleapis.com/google.cloud.clouddms.v1.OperationMetadata
  apiVersion: v1
  createTime: '2024-02-20T12:20:24.493106418Z'
  requestedCancellation: false
  target: MIGRATION_JOB_ID
  verb: start
name: OPERATION_ID

To see if your operation is successful, you can query the returned operation object, or check the status of the migration job:

• Use the gcloud database-migration migration-jobs describe command to view the status of the migration job.
• Use the gcloud database-migration operations describe with the OPERATION_ID to see the status of the operation itself.

Stop a migration job

You can stop a running migration job at any time by performing the following steps:

Console

1. In the Google Cloud console, go to the Migration jobs page.

   Go to Migration jobs

2. In the Jobs tab, click the display name of the migration job that you want to start.

   The migration job details page opens.

3. Click Stop.
4. In the dialog, click Stop.

gcloud

Before using any of the command data below, make the following replacements:

• MIGRATION_JOB_ID with your migration job identifier.

  If you don't know the identifier, you can use the gcloud database-migration migration-jobs list command to list all migration jobs in a given region and view their identifiers.

• REGION with the identifier of the region where your connection profile is saved.

Execute the following command:

Linux, macOS, or Cloud Shell

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud database-migration migration-jobs \
stop MIGRATION_JOB_ID \
  --region=REGION

Windows (PowerShell)

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud database-migration migration-jobs `
stop MIGRATION_JOB_ID `
  --region=REGION

Windows (cmd.exe)

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud database-migration migration-jobs ^
stop MIGRATION_JOB_ID ^
  --region=REGION

Result

The action is performed in an asynchronous manner. As such, this command returns an Operation entity that represents a long-running operation:

done: false
metadata:
  '@type': type.googleapis.com/google.cloud.clouddms.v1.OperationMetadata
  apiVersion: v1
  createTime: '2024-02-20T12:20:24.493106418Z'
  requestedCancellation: false
  target: MIGRATION_JOB_ID
  verb: stop
name: OPERATION_ID

To see if your operation is successful, you can query the returned operation object, or check the status of the migration job:

• Use the gcloud database-migration migration-jobs describe command to view the status of the migration job.
• Use the gcloud database-migration operations describe with the OPERATION_ID to see the status of the operation itself.

Resume a migration job

You can resume a stopped migration job by performing the following steps:

Console

1. In the Google Cloud console, go to the Migration jobs page.

   Go to Migration jobs

2. In the Jobs tab, click the display name of the migration job that you want to start.

   The migration job details page opens.

3. Click Resume.
4. In the dialog, click Resume.

gcloud

Before using any of the command data below, make the following replacements:

• MIGRATION_JOB_ID with your migration job identifier.

  If you don't know the identifier, you can use the gcloud database-migration migration-jobs list command to list all migration jobs in a given region and view their identifiers.

• REGION with the identifier of the region where your connection profile is saved.

Execute the following command:

Linux, macOS, or Cloud Shell

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud database-migration migration-jobs \
resume MIGRATION_JOB_ID \
  --region=REGION

Windows (PowerShell)

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud database-migration migration-jobs `
resume MIGRATION_JOB_ID `
  --region=REGION

Windows (cmd.exe)

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud database-migration migration-jobs ^
resume MIGRATION_JOB_ID ^
  --region=REGION

Result

The action is performed in an asynchronous manner. As such, this command returns an Operation entity that represents a long-running operation:

done: false
metadata:
  '@type': type.googleapis.com/google.cloud.clouddms.v1.OperationMetadata
  apiVersion: v1
  createTime: '2024-02-20T12:20:24.493106418Z'
  requestedCancellation: false
  target: MIGRATION_JOB_ID
  verb: resume
name: OPERATION_ID

To see if your operation is successful, you can query the returned operation object, or check the status of the migration job:

• Use the gcloud database-migration migration-jobs describe command to view the status of the migration job.
• Use the gcloud database-migration operations describe with the OPERATION_ID to see the status of the operation itself.

Restart a migration job

To start a migration job, perform the following steps:

Console

1. In the Google Cloud console, go to the Migration jobs page.

   Go to Migration jobs

2. In the Jobs tab, click the display name of the migration job that you want to restart.

   The migration job details page opens.

3. Click Restart.
4. In the dialog, click Restart.

gcloud

Before using any of the command data below, make the following replacements:

• MIGRATION_JOB_ID with your migration job identifier.

  If you don't know the identifier, you can use the gcloud database-migration migration-jobs list command to list all migration jobs in a given region and view their identifiers.

• REGION with the identifier of the region where your connection profile is saved.

Execute the following command:

Linux, macOS, or Cloud Shell

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud database-migration migration-jobs \
restart MIGRATION_JOB_ID \
  --region=REGION

Windows (PowerShell)

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud database-migration migration-jobs `
restart MIGRATION_JOB_ID `
  --region=REGION

Windows (cmd.exe)

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud database-migration migration-jobs ^
restart MIGRATION_JOB_ID ^
  --region=REGION

Result

The action is performed in an asynchronous manner. As such, this command returns an Operation entity that represents a long-running operation:

done: false
metadata:
  '@type': type.googleapis.com/google.cloud.clouddms.v1.OperationMetadata
  apiVersion: v1
  createTime: '2024-02-20T12:20:24.493106418Z'
  requestedCancellation: false
  target: MIGRATION_JOB_ID
  verb: restart
name: OPERATION_ID

To see if your operation is successful, you can query the returned operation object, or check the status of the migration job:

• Use the gcloud database-migration migration-jobs describe command to view the status of the migration job.
• Use the gcloud database-migration operations describe with the OPERATION_ID to see the status of the operation itself.

Update a draft migration job

To finish creating a migration job, perform the following steps:

Console

1. In the Google Cloud console, go to the Migration jobs page.

   Go to Migration jobs

2. In the Drafts tab, click the display name of the migration job that you want to finish creating.

   The migration job creation wizard opens.

3. Finish creating the migration job. See Create a migration job.

gcloud

This sample uses the optional --no-async flag so that all operations are performed synchronously. This means that some commands might take a while to complete. You can skip the --no-async flag to run commands asynchronously. If you do, you need to use the gcloud database-migration operations describe command to verify if your operation is successful.

Before using any of the command data below, make the following replacements:

• MIGRATION_JOB_ID with a machine-readable identifier for your migration job.
• REGION with the region identifier where you want to save the connection profile.
• MIGRATION_JOB_NAME with a human-readable name for your migration job. This value is displayed in Database Migration Service in the Google Cloud console.
• SOURCE_CONNECTION_PROFILE_ID with a machine-readable identifier of the source connection profile.
• DESTINATION_CONNECTION_PROFILE_ID with a machine-readable identifier of the destination connection profile.
• PATTERN with the regular expression that you want Database Migration Service to use to identify the backup files in the Cloud Storage bucket.
• COMMA_SEPARATED_DATABASE_ID_LIST with a comma-separated list of database identifiers of the SQL Server you want to migrate from your backup files.

Execute the following command:

Linux, macOS, or Cloud Shell

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud database-migration migration-jobs \
create MIGRATION_JOB_ID \
  --no-async \
  --region=REGION \
  --display-name=MIGRATION_JOB_NAME \
  --source=SOURCE_CONNECTION_PROFILE_ID \
  --destination=DESTINATION_CONNECTION_PROFILE_ID \
  --sql-server-default-backup-name-pattern=PATTERN \
  --sqlserver-databases=COMMA_SEPARATED_DATABASE_ID_LIST \
  --type=CONTINUOUS]

Windows (PowerShell)

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud database-migration migration-jobs `
create MIGRATION_JOB_ID `
  --no-async `
  --region=REGION `
  --display-name=MIGRATION_JOB_NAME `
  --source=SOURCE_CONNECTION_PROFILE_ID `
  --destination=DESTINATION_CONNECTION_PROFILE_ID `
  --sql-server-default-backup-name-pattern=PATTERN `
  --sqlserver-databases=COMMA_SEPARATED_DATABASE_ID_LIST `
  --type=CONTINUOUS]

Windows (cmd.exe)

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud database-migration migration-jobs ^
create MIGRATION_JOB_ID ^
  --no-async ^
  --region=REGION ^
  --display-name=MIGRATION_JOB_NAME ^
  --source=SOURCE_CONNECTION_PROFILE_ID ^
  --destination=DESTINATION_CONNECTION_PROFILE_ID ^
  --sql-server-default-backup-name-pattern=PATTERN ^
  --sqlserver-databases=COMMA_SEPARATED_DATABASE_ID_LIST ^
  --type=CONTINUOUS]

You should receive a response similar to the following:

Waiting for migration job [MIGRATION_JOB_ID]
to be updated with [OPERATION_ID]

Waiting for operation [OPERATION_ID] to complete...done.

Updated migration job MIGRATION_JOB_ID [OPERATION_ID]

Add databases to the migration job

To add a new database to the migration job, you first need to create a new dedicated folder in your Cloud Storage bucket and upload the backup files there. See Configure Cloud Storage buckets.

When you have the necessary backup files in the Cloud Storage bucket, perform the following steps:

Console

1. In the Google Cloud console, go to the Migration jobs page.

   Go to Migration jobs

2. In the Jobs tab, click the display name of your migration job.

   The migration job details page opens.

3. Click Edit.
4. In the Select databases to migrate section, use the checkboxes to select the new database you want to add to the migration job.
5. (Optional) If you use encrypted backups, provide the encryption keys for your backups. For more details on using encrypted backups, see Use encrypted backups.

   Perform the following actions:

   • Click Edit details next to the database you selected for migration.

     The Encryption side panel opens.

   • Use the Encryption key drop-down menus to select your keys.
   • In the Password field, enter the encryption key password.
   • Click Save and exit.

gcloud

This sample uses the optional --no-async flag so that all operations are performed synchronously. This means that some commands might take a while to complete. You can skip the --no-async flag to run commands asynchronously. If you do, you need to use the gcloud database-migration operations describe command to verify if your operation is successful.

Before using any of the command data below, make the following replacements:

• MIGRATION_JOB_ID with your migration job identifier.

  If you don't know the identifier, you can use the gcloud database-migration migration-jobs list command to list all migration jobs in a given region and view their identifiers.

• REGION with the identifier of the region where your connection profile is saved.
• COMMA_SEPARATED_DATABASE_ID_LIST with a comma-separated list of database identifiers of the SQL Server you want to migrate from your backup files. These identifiers need to be the same as the database folder names in your Cloud Storage.

  For example: --sqlserver-databases=my-business-database,my-other-database

Execute the following command:

Linux, macOS, or Cloud Shell

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud database-migration migration-jobs \
update MIGRATION_JOB_ID \
  --region=REGION \
  --sqlserver-databases=COMMA_SEPARATED_DATABASE_ID_LIST

Windows (PowerShell)

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud database-migration migration-jobs `
update MIGRATION_JOB_ID `
  --region=REGION `
  --sqlserver-databases=COMMA_SEPARATED_DATABASE_ID_LIST

Windows (cmd.exe)

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud database-migration migration-jobs ^
update MIGRATION_JOB_ID ^
  --region=REGION ^
  --sqlserver-databases=COMMA_SEPARATED_DATABASE_ID_LIST

You should receive a response similar to the following:

Waiting for migration job [MIGRATION_JOB_ID]
to be updated with [OPERATION_ID]

Waiting for operation [OPERATION_ID] to complete...done.

Updated migration job MIGRATION_JOB_ID [OPERATION_ID]

Edit a migration job

For non-draft migration jobs, you can use Google Cloud CLI to change their display name.

This sample uses the optional --no-async flag so that all operations are performed synchronously. This means that some commands might take a while to complete. You can skip the --no-async flag to run commands asynchronously. If you do, you need to use the gcloud database-migration operations describe command to verify if your operation is successful.

Before using any of the command data below, make the following replacements:

• MIGRATION_JOB_ID with your migration job identifier.

  If you don't know the identifier, you can use the gcloud database-migration migration-jobs list command to list all migration jobs in a given region and view their identifiers.

• REGION with the identifier of the region where your connection profile is saved.
• MIGRATION_JOB_NAME with a human-readable name for your migration job. This value is displayed in Database Migration Service in the Google Cloud console.

Execute the following command:

Linux, macOS, or Cloud Shell

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud database-migration migration-jobs \
update MIGRATION_JOB_ID \
  --region=REGION \
  --display-name=MIGRATION_JOB_NAME 

Windows (PowerShell)

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud database-migration migration-jobs `
update MIGRATION_JOB_ID `
  --region=REGION `
  --display-name=MIGRATION_JOB_NAME 

Windows (cmd.exe)

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud database-migration migration-jobs ^
update MIGRATION_JOB_ID ^
  --region=REGION ^
  --display-name=MIGRATION_JOB_NAME 

You should receive a response similar to the following:

Waiting for migration job [MIGRATION_JOB_ID]
to be updated with [OPERATION_ID]

Waiting for operation [OPERATION_ID] to complete...done.

Updated migration job MIGRATION_JOB_ID [OPERATION_ID]

Test a migration job

Before you run the migration job, you can perform a test operation to check if Database Migration Service can reach all the necessary source and destination entities. In the Google Cloud console, you can only test draft migration jobs that you create in the migration job creation wizard. See Create a migration job. With gcloud CLI, you can test migration jobs that are created, but not yet started.

Before using any of the command data below, make the following replacements:

• MIGRATION_JOB_ID with your migration job identifier.

  If you don't know the identifier, you can use the gcloud database-migration migration-jobs list command to list all migration jobs in a given region and view their identifiers.

• REGION with the identifier of the region where your connection profile is saved.

Execute the following command:

Linux, macOS, or Cloud Shell

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud database-migration migration-jobs \
verify MIGRATION_JOB_ID \
  --region=REGION

Windows (PowerShell)

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud database-migration migration-jobs `
verify MIGRATION_JOB_ID `
  --region=REGION

Windows (cmd.exe)

Note: Ensure you have initialized the Google Cloud CLI with authentication and a project by running either gcloud init; or gcloud auth login and gcloud config set project.

gcloud database-migration migration-jobs ^
verify MIGRATION_JOB_ID ^
  --region=REGION

Result

The action is performed in an asynchronous manner. As such, this command returns an Operation entity that represents a long-running operation:

done: false
metadata:
  '@type': type.googleapis.com/google.cloud.clouddms.v1.OperationMetadata
  apiVersion: v1
  createTime: '2024-02-20T12:20:24.493106418Z'
  requestedCancellation: false
  target: MIGRATION_JOB_ID
  verb: verify
name: OPERATION_ID

To see if your operation is successful, you can query the returned operation object, or check the status of the migration job:

• Use the gcloud database-migration migration-jobs describe command to view the status of the migration job.
• Use the gcloud database-migration operations describe with the OPERATION_ID to see the status of the operation itself.