Manage migration jobs using the API

Overview

In this page, you learn how to use the Database Migration Service API to manage migration jobs for a MySQL source database.

There are two ways that you can use the Database Migration Service API. You can make REST API calls or you can use the gcloud command-line interface (CLI).

To see high-level information about using gcloud to manage Database Migration Service migration jobs, click here.

Create a draft of a migration job

The following shows a request to create a migration job in draft mode. This way, you don't have to create the migration job all at once. You can create a portion of it, and then update it by using the PATCH operation.

For example, if you want to create a migration job, but you don't have the destination database or the network connectivity method, you can use the following code:

REST

Before using any of the request data, make the following replacements:

  • project-id: The project ID
  • region: The project region
  • migration-job-id: The migration job ID
  • migration-job-name: The migration job name
  • source-connection-profile-id: The source connection profile ID
  • destination-connection-profile-id: The destination connection profile ID
  • provider: The provider associated with the classification type of the source database.
    • For a standalone MySQL instance, use DATABASE_PROVIDER_UNSPECIFIED because this value is associated with an on-premises database.
    • For a Cloud SQL for MySQL instance, use CLOUDSQL.
    • For any managed database service, such as Amazon RDS for MySQL, use RDS.
  • cloud-storage-bucket (optional): The bucket in Cloud Storage where you store your dump file.
  • dump-file (optional): The dump file that you store in a bucket in Cloud Storage.

HTTP method and URL:

POST https://datamigration.googleapis.com/v1/projects/project-id/locations/region/migrationJobs?migrationJobId=migration-job-id

Request JSON body:


{
  "displayName": "migration-job-name",
  "state": "DRAFT",
  "type": "CONTINUOUS",
  "source": "projects/project-id/locations/region/connectionProfiles/source-connection-profile-id",
  //"destination":"projects/project-id/locations/region/connectionProfiles/destination-connection-profile-id",
  "sourceDatabase": {
    "engine": "MYSQL",
    "provider": "provider"
  },
  //"vpcPeeringConnectivity": {
  //"vpc": "default"
  //}
    "dump_path": "gs://cloud-storage-bucket/dump-file"
}


To send your request, expand one of these options:

You should receive a JSON response similar to the following:

{
  "name": "projects/project-id/locations/region/operations/operation-1591975557292-5a7e4b195623c-e350e3da-713dee7d",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.clouddms.v1.OperationMetadata",
    "createTime": "2020-06-12T15:25:57.430715421Z",
    "target": "projects/project-id/locations/region/migrationJobs/migration-job-id",
    "verb": "create",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

Create a continuous migration job with VPC peering connectivity

The following shows a request to create a continuous migration job for migrating a MySQL database (running on a Google Compute Engine VM) to Cloud SQL for MySQL, using VPC peering connectivity.

REST

Before using any of the request data, make the following replacements:

  • project-id: The project ID
  • region: The project region
  • migration-job-id: The migration job ID
  • migration-job-name: The migration job name
  • source-connection-profile-id: The source connection profile ID
  • destination-connection-profile-id: The destination connection profile ID
  • provider: The provider associated with the classification type of the source database.
    • For a standalone MySQL instance, use DATABASE_PROVIDER_UNSPECIFIED because this value is associated with an on-premises database.
    • For a Cloud SQL for MySQL instance, use CLOUDSQL.
    • For any managed database service, such as Amazon RDS for MySQL, use RDS.
  • cloud-storage-bucket (optional): The bucket in Cloud Storage where you store your dump file.
  • dump-file (optional): The dump file that you store in a bucket in Cloud Storage.

HTTP method and URL:

POST https://datamigration.googleapis.com/v1/projects/project-id/locations/region/migrationJobs?migrationJobId=migration-job-id

Request JSON body:


{
  "displayName": "migration-job-name",
  "state": "NOT_STARTED",
  "type": "CONTINUOUS",
  "source": "projects/project-id/locations/region/connectionProfiles/source-connection-profile-id",
  "destination":"projects/project-id/locations/region/connectionProfiles/destination-connection-profile-id",
  "sourceDatabase": {
    "engine": "MYSQL",
    "provider": "provider"
  },
  "vpcPeeringConnectivity": {
    "vpc": "default"
  }
    "dump_path": "gs://cloud-storage-bucket/dump-file"
}

To send your request, expand one of these options:

You should receive a JSON response similar to the following:

{
  "name": "projects/project-id/locations/region/operations/operation-1591975557292-5a7e4b195623c-e350e3da-713dee7d",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.clouddms.v1.OperationMetadata",
    "createTime": "2020-06-12T15:25:57.430715421Z",
    "target": "projects/project-id/locations/region/migrationJobs/migration-job-id",
    "verb": "create",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

gcloud

For more information on using gcloud to create Database Migration Service migration jobs, click here.

Create a continuous migration job with reverse SSH connectivity

The following shows a request to create a continuously running migration job for migrating an Amazon RDS MySQL database to Cloud SQL for MySQL, using reverse SSH connectivity.

REST

Before using any of the request data, make the following replacements:

  • project-id: The project ID
  • region: The project region
  • migration-job-id: The migration job ID
  • migration-job-name: The migration job name
  • source-connection-profile-id: The source connection profile ID
  • destination-connection-profile-id: The destination connection profile ID
  • vm-name: The name of the SSH VM. For example, dms-ssh-bastion.
  • vm-ip-address: The IP address of the SSH VM. For example, 11.22.33.44.
  • vm-port: The connection port of the SSH VM. For example, 3306.
  • vpc-name: The VPC network name. For example, projects/project-id/global/networks/test-network.
  • provider: The provider associated with the classification type of the source database.
    • For a standalone MySQL instance, use DATABASE_PROVIDER_UNSPECIFIED because this value is associated with an on-premises database.
    • For a Cloud SQL for MySQL instance, use CLOUDSQL.
    • For any managed database service, such as Amazon RDS for MySQL, use RDS.
  • cloud-storage-bucket (optional): The bucket in Cloud Storage where you store your dump file.
  • dump-file (optional): The dump file that you store in a bucket in Cloud Storage.

HTTP method and URL:

POST https://datamigration.googleapis.com/v1/projects/project-id/locations/region/migrationJobs?migrationJobId=migration-job-id

Request JSON body:


{
  "displayName": "migration-job-name",
  "state": "NOT_STARTED",
  "type": "CONTINUOUS",
  "source": "projects/project-id/locations/region/connectionProfiles/source-connection-profile-id",
  "destination":"projects/project-id/locations/region/connectionProfiles/destination-connection-profile-id",
  "sourceDatabase": {
    "engine": "MYSQL",
    "provider": "provider"
  },
  "reverseSshConnectivity": {
    "vm": "vm-name",
    "vm_ip": "vm-ip-address",
    "vm_port": vm-port,
    "vpc": "vpc-name"
  }
    "dump_path": "gs://cloud-storage-bucket/dump-file"
}

To send your request, expand one of these options:

You should receive a JSON response similar to the following:

{
  "name": "projects/project-id/locations/region/operations/operation-1591973161667-5a7e422cb0ba4-3004980d-2ae97165",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.clouddms.v1.OperationMetadata",
    "createTime": "2020-06-12T14:46:01.744267779Z",
    "target": "projects/project-id/locations/region/migrationJobs/migration-job-id",
    "verb": "create",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

gcloud

For more information on using gcloud to create Database Migration Service migration jobs, click here.

Create a migration job with IP allowlist connectivity

The following shows a request to create a migration job for migrating either a standalone MySQL instance or a managed database service to a Cloud SQL for MySQL database, using an IP allowlist.

REST

Before using any of the request data, make the following replacements:

  • project-id: The project ID
  • region: The project region
  • migration-job-id: The migration job ID
  • migration-job-name: The migration job name
  • source-connection-profile-id: The source connection profile ID
  • destination-connection-profile-id: The destination connection profile ID
  • provider: The provider associated with the classification type of the source database.
    • For a standalone MySQL instance, use DATABASE_PROVIDER_UNSPECIFIED because this value is associated with an on-premises database.
    • For a Cloud SQL for MySQL instance, use CLOUDSQL.
    • For any managed database service, such as Amazon RDS for MySQL, use RDS.
  • cloud-storage-bucket (optional): The bucket in Cloud Storage where you store your dump file.
  • dump-file (optional): The dump file that you store in a bucket in Cloud Storage.

HTTP method and URL:

POST https://datamigration.googleapis.com/v1/projects/project-id/locations/region/migrationJobs?migrationJobId=migration-job-id

Request JSON body:


{
  "displayName": "migration-job-name",
  "state": "NOT_STARTED",
  "type": "CONTINUOUS",
  "source": "projects/project-id/locations/region/connectionProfiles/source-connection-profile-id",
  "destination":"projects/project-id/locations/region/connectionProfiles/destination-connection-profile-id",
  "sourceDatabase": {
    "engine": "MYSQL",
    "provider": "provider"
  },
  "staticIpConnectivity": {}
    "dump_path": "gs://cloud-storage-bucket/dump-file"
}

To send your request, expand one of these options:

You should receive a JSON response similar to the following:

{
  "name": "projects/project-id/locations/region/operations/operation-1591973161667-5a7e422cb0ba4-3004980d-2ae97165",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.clouddms.v1.OperationMetadata",
    "createTime": "2020-06-12T14:46:01.744267779Z",
    "target": "projects/project-id/locations/region/migrationJobs/migration-job-id",
    "verb": "create",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

gcloud

For more information on using gcloud to create Database Migration Service migration jobs, click here.

Get information about a migration job

REST

Before using any of the request data, make the following replacements:

  • project-id: The project ID
  • region: The project region
  • migration-job-id: The migration job ID

HTTP method and URL:

GET https://datamigration.googleapis.com/v1/projects/project-id/locations/region/migrationJobs/migration-job-id

To send your request, expand one of these options:

You should receive a JSON response similar to the following:

{
  "name": "projects/project-id/locations/region/migrationJobs/one-time-vpc-job",
  "createTime": "2020-06-12T15:48:39.666093835Z",
  "updateTime": "2020-06-12T15:48:39.666093835Z",
  "displayName": "migration-job-display-name",
  "state": "CREATING",
  "type": "CONTINUOUS",
  "source": "projects/project-id/locations/region/connectionProfiles/connection-profile-id",
  "destination": "projects/project-id/locations/region/connectionProfiles/connection-profile-id",
  "sourceDatabase": {
    "engine": "MYSQL"
  },
  "destinationDatabase": {
    "provider": "CLOUDSQL"
  },
  "vpcPeeringConnectivity": {
    "vpc": "default"
  }
}

gcloud

For more information on using gcloud to retrieve information about your migration job, click here.

List migration jobs

REST

Before using any of the request data, make the following replacements:

  • project-id: The project ID
  • region: The project region
You can also filter the list of migration jobs that Database Migration Service retrieves, as follows:

  • orderBy: Use this filter to retrieve a listing of all migration jobs for a particular region in alphabetical order. For example, the orderBy=name filter returns all migration jobs, alphabetically, by name.
  • pageSize: Use this filter to specify the maximum number of migration jobs that Database Migration Service retrieves and displays on a page. For example, by setting pageSize=10, Database Migration Service will return up to 10 migration jobs for a page.

  • If there are more than 10 migration jobs, then they appear on other pages. At the end of each page, a nextPageToken parameter and a unique identifier appear (for example, oasndfoasdnoasun1241243ojsandf). Use the identifier to retrieve the listing of the migration jobs for the following page. On the final page, the nextPageToken parameter and unique identifier don't appear.

HTTP method and URL:

GET https://datamigration.googleapis.com/v1/projects/project-id/locations/region/migrationJobs

To send your request, expand one of these options:

You should receive a JSON response similar to the following:

{
  "migrationJobs": [
    {
      "name": "projects/project-id/locations/region/migrationJobs/name-of-first-migration-job",
      "createTime": "2020-06-12T15:48:39.666093835Z",
      "updateTime": "2020-06-12T15:48:39.666093835Z",
      "displayName": "display-name-of-first-migration-job",
      "state": "NOT_STARTED",
      "type": "CONTINUOUS",
      "source": "projects/project-id/locations/region/connectionProfiles/connection-profile-id",
      "destination": "projects/project-id/locations/region/connectionProfiles/connection-profile-id",
      "sourceDatabase": {
        "engine": "MYSQL"
      },
      "destinationDatabase": {
        "provider": "CLOUDSQL"
      },
      "vpcPeeringConnectivity": {
        "vpc": "default"
      }
    }
    {
      "name": "projects/project-id/locations/region/migrationJobs/name-of-second-migration-job",
      "createTime": "2021-02-13T11:59:39.104613835Z",
      "updateTime": "2021-02-13T12:01:38.666093835Z",
      "displayName": "display-name-of-second-migration-job",
      "state": "RUNNING",
      "type": "CONTINUOUS",
      "source": "projects/project-id/locations/region/connectionProfiles/connection-profile-id",
      "destination": "projects/project-id/locations/region/connectionProfiles/connection-profile-id",
      "sourceDatabase": {
        "engine": "MYSQL"
      },
      "destinationDatabase": {
        "provider": "CLOUDSQL"
      },
      "staticIpConnectivity": {}
        "vpc": "default"
    }
  ],
  "nextPageToken": "unique-identifier"
}

gcloud

For more information on using gcloud to retrieve information about all of your migration jobs, click here.

Generate an SSH tunnel configuration script for a migration job

REST

Before using any of the request data, make the following replacements:

  • project-id: The project ID
  • region: The project region
  • migration-job-id: The migration job ID

HTTP method and URL:

POST https://datamigration.googleapis.com/v1/projects/project-id/locations/region/migrationJobs/migration-job-id:generateSshScript

Request JSON body:

{
  "vm":"vm-name",
  "vmCreationConfig":{
    "vmMachineType":"machine-type",
    "subnet":"subnet-name"
	}
}

To send your request, expand one of these options:

You should receive a JSON response similar to the following:

{
  "name": "projects/project-id/locations/region/operations/operation-1591973161667-5a7e422cb0ba4-3004980d-2ae97165",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.clouddms.v1.OperationMetadata",
    "createTime": "2020-06-12T14:46:01.744267779Z",
    "target": "projects/project-id/locations/region/migrationJobs/migration-job-id",
    "verb": "generate",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

gcloud

For more information on using gcloud to generate an SSH script for your migration job, click here.

Verify a migration job

The following shows a request to verify a migration job. By verifying a migration job, you can ensure that the job will start and run successfully.

REST

Before using any of the request data, make the following replacements:

  • project-id: The project ID
  • region: The project region
  • migration-job-id: The migration job ID

HTTP method and URL:

POST https://datamigration.googleapis.com/v1/projects/project-id/locations/region/migrationJobs/migration-job-id:verify

To send your request, expand one of these options:

You should receive a JSON response similar to the following:

{
  "name": "projects/project-id/locations/region/operations/operation-1591973161667-5a7e422cb0ba4-3004980d-2ae97165",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.clouddms.v1.OperationMetadata",
    "createTime": "2020-06-12T14:46:01.744267779Z",
    "target": "projects/project-id/locations/region/migrationJobs/migration-job-id",
    "verb": "verify",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

gcloud

For more information on using gcloud to verify your migration job, click here.

Update a migration job

The following shows a request to update the display name of an existing migration job. By using the updateMask parameter in the request, only these fields need to be included in the request body.

REST

Before using any of the request data, make the following replacements:

  • project-id: The project ID
  • region: The project region
  • migration-job-id: The migration job ID

HTTP method and URL:

PATCH https://datamigration.googleapis.com/v1/projects/project-id/locations/region/connectionProfiles/connection-profile-id?updateMask=displayName

Request JSON body:

{
  "displayName": "updated-display-name",
}

To send your request, expand one of these options:

You should receive a JSON response similar to the following:

{
  "name": "projects/project-id/locations/region/operations/operation-1591973161667-5a7e422cb0ba4-3004980d-2ae97165",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.clouddms.v1.OperationMetadata",
    "createTime": "2020-06-12T14:46:01.744267779Z",
    "target": "projects/project-id/locations/region/migrationJobs/migration-job-id",
    "verb": "update",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

gcloud

For more information on using gcloud to update your migration job, click here.

Start a migration job

The following shows a request to start a migration job.

REST

Before using any of the request data, make the following replacements:

  • project-id: The project ID
  • region: The project region
  • migration-job-id: The migration job ID

HTTP method and URL:

POST https://datamigration.googleapis.com/v1/projects/project-id/locations/region/migrationJobs/migration-job-id:start

To send your request, expand one of these options:

You should receive a JSON response similar to the following:

{
  "name": "projects/project-id/locations/region/operations/operation-1591973161667-5a7e422cb0ba4-3004980d-2ae97165",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.clouddms.v1.OperationMetadata",
    "createTime": "2020-06-12T14:46:01.744267779Z",
    "target": "projects/project-id/locations/region/migrationJobs/migration-job-id",
    "verb": "start",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

gcloud

For more information on using gcloud to start your migration job, click here.

Restart a failed migration job

The following shows a request to restart a migration job. A migration job can be restarted from the beginning if the migration failed and is not recoverable, or was stopped during full dump.

REST

Before using any of the request data, make the following replacements:

  • project-id: The project ID
  • region: The project region
  • migration-job-id: The migration job ID

HTTP method and URL:

POST https://datamigration.googleapis.com/v1/projects/project-id/locations/region/migrationJobs/migration-job-id:restart

To send your request, expand one of these options:

You should receive a JSON response similar to the following:

{
  "name": "projects/project-id/locations/region/operations/operation-1591973161667-5a7e422cb0ba4-3004980d-2ae97165",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.clouddms.v1.OperationMetadata",
    "createTime": "2020-06-12T14:46:01.744267779Z",
    "target": "projects/project-id/locations/region/migrationJobs/migration-job-id",
    "verb": "restart",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

gcloud

For more information on using gcloud to restart your migration job, click here.

Stop a migration job

The following shows a request to stop a migration job.

REST

Before using any of the request data, make the following replacements:

  • project-id: The project ID
  • region: The project region
  • migration-job-id: The migration job ID

HTTP method and URL:

POST https://datamigration.googleapis.com/v1/projects/project-id/locations/region/migrationJobs/migration-job-id:stop

To send your request, expand one of these options:

You should receive a JSON response similar to the following:

{
  "name": "projects/project-id/locations/region/operations/operation-1591973161667-5a7e422cb0ba4-3004980d-2ae97165",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.clouddms.v1.OperationMetadata",
    "createTime": "2020-06-12T14:46:01.744267779Z",
    "target": "projects/project-id/locations/region/migrationJobs/migration-job-id",
    "verb": "stop",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

gcloud

For more information on using gcloud to stop your migration job, click here.

Resume a migration job

The following shows a request to resume a migration job.

REST

Before using any of the request data, make the following replacements:

  • project-id: The project ID
  • region: The project region
  • migration-job-id: The migration job ID

HTTP method and URL:

POST https://datamigration.googleapis.com/v1/projects/project-id/locations/region/migrationJobs/migration-job-id:resume

To send your request, expand one of these options:

You should receive a JSON response similar to the following:

{
  "name": "projects/project-id/locations/region/operations/operation-1591973161667-5a7e422cb0ba4-3004980d-2ae97165",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.clouddms.v1.OperationMetadata",
    "createTime": "2020-06-12T14:46:01.744267779Z",
    "target": "projects/project-id/locations/region/migrationJobs/migration-job-id",
    "verb": "resume",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

gcloud

For more information on using gcloud to resume your migration job, click here.

Promote a migration job

The following shows a request to promote a migration job.

REST

Before using any of the request data, make the following replacements:

  • project-id: The project ID
  • region: The project region
  • migration-job-id: The migration job ID

HTTP method and URL:

POST https://datamigration.googleapis.com/v1/projects/project-id/locations/region/migrationJobs/migration-job-id:promote

To send your request, expand one of these options:

You should receive a JSON response similar to the following:

{
  "name": "projects/project-id/locations/region/operations/operation-1591973161667-5a7e422cb0ba4-3004980d-2ae97165",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.clouddms.v1.OperationMetadata",
    "createTime": "2020-06-12T14:46:01.744267779Z",
    "target": "projects/project-id/locations/region/migrationJobs/migration-job-id",
    "verb": "promote",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

gcloud

For more information on using gcloud to promote your migration job, click here.

Delete a migration job

The following shows a request to delete a migration job.

REST

Before using any of the request data, make the following replacements:

  • project-id: The project ID
  • region: The project region
  • migration-job-id: The migration job ID

HTTP method and URL:

DELETE https://datamigration.googleapis.com/v1/projects/project-id/locations/region/migrationJobs/migration-job-id

To send your request, expand one of these options:

You should receive a JSON response similar to the following:

{
  "name": "projects/project-id/locations/region/operations/operation-1591973161667-5a7e422cb0ba4-3004980d-2ae97165",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.clouddms.v1.OperationMetadata",
    "createTime": "2020-06-12T14:46:01.744267779Z",
    "target": "projects/project-id/locations/region/migrationJobs/migration-job-id",
    "verb": "delete",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

gcloud

For more information on using gcloud to delete your migration job, click here.