Migrate to a new destination cluster

This page describes how to migrate your databases to a new AlloyDB for PostgreSQL cluster that Database Migration Service creates on your behalf when you configure the migration job. If your migration has different requirements, consider following a different migration flow. For more information, see Guide: Migrate to an existing AlloyDB for PostgreSQL cluster.

At a high level, the continuous migration follows these steps:

1. Configure the source database to allow Database Migration Service to replicate your data to the new databases.
2. Create the source connection profile.
3. Create the continuous migration job and configure the new destination AlloyDB for PostgreSQL cluster.
4. Start and monitor the continuous migration job.
5. Promote the migration job, audit permissions, and redirect your application traffic to the new cluster.

Costs

In this document, you use the following billable components of Google Cloud:

• AlloyDB for PostgreSQL (See AlloyDB for PostgreSQL pricing.)
• If used for storing Customer-managed Encryption Keys (CMEK): Cloud Storage (See Cloud Storage pricing.)

To generate a cost estimate based on your projected usage, use the pricing calculator.

Before you begin

1. Verify if this migration path can fully support your scenario. See the following pages:
   • Supported sources and destinations on the Scenario overview page lists all supported source and destination versions.
   • Known limitations describes supported data types, database sizes, and other operational boundaries. Note that Database Migration Service for AlloyDB for PostgreSQL supports continuous migrations.

   • Different network connectivity methods are available for different source databases. Plan your network connectivity before you begin migration procedures. For more information, see Networking overview.

     Migrating to a new destination cluster doesn't support Private Service Connect interfaces connectivity. If you want to use Private Service Connect interfaces connectivity, consider pre-creating your destination cluster directly in AlloyDB for PostgreSQL (see Guide: Migrate to an existing AlloyDB for PostgreSQL cluster).

2. Consider in which region you want to create the destination database. Database Migration Service is a fully regional product, meaning all entities related to your migration (source connection profiles, migration jobs, and destination clusters) must reside in a single Google Cloud region.
3. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Go to project selector

4. Enable the Database Migration Service, AlloyDB for PostgreSQL, and Compute Engine APIs.

   Enable the APIs

Required roles

To get the permissions that you need to perform homogeneous PostgreSQL migrations to AlloyDB for PostgreSQL with Database Migration Service, ask your administrator to grant you the required IAM roles on your project:

• Database Migration Admin (roles/datamigration.admin)
• AlloyDB Admin (roles/alloydb.admin)

For more information about granting roles, see Manage access in the Identity and Access Management documentation.

These predefined roles contain the permissions required to perform homogeneous PostgreSQL migrations to AlloyDB for PostgreSQL with Database Migration Service. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to perform homogeneous PostgreSQL migrations to AlloyDB for PostgreSQL with Database Migration Service:

• datamigration.*
• 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

You might also be able to get these permissions with custom roles or other predefined roles.

Prepare your source database

To prepare your source database for migration, follow these steps:

1. Choose and configure your source network connectivity method.

   For public IP allowlist connectivity: At a later point, after Database Migration Service creates the destination cluster, you might need to add the AlloyDB for PostgreSQL outgoing IP address to your firewall allowlist. Consult your network administrator on how to best schedule such configuration changes.

2. Configure your source database instance. At a high level, this includes the following steps:
   1. Install the pglogical PostgreSQL extension (version 2.2.1 or later) on the source database and on all databases to be migrated.
   2. Configure PostgreSQL parameters: set wal_level = logical, and ensure adequate values for max_replication_slots, max_wal_senders, and max_worker_processes.
   3. Grant replication privileges to your migration user, and configure pg_hba.conf to permit incoming connections.

   For detailed instructions, see Configure your source database.

3. Create the source connection profile.

Create and run the migration job

Note: When Database Migration Service creates your destination AlloyDB for PostgreSQL cluster, it provisions the cluster alongside its primary read/write instance. The primary instance isn't demoted into read-only mode during migration, but you must avoid performing write operations on tables or databases included in the migration to prevent replication conflicts. For more information, see Known limitations.

To configure and run your migration, perform the following steps:

1. Optional: If you want to manage your own encryption keys for the destination cluster, prepare Customer-Managed Encryption Keys (CMEK).
2. Create and run the migration job.

   You can monitor the migration progress and destination cluster health with Database Migration Service observability features. See Migration job metrics.

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 set the source database to read-only mode to retain query functionality during the cutover window.
2. Promote the migration job. Promoting the migration job completes replication of any remaining CDC events, severs the replication stream, and establishes the destination AlloyDB for PostgreSQL cluster as an independent, fully operational primary cluster.
3. Optional: Verify migration data for completeness and consistency.

What's next

Learn more about AlloyDB for PostgreSQL architecture, features, and management. See AlloyDB for PostgreSQL overview.