Use quick-start migrations to migrate to AlloyDB for PostgreSQL


This page describes how to perform quick-start continuous migrations for homogeneous PostgreSQL migrations to AlloyDB for PostgreSQL.

Overview

Quick-start migrations are a lightweight continuous migration flow for homogeneous PostgreSQL scenarios. With quick-start migrations, Database Migration Service can automatically configure the core networking and migration resources you need: network attachments, subnets, private connectivity configurations with Private Service Connect interfaces, connection profiles, and continuous migration jobs.

With quick-start migrations, you can move your data to an existing AlloyDB for PostgreSQL cluster, or create a new one as you configure the migration. Quick-start migrations are best suited for:

  • Basic migrations where you don't need customized data dump parallelism settings.
  • Migrating your database from one Google Cloud project to another. When you configure a quick-start migration, you can create your destination cluster in a different project than your source and set Database Migration Service to create the network attachment and subnet in the Virtual Private Cloud (VPC) network of another project.

  • Migrating from sources that have a private IP address in your Google Cloud Virtual Private Cloud (VPC) network, such as self-managed databases on Compute Engine, or Cloud SQL for PostgreSQL instances enabled for private networking.

    Sources hosted outside Google Cloud might need additional network components (such as a Cloud VPN connection) so that they can be reached at a private IP address within your VPC network.

  • Quick-start migrations support public IP and Private Service Connect interfaces connectivity. Reverse SSH tunnels aren't supported for quick-start migrations.

To learn more about quick-start migrations, see Quick-start migrations overview in the main Database Migration Service documentation.

Before you begin

  1. Verify if quick-start migrations can fully support your scenario. See Quick-start migration limitations.
  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Enable the Database Migration Service, Compute Engine, Network Connectivity Center, and AlloyDB for PostgreSQL APIs.

    Enable the APIs

Required roles

To get the permissions that you need to run quick-start migrations to AlloyDB for PostgreSQL with Database Migration Service, ask your administrator to grant the required Identity and Access Management (IAM) roles for the accounts involved in the migration in the relevant projects. For more information about granting roles, see Manage access in the IAM documentation.

Roles and permissions in the source project

If you use private IP connectivity to connect to a source database in a Google Cloud project, grant the following roles to specific accounts on the project where your source database resides:

  • For the user account that performs the migration:
  • For the Database Migration Service service account of the destination project: Compute Network Viewer (roles/compute.networkViewer)

    The Database Migration Service service account is created when you enable the Database Migration Service API. The email address associated with this account is generated automatically and can't be changed. This email address uses the following format: 

    service-DESTINATION_PROJECT_NUMBER@gcp-sa-datamigration.

These predefined roles contain the permissions required to set up connectivity on your source database project as part of a quick-start migration with Database Migration Service. To see the exact permissions that are required, expand the Required permissions (source) section:

Required permissions (source)

The following permissions are required to perform homogeneous quick-start migrations with Database Migration Service:

For the user account that performs the migration:

  • compute.networks.get
  • compute.networks.list
  • compute.networks.updatePolicy
  • compute.subnetworks.get
  • compute.subnetworks.list
  • compute.subnetworks.create
  • compute.subnetworks.use
  • compute.networkAttachments.create
  • compute.networkAttachments.get
  • compute.networkAttachments.list
  • compute.networkAttachments.update
  • compute.networkAttachments.use
  • compute.regionOperations.get
  • networkconnectivity.internalRanges.create
  • networkconnectivity.internalRanges.get
  • networkconnectivity.operations.get
  • resourcemanager.projects.getIamPolicy

For the Database Migration Service service account of the destination project:

  • compute.networkAttachments.get

Roles and permissions in the destination project

Grant the following roles to the user account that performs the migration on the Google Cloud project where your destination database resides:

In addition, the Database Migration Service service account of the destination project (service-DESTINATION_PROJECT_NUMBER@gcp-sa-datamigration.) requires the Database Migration Service Agent (roles/datamigration.serviceAgent) role on the destination project. Google Cloud grants this role automatically when you enable the Database Migration Service API.

These predefined roles contain the permissions required to set up the required migration components on your destination database project as part of a quick-start migration with Database Migration Service. To see the exact permissions that are required, expand the Required permissions (destination) section:

Required permissions (destination)

The following permissions are required to perform homogeneous quick-start migrations with Database Migration Service:

For the user account that performs the migration:

  • datamigration.privateconnections.get
  • datamigration.privateconnections.list
  • datamigration.privateconnections.create
  • datamigration.migrationjobs.create
  • datamigration.migrationjobs.update
  • datamigration.migrationjobs.verify
  • datamigration.migrationjobs.start
  • datamigration.migrationjobs.get
  • datamigration.migrationjobs.fetchSourceObjects
  • datamigration.operations.get
  • datamigration.connectionprofiles.create
  • datamigration.connectionprofiles.get
  • datamigration.connectionprofiles.update
  • datamigration.locations.list
  • datamigration.locations.fetchStaticIps
  • alloydb.clusters.create
  • alloydb.clusters.get
  • alloydb.clusters.list
  • alloydb.clusters.update
  • alloydb.clusters.delete
  • alloydb.instances.create
  • alloydb.instances.get
  • alloydb.instances.list
  • alloydb.instances.update
  • alloydb.instances.delete
  • alloydb.operations.get
  • alloydb.users.list
  • alloydb.users.get
  • alloydb.users.create
  • alloydb.users.update
  • alloydb.users.delete
  • resourcemanager.projects.getIamPolicy

For the Database Migration Service service account of the destination project:

  • alloydb.clusters.import
  • alloydb.instances.connect
  • alloydb.instances.executeSql

Configure your source database

To configure your source PostgreSQL database, do the following:

  1. Create a dedicated migration user account in your instance.
    • For Cloud SQL for PostgreSQL sources, see Create a user in the Cloud SQL documentation.
    • For other sources, see your database provider documentation or create and manage users in the PostgreSQL documentation.
  2. Assign the necessary privileges to the dedicated migration user account. Run the following commands for each database you want to migrate: 
    -- Grant the REPLICATION attribute
ALTER ROLE MIGRATION_USER REPLICATION;

-- Grant database-level permissions.
-- Repeat for each database you want to migrate.
GRANT CONNECT, CREATE ON DATABASE DATABASE_NAME TO MIGRATION_USER;

-- Grant schema-level usage.
-- Repeat for each schema in each database you want to migrate.
GRANT USAGE ON SCHEMA SCHEMA_NAME TO MIGRATION_USER;

    Replace the following:

    • MIGRATION_USER with the name of the migration user account.
    • DATABASE_NAME with the name of the database you want to migrate.
    • SCHEMA_NAME with the name of the schema in the database you want to migrate.
  3. The migration user account needs to have ownership access to the tables you migrate. To grant this level of access, do one of the following:
    • For sources other than Cloud SQL for PostgreSQL only: Assign the SUPERUSER PostgreSQL role to the migration account.
    • For all sources: Add the migration user account to the user group that owns the tables. Run the following command: 
      -- Grant table ownership.
GRANT TABLE_OWNER_GROUP_NAME TO MIGRATION_USER;

      Replace the following:

      • TABLE_OWNER_GROUP_NAME with the name of the user group that owns each table that you want to migrate.
      • MIGRATION_USER with the name of the migration user account.
  4. For tables that don't have primary keys: Database Migration Service doesn't replicate UPDATE or DELETE operations for tables without primary keys during the Change Data Capture (CDC) phase. If you want to include such operations in your replication, modify tables without primary keys with REPLICA IDENTITY: 
    ALTER TABLE TABLE_NAME REPLICA IDENTITY FULL;
ALTER TABLE TABLE_NAME REPLICA IDENTITY USING INDEX INDEX_NAME;

    Replace the following:

    • TABLE_NAME is the name of the table that doesn't have primary keys.
    • INDEX_NAME is the unique index that can track rows from tables without primary keys.
  5. Configure the replication settings using database flags.

    Self-managed sources

    Saving changes to database flags requires a full database restart. The following examples use SQL queries for changing flag values. If you can't run SQL queries directly, refer to your provider documentation for steps about changing these flags.

    1. Set the wal_level parameter to logical. Run the following command: 
      ALTER SYSTEM SET wal_level = 'logical';
    2. Set the wal_sender_timeout parameter to 0. This value disables the timeout mechanism that's used to terminate inactive replication connections. Run the following command: 
      ALTER SYSTEM SET wal_sender_timeout = 0;
    3. Configure the maximum number of replication slots with the max_replication_slots parameter. This parameter must be set to at least the number of databases you're migrating per migration job, plus some reserves for table synchronization.

      For example, if you're migrating 5 databases and there are 2 migration jobs created for the source instance, then the number of replication slots must be at least 5 * 2 = 10, plus the number of replication slots already used by you.

      To set this parameter, run the following command:

      ALTER SYSTEM SET max_replication_slots = NUMBER_OF_SLOTS;
       Where NUMBER_OF_SLOTS represents the maximum number of replication slots.
    4. Configure the max_wal_senders parameter to at least the same value as max_replication_slots, plus the number of senders already used on your instance.

      For example, if the max_replication_slots parameter is set to 10, and you're already using 2 senders, then the number of WAL sender processes running at the same time would be 10 + 2 = 12.

      To set this parameter, run the following command:

      ALTER SYSTEM SET max_wal_senders = NUMBER_OF_SENDERS;
       Where NUMBER_OF_SENDERS represents the number of WAL sender processes running simultaneously.
    5. Set the max_worker_processes to at least the number of databases that you want to migrate, plus the number of max_worker_processes already used on your instance. To set this parameter, run the following command: 
      ALTER SYSTEM SET max_worker_processes = NUMBER_OF_PROCESSES;
       Where NUMBER_OF_PROCESSES represents the number of databases that will be migrated.

    Cloud SQL for PostgreSQL sources

    For Cloud SQL sources, you configure database flags in the Google Cloud console. You have to restart your instance after modifying database flags for the setting to take effect. For more information on setting database flags in Cloud SQL, see Configure database flags in the Cloud SQL documentation.

    1. Set the cloudsql.logical_decoding flag to on. Enabling this flag requires an instance restart for the setting to take effect.
    2. Set the wal_sender_timeout parameter to 0. This value disables the timeout mechanism that's used to terminate inactive replication connections.
    3. Configure the maximum number of replication slots with the max_replication_slots parameter. This parameter must be set to at least the number of databases you're migrating per migration job, plus some reserves for table synchronization.

      For example, if you're migrating 5 databases and there are 2 migration jobs created for the source instance, then the number of replication slots must be at least 5 * 2 = 10, plus the number of replication slots already used by you.

    4. Configure the max_wal_senders parameter to at least the same value as max_replication_slots, plus the number of senders already used on your instance.

      For example, if the max_replication_slots parameter is set to 10, and you're already using 2 senders, then the number of WAL sender processes running at the same time would be 10 + 2 = 12.

    5. Set the max_worker_processes parameter to at least the number of databases that you want to migrate, plus the number of max_worker_processes already used on your instance.

Create and run a quick-start migration

To create and run a quick-start migration, you can use the Google Cloud console or the gcloud CLI.

Console

  1. In the Google Cloud console, go to the Get started page.

    Go to Get started

  2. In the Source engine menu, select PostgreSQL.
  3. In the Destination engine menu, select AlloyDB for PostgreSQL.

    The Introducing quick-start PostgreSQL migration section appears.

  4. In the Introducing quick-start PostgreSQL migration section, click Start migration.

    The Migrate to AlloyDB for PostgreSQL page opens.

  5. In the Configure migration section, do the following:
    1. From the Destination region menu, select the region of your destination AlloyDB for PostgreSQL cluster.
    2. In the Migration prefix box, enter a human-friendly string that will be added to the names of all migration entities created for the quick-start migration: connection profiles, private connectivity configuration, network attachment and its subnet, and migration job.
    3. From the Connectivity type menu, select how Database Migration Service connects to your source database:
      • Private IP: Connect over a private network using Private Service Connect interfaces. From the Configuration type menu, select one of the following:
        • Existing connectivity configuration: Select this option if you already have a network attachment and a private connectivity configuration that uses the Private Service Connect interfaces method. This option is best used if you previously used quick-start migrations and want to re-use the same networking resources.
        • New connectivity configuration: Select this option to create a new network attachment and the network attachment subnet in the source database VPC network. The private connectivity configuration will be created in the same project as your destination cluster.
      • Public IP: Connect over the public internet using a dedicated outgoing static public IP address. If a public IP connectivity configuration already exists in your destination project and region, Database Migration Service reuses it. Otherwise, Database Migration Service creates a new public IP connectivity configuration and generates an outgoing IP address when you continue.
    4. Click Continue. If prompted to confirm the creation of networking resources, click Configure & continue.
  6. In the Connect source section, do the following:
    1. If you selected Public IP in the previous step, copy the outgoing IP address displayed in the Google Cloud console and add it as an inbound firewall rule or IP allowlist entry on your source network (such as pg_hba.conf or cloud provider security groups) to allow Database Migration Service to connect.
    2. Enter a Hostname or the IP address of your source database. If you selected Private IP, enter the private IP address reachable from your source VPC network. If you selected Public IP, enter the public IP address of your source database.
    3. Enter the Port that's used to access the host. The default PostgreSQL port is 5432.
    4. Enter the username and password for the dedicated migration account in your source database.
    5. From the Encryption type menu, select one of the following:
      • None: If your source database doesn't require SSL/TLS-encrypted connections.
      • Required: If your source database requires SSL/TLS-encrypted connections. This option doesn't require any certificate verification.
    6. In the Databases to migrate menu, click Customize. Use the side panel with embedded database discovery to select only the databases you want to migrate to AlloyDB for PostgreSQL.
    7. Click Continue.
  7. In the Configure destination section, you can create a new destination cluster, or select an existing one:

    New clusters

    If you want to create a new destination cluster, do the following:

    1. From the Destination instance type menu, select New cluster.

      Database Migration Service uses the default AlloyDB for PostgreSQL configuration for a new cluster. Click Customize to adjust cluster features, such as the machine type, zonal availability, or data protection settings. For more information on cluster configuration, see Create a cluster and its primary instance in the AlloyDB for PostgreSQL documentation.

    2. In the Password field, enter a password for the default postgres admin user. Database Migration Service connects as this user to migrate your data.

    Existing clusters

    You can migrate databases to a cluster that already exists. Make sure the destination cluster is enabled for Private Service Connect, is in the RUNNABLE state, and doesn't enforce mTLS with AlloyDB connectors. Do the following:

    1. From the Destination instance type menu, select Existing cluster.
    2. From the Existing cluster ID menu, select the cluster identifier.
  8. Click Start migration.

    Database Migration Service creates the continuous migration job and begins replicating data. You can monitor the migration progress and your destination cluster health in AlloyDB for PostgreSQL. For more information, see View cluster and instance details in the AlloyDB for PostgreSQL documentation.

gcloud

To create and run a quick-start migration using the gcloud CLI, do the following:

  1. Configure connectivity to your source database.
    Select the tab based on whether your source database uses Private IP (Private Service Connect) or Public IP:

    Private IP (Private Service Connect)

    To connect using Private Service Connect, configure your network attachment and private connection:

    1. Configure the network attachment: Decide if you want to create a new network attachment or re-use an existing one. You need to have a network attachment in the network where your source database private IP can be reached.

      • If you want to create a new network attachment, run the following command (click to expand full details).

        gcloud compute network-attachments create

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

        • NETWORK_ATTACHMENT with the name of the network attachment to create.
        • REGION with the region for the network attachment.
        • DEST_PROJECT_ID with the project ID of your destination project.
        • SOURCE_PROJECT_ID with the project ID where the source network resides.

        Execute the following command:

        Linux, macOS, or Cloud Shell

        gcloud compute network-attachments create NETWORK_ATTACHMENT \
  --region=REGION \
  --connection-preference=ACCEPT_MANUAL \
  --producer-accept-list=DEST_PROJECT_ID \
  --subnets=default \
  --project=SOURCE_PROJECT_ID

        Windows (PowerShell)

        gcloud compute network-attachments create NETWORK_ATTACHMENT `
  --region=REGION `
  --connection-preference=ACCEPT_MANUAL `
  --producer-accept-list=DEST_PROJECT_ID `
  --subnets=default `
  --project=SOURCE_PROJECT_ID

        Windows (cmd.exe)

        gcloud compute network-attachments create NETWORK_ATTACHMENT ^
  --region=REGION ^
  --connection-preference=ACCEPT_MANUAL ^
  --producer-accept-list=DEST_PROJECT_ID ^
  --subnets=default ^
  --project=SOURCE_PROJECT_ID
      • If you want to re-use an existing network attachment, proceed to the next step.

    2. Allow the Database Migration Service tenant project to access your network attachment: Your network attachment must allow connections from the Database Migration Service tenant project. Perform the following steps:

      1. Retrieve the Database Migration Service tenant project ID by performing a dry-run private connection creation (click to expand):

        gcloud database-migration private-connections create --validate-only

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

        • PRIVATE_CONN with the name of the private connection resource.
        • REGION with the region for the private connection.
        • NETWORK_ATTACHMENT_URI with the URI of the network attachment.

        Execute the following command:

        Linux, macOS, or Cloud Shell

        gcloud database-migration private-connections create PRIVATE_CONN \
  --region=REGION \
  --network-attachment=NETWORK_ATTACHMENT_URI \
  --display-name=PRIVATE_CONN \
  --format="value(metadata.metadata.tenant_project_id)" \
  --validate-only

        Windows (PowerShell)

        gcloud database-migration private-connections create PRIVATE_CONN `
  --region=REGION `
  --network-attachment=NETWORK_ATTACHMENT_URI `
  --display-name=PRIVATE_CONN `
  --format="value(metadata.metadata.tenant_project_id)" `
  --validate-only

        Windows (cmd.exe)

        gcloud database-migration private-connections create PRIVATE_CONN ^
  --region=REGION ^
  --network-attachment=NETWORK_ATTACHMENT_URI ^
  --display-name=PRIVATE_CONN ^
  --format="value(metadata.metadata.tenant_project_id)" ^
  --validate-only

        Save the returned tenant project ID to use with next commands.

      2. Allow the Database Migration Service tenant project and the destination project to connect to the network attachment (click to expand):

        gcloud compute network-attachments update

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

        • NETWORK_ATTACHMENT with the name of the network attachment.
        • REGION with the region.
        • DEST_PROJECT_ID with the project ID of your destination project.
        • DMS_TENANT_ID with the retrieved Database Migration Service tenant project ID.
        • SOURCE_PROJECT_ID with the project ID where the source network resides.

        Execute the following command:

        Linux, macOS, or Cloud Shell

        gcloud compute network-attachments update NETWORK_ATTACHMENT \
  --region=REGION \
  --producer-accept-list=DEST_PROJECT_ID,DMS_TENANT_ID \
  --project=SOURCE_PROJECT_ID

        Windows (PowerShell)

        gcloud compute network-attachments update NETWORK_ATTACHMENT `
  --region=REGION `
  --producer-accept-list=DEST_PROJECT_ID,DMS_TENANT_ID `
  --project=SOURCE_PROJECT_ID

        Windows (cmd.exe)

        gcloud compute network-attachments update NETWORK_ATTACHMENT ^
  --region=REGION ^
  --producer-accept-list=DEST_PROJECT_ID,DMS_TENANT_ID ^
  --project=SOURCE_PROJECT_ID

    3. Create the Database Migration Service private connectivity resource: Run the following command (click to expand):

      gcloud database-migration private-connections create

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

      • PRIVATE_CONN with the name of the private connection resource.
      • REGION with the region for the private connection.
      • NETWORK_ATTACHMENT_URI with the URI of the network attachment.

      Execute the following command:

      Linux, macOS, or Cloud Shell

      gcloud database-migration private-connections create PRIVATE_CONN \
  --region=REGION \
  --network-attachment=NETWORK_ATTACHMENT_URI \
  --display-name=PRIVATE_CONN

      Windows (PowerShell)

      gcloud database-migration private-connections create PRIVATE_CONN `
  --region=REGION `
  --network-attachment=NETWORK_ATTACHMENT_URI `
  --display-name=PRIVATE_CONN

      Windows (cmd.exe)

      gcloud database-migration private-connections create PRIVATE_CONN ^
  --region=REGION ^
  --network-attachment=NETWORK_ATTACHMENT_URI ^
  --display-name=PRIVATE_CONN

    Public IP

    To connect to a source database with a public IP address, perform the following steps:

    1. Create a private connection with reserved public IP.
      Run the following command (click to expand):

      gcloud database-migration private-connections create

      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:

      • CONNECTION_ID with the identifier for the private connection.
      • REGION with the Google Cloud region where you want to create the private connection.
      • DISPLAY with a friendly display name for the private connection.
      • Optional: You can replace the --reserved-public-ip flag with --reserved-public-ip-nat-ips-count to reserve multiple dedicated public IP addresses that Database Migration Service uses for connection. You can reserve up to 10 IP addresses.

      Execute the following command:

      Linux, macOS, or Cloud Shell

      gcloud database-migration private-connections create \
  CONNECTION_ID \
  --region=REGION \
  --display-name="DISPLAY" \
  --reserved-public-ip \
  --no-async

      Windows (PowerShell)

      gcloud database-migration private-connections create `
  CONNECTION_ID `
  --region=REGION `
  --display-name="DISPLAY" `
  --reserved-public-ip `
  --no-async

      Windows (cmd.exe)

      gcloud database-migration private-connections create ^
  CONNECTION_ID ^
  --region=REGION ^
  --display-name="DISPLAY" ^
  --reserved-public-ip ^
  --no-async

    2. Retrieve the reserved public IP address(es).
      Run the following command (click to expand):

      gcloud database-migration connection-profiles fetch-static-ips

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

      • REGION with the Google Cloud region of the private connection.

      Execute the following command:

      Linux, macOS, or Cloud Shell

      gcloud database-migration connection-profiles fetch-static-ips \
  REGION \
  --fetch-reserved-public-ips

      Windows (PowerShell)

      gcloud database-migration connection-profiles fetch-static-ips `
  REGION `
  --fetch-reserved-public-ips

      Windows (cmd.exe)

      gcloud database-migration connection-profiles fetch-static-ips ^
  REGION ^
  --fetch-reserved-public-ips

    3. Allowlist the reserved IP address(es) on the source database.
      Add the IP address(es) retrieved in the previous step to the incoming allowlist for your source database (for example, in your pg_hba.conf configuration, cloud provider security groups, or network firewall rules) so that Database Migration Service can establish a connection.

  2. Create a source connection profile.
    Run the following command (click to expand):

    gcloud database-migration connection-profiles create postgresql

    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:

    • SOURCE_CONN_ID with your source connection profile identifier.
    • REGION with the region where you want to save the connection profile.
    • SOURCE_PRIVATE_IP with the private IP address of your source database.
    • SOURCE_PORT with the port of your source database (default is 5432).
    • SOURCE_USER with the username of the migration user on your source database.
    • SOURCE_PASSWORD with the password of the migration user on your source database.
    • PRIVATE_CONN with the name of the private connection resource.

    Execute the following command:

    Linux, macOS, or Cloud Shell

    gcloud database-migration connection-profiles create postgresql \
  SOURCE_CONN_ID \
  --region=REGION \
  --role=SOURCE \
  --host=SOURCE_PRIVATE_IP \
  --port=SOURCE_PORT \
  --username=SOURCE_USER \
  --password=SOURCE_PASSWORD \
  --private-connection=PRIVATE_CONN \
  --no-async

    Windows (PowerShell)

    gcloud database-migration connection-profiles create postgresql `
  SOURCE_CONN_ID `
  --region=REGION `
  --role=SOURCE `
  --host=SOURCE_PRIVATE_IP `
  --port=SOURCE_PORT `
  --username=SOURCE_USER `
  --password=SOURCE_PASSWORD `
  --private-connection=PRIVATE_CONN `
  --no-async

    Windows (cmd.exe)

    gcloud database-migration connection-profiles create postgresql ^
  SOURCE_CONN_ID ^
  --region=REGION ^
  --role=SOURCE ^
  --host=SOURCE_PRIVATE_IP ^
  --port=SOURCE_PORT ^
  --username=SOURCE_USER ^
  --password=SOURCE_PASSWORD ^
  --private-connection=PRIVATE_CONN ^
  --no-async

  3. Create the destination connection profile.
    Select the tab based on whether you want to migrate to a new or an existing AlloyDB for PostgreSQL cluster:

    New clusters

    To use a new destination cluster for the quick-start migration, first create the cluster and its primary instance with AlloyDB for PostgreSQL Google Cloud CLI, and then create the destination connection profile. Follow these steps:

    1. Create a cluster and its primary instance with AlloyDB for PostgreSQL Google Cloud CLI. Make sure you use the --enable-private-service-connect flag to enable your destination cluster for Private Service Connect. Quick-start migrations support only Private Service Connect-enabled destinations.
    2. Create the destination connection profile for your new cluster. Expand the following section for full command details.

      gcloud database-migration connection-profiles create postgresql

      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:

      • DEST_CONN_ID with the destination connection profile identifier.
      • REGION with the region where you want to save the connection profile. This region should be the same as your destination cluster region.
      • DEST_CLUSTER with the ID or full resource path of your destination AlloyDB for PostgreSQL cluster.
      • DEST_USER with the username of the migration user on your destination database.
      • DEST_PASSWORD with the password for the migration user in the destination database.

      Execute the following command:

      Linux, macOS, or Cloud Shell

      gcloud database-migration connection-profiles create postgresql DEST_CONN_ID \
  --region=REGION \
  --alloydb-cluster=DEST_CLUSTER \
  --username=DEST_USER \
  --password=DEST_PASSWORD \
  --role=DESTINATION \
  --no-async

      Windows (PowerShell)

      gcloud database-migration connection-profiles create postgresql DEST_CONN_ID `
  --region=REGION `
  --alloydb-cluster=DEST_CLUSTER `
  --username=DEST_USER `
  --password=DEST_PASSWORD `
  --role=DESTINATION `
  --no-async

      Windows (cmd.exe)

      gcloud database-migration connection-profiles create postgresql DEST_CONN_ID ^
  --region=REGION ^
  --alloydb-cluster=DEST_CLUSTER ^
  --username=DEST_USER ^
  --password=DEST_PASSWORD ^
  --role=DESTINATION ^
  --no-async

      You should receive a response similar to the following:

      Waiting for connection profile [CONNECTION_PROFILE_ID]
to be created with [OPERATION_ID]

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

Created connection profile CONNECTION_PROFILE_ID [OPERATION_ID]

    Existing clusters

    To migrate to an existing destination cluster, create the connection profile pointing to the pre-created cluster. Run the following command (click to expand):

    gcloud database-migration connection-profiles create postgresql

    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:

    • DEST_CONN_ID with the destination connection profile identifier.
    • REGION with the region where you want to save the connection profile. This region should be the same as your destination cluster region.
    • DEST_CLUSTER with the ID or full resource path of your destination AlloyDB for PostgreSQL cluster.
    • DEST_USER with the username of the migration user on your destination database.
    • DEST_PASSWORD with the password for the migration user in the destination database.

    Execute the following command:

    Linux, macOS, or Cloud Shell

    gcloud database-migration connection-profiles create postgresql DEST_CONN_ID \
  --region=REGION \
  --alloydb-cluster=DEST_CLUSTER \
  --username=DEST_USER \
  --password=DEST_PASSWORD \
  --role=DESTINATION \
  --no-async

    Windows (PowerShell)

    gcloud database-migration connection-profiles create postgresql DEST_CONN_ID `
  --region=REGION `
  --alloydb-cluster=DEST_CLUSTER `
  --username=DEST_USER `
  --password=DEST_PASSWORD `
  --role=DESTINATION `
  --no-async

    Windows (cmd.exe)

    gcloud database-migration connection-profiles create postgresql DEST_CONN_ID ^
  --region=REGION ^
  --alloydb-cluster=DEST_CLUSTER ^
  --username=DEST_USER ^
  --password=DEST_PASSWORD ^
  --role=DESTINATION ^
  --no-async

    You should receive a response similar to the following:

    Waiting for connection profile [CONNECTION_PROFILE_ID]
to be created with [OPERATION_ID]

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

Created connection profile CONNECTION_PROFILE_ID [OPERATION_ID]

  4. Create a continuous migration job.
    Run the following command to create a continuous migration job (click to expand):

    gcloud database-migration migration-jobs create

    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.
    • REGION with the region where you want to save the migration job.
    • SOURCE_CONN_ID with the source connection profile identifier.
    • DEST_CONN_ID with the destination connection profile identifier.
    • DATABASES_LIST with a comma-separated list of databases you want to migrate.

    Execute the following command:

    Linux, macOS, or Cloud Shell

    gcloud database-migration migration-jobs create \
  MIGRATION_JOB_ID \
  --region=REGION \
  --type=CONTINUOUS \
  --source=SOURCE_CONN_ID \
  --destination=DEST_CONN_ID \
  --use-postgres-native \
  --postgres-max-additional-subscriptions=10 \
  --databases-filter=DATABASES_LIST \
  --no-async

    Windows (PowerShell)

    gcloud database-migration migration-jobs create `
  MIGRATION_JOB_ID `
  --region=REGION `
  --type=CONTINUOUS `
  --source=SOURCE_CONN_ID `
  --destination=DEST_CONN_ID `
  --use-postgres-native `
  --postgres-max-additional-subscriptions=10 `
  --databases-filter=DATABASES_LIST `
  --no-async

    Windows (cmd.exe)

    gcloud database-migration migration-jobs create ^
  MIGRATION_JOB_ID ^
  --region=REGION ^
  --type=CONTINUOUS ^
  --source=SOURCE_CONN_ID ^
  --destination=DEST_CONN_ID ^
  --use-postgres-native ^
  --postgres-max-additional-subscriptions=10 ^
  --databases-filter=DATABASES_LIST ^
  --no-async

    You should receive a response similar to the following:

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

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

Created migration job MIGRATION_JOB_ID [OPERATION_ID]

  5. Start the migration job.
    To start the continuous migration job, run the following command (click to expand):

    gcloud database-migration migration-jobs start

    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

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

    Windows (PowerShell)

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

    Windows (cmd.exe)

    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:

Finalize the migration

When you decide to switch your application traffic to the new AlloyDB for PostgreSQL cluster, finalize the migration by following these steps:

  1. Stop all write operations on your source database. You can switch the source database to read-only mode to retain operational query functionality during cutover.
  2. Promote the migration job. For quick-start migrations, your destination cluster remains writable during the migration process. Promoting the migration job only ends the replication and doesn't have any impact on your destination cluster.
  3. Optional: Verify migration data for completeness and consistency.

What's next