Manage migration jobs

You can perform actions from the migration jobs list, from the single migration job details page, or directly from the destination cluster page in AlloyDB for PostgreSQL. In the Google Cloud console, you can perform actions on multiple jobs simultaneously if they all 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 some actions on migration jobs as a whole, while other actions (such as restarting failed databases or viewing details) can also be performed on individual databases within a migration job.

You can perform the following actions on migration jobs:

Action	Description
Edit	To make the following changes, edit the migration job: Change between migrating all databases and specific databases. Add or remove databases in any migration state or phase, as many times as you need. When you remove a database, Database Migration Service stops the replication process on that database, but doesn't remove it from the destination cluster. For more information, see Add or remove databases. Edit the data dump parallelism level of a running migration job. You must save and restart the job after you make the changes. Update the migration job display name with gcloud CLI. For more information, see Edit a non-draft migration job.
Start	Start migration jobs that were created without being started. You can start jobs that aren't in the Running or Starting state. See Migration job statuses.
Stop	Stop a running migration job at any time. The data migration is halted, and the migration job status changes to Stopping and subsequently to Stopped. If the migration job is stopped during the initial full dump phase, you can delete or restart the job. However, WAL logs will continue to accumulate in replication slots on the source database, which can eventually lead to the source database running out of disk space. In addition, Database Migration Service continues to poll for replication delay metrics, continuing to consume network traffic. If the migration job is stopped during the change data capture (CDC) phase, you can resume, promote, or delete the job. Monitor the replication slots and disk space of your source database server. Deleting the migration job cleans all replication slots on the source and stops network traffic.
Resume	If a continuous migration job was stopped during the CDC phase, then it can be resumed. Resuming the migration job restarts replication of events and data changes that accumulated during the stopped time.
Restart	If a migration job failed and isn't recoverable, or was stopped during the initial full dump phase, you can restart it from the beginning. You can either restart all databases in the migration job or restart only the databases that failed: Restarting the entire migration job wipes all data from all migrating databases in the destination cluster and starts a new full dump for them. If the migration job is configured to migrate all databases and new databases were created on the source PostgreSQL server since the migration started, restarting the migration job also replicates those new databases into the destination cluster. Restarting failed databases wipes all data only from the destination databases that encountered errors and starts a new full dump for them, without affecting other databases in the destination cluster.
Delete	Delete a migration job. You can delete migration jobs in any state. However, you can delete a running migration job only in the Google Cloud console. The outcome depends on the status of the job: If the migration job status is Completed, then the record is deleted from the migration job list. If the migration job is in any other status, there's an option in the Google Cloud console to choose whether to delete the destination AlloyDB for PostgreSQL cluster. Deleting a migration job removes allocated replication slots on the source database and stops network traffic. Deleting a migration job doesn't delete the source databases.
Promote	Promote the destination AlloyDB for PostgreSQL cluster from replicating to an independent standalone primary database cluster, and disconnect the destination cluster from the source. For more information, see Promote a migration.
View specific database	View migration details for a specific database configured for migration.
View all databases	View migration details for all databases configured for 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 migration job 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 with the MIGRATION_JOB_ID to view the status of the migration job.
• Use the gcloud database-migration operations describe command 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. When you stop a migration job, data migration is halted, and the migration job status changes to Stopping and subsequently to Stopped.

Caution: When a migration job is stopped, WAL logs continue to accumulate in replication slots on the source database server. This can eventually lead to your source database running out of disk space. In addition, Database Migration Service continues to poll for replication delay metrics, continuing to consume network traffic. Monitor your source database server's replication slots and disk space. If you don't plan to resume the migration, delete the migration job to clean up the replication slots and stop network traffic.

To stop 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 stop.

   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 migration job 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

If a continuous migration job was stopped during the change data capture (CDC) phase, you can resume it. Resuming the migration job restarts replication of events and data changes that accumulated on the source database while the job was stopped.

To resume a stopped 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 resume.

   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 migration job 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

If a migration job failed and isn't recoverable, or was stopped during the initial full dump phase, you can restart it from the beginning.

You can either restart all databases in the migration job, or restart only the databases that failed:

• Restart all databases: Wipes all data from all migrating databases in the destination cluster and initiates a new full dump for them. If the migration job is configured to migrate all databases and new databases were created on the source PostgreSQL server since the migration started, restarting the migration job also replicates those new databases into the destination cluster.
• Restart failed databases: Wipes all data only from the destination databases that encountered errors and initiates a new full dump for them. Other databases in the destination cluster aren't affected.

To restart 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. On the Jobs tab, click the display name of the migration job that you want to restart.

   The migration job details page opens.

3. Perform one of the following restart actions:

   • If you want to restart all databases included in the migration, on the migration job's toolbar, click Restart.

     The restart migration job dialog appears.

   • If you want to restart only failed databases, on the Databases tab, click Restart failed databases.

     The dialog with the number of failed databases to restart appears.

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 migration job is saved.

• Optional: By default, restarting a migration job restarts all databases included in the migration job. If you want to restart only the databases that failed without affecting other migrating databases, add the --restart-failed-objects flag.

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 migration job.
• 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.
• COMMA_SEPARATED_DATABASE_ID_LIST with a comma-separated list of database identifiers of the PostgreSQL you want to migrate.

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 \
  --no-async \
  --region=REGION \
  --display-name=MIGRATION_JOB_NAME \
  --source=SOURCE_CONNECTION_PROFILE_ID \
  --destination=DESTINATION_CONNECTION_PROFILE_ID \
  --databases-filter=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 `
update MIGRATION_JOB_ID `
  --no-async `
  --region=REGION `
  --display-name=MIGRATION_JOB_NAME `
  --source=SOURCE_CONNECTION_PROFILE_ID `
  --destination=DESTINATION_CONNECTION_PROFILE_ID `
  --databases-filter=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 ^
update MIGRATION_JOB_ID ^
  --no-async ^
  --region=REGION ^
  --display-name=MIGRATION_JOB_NAME ^
  --source=SOURCE_CONNECTION_PROFILE_ID ^
  --destination=DESTINATION_CONNECTION_PROFILE_ID ^
  --databases-filter=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 or remove databases from the migration job

You can add or remove databases in any migration state or phase, as many times as you need. When you remove a database, Database Migration Service stops the replication process on that database, but doesn't remove it from the destination AlloyDB for PostgreSQL cluster.

Note: You must save the migration job after each change.

To add or remove databases from your migration job, perform the following steps:

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 or clear the ones that you want to remove.
5. Click Save.

Edit a non-draft migration job

To edit the data dump parallelism level of a running migration job, see Known limitations. You must save and restart the migration job after changing the parallelism settings.

For non-draft migration jobs, you can use Google Cloud CLI to change the display name of the migration job:

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 migration job 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 \
  --no-async \
  --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 `
  --no-async `
  --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 ^
  --no-async ^
  --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 migration job 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 with the MIGRATION_JOB_ID to view the status of the migration job.
• Use the gcloud database-migration operations describe command with the OPERATION_ID to see the status of the operation itself.

View migration details for a specific database

When your migration job is fully created (that is, it isn't saved in a draft state), you can use Google Cloud CLI to view details about a specific database in that migration job:

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 migration job is saved.
• DATABASE_NAME with the name of the 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 objects lookup --migration-job=MIGRATION_JOB_ID \
  --region=REGION --database=DATABASE_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 objects lookup --migration-job=MIGRATION_JOB_ID `
  --region=REGION --database=DATABASE_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 objects lookup --migration-job=MIGRATION_JOB_ID ^
  --region=REGION --database=DATABASE_NAME

Result

The output is similar to the following:

createTime: '2025-03-21T17:05:19.211441641Z'
name: projects/PROJECT_ID/locations/REGION/migrationJobs/MIGRATION_JOB_ID/objects/OBJECT_ID
phase: FULL_DUMP
sourceObject:
  database: DATABASE_NAME
  type: DATABASE
state: RUNNING

View migration details for specific databases

When your migration job is fully created (that is, it isn't saved in a draft state), you can use Google Cloud CLI to list all databases that you selected for that migration job and view details about them:

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 migration job 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 objects list --migration-job=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 objects list --migration-job=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 objects list --migration-job=MIGRATION_JOB_ID ^
  --region=REGION

Result

The output is similar to the following:

SOURCE_OBJECT                            STATE    PHASE      ERROR
{'database': 'db1', 'type': 'DATABASE'}  RUNNING  FULL_DUMP
{'database': 'db2', 'type': 'DATABASE'}  STOPPED  CDC        {'code': 1, 'message': 'Internal error'}