Legacy Cloud SQL migration (deprecated) ¶

The CLI saves migration configuration in the cluster and launches Naisjobs running cloudsql-migrator . Each phase runs as a separate job. The migrator uses Google Database Migration Service to replicate data and handles the Nais resources and application switch.

The workflow has three phases:

Set up the new SQLInstance and replication.
Promote the new SQLInstance and switch the application.
Finalize by deleting the old SQLInstance and cleaning up migration resources.

Rollback is available before finalization, but does not copy data written to the destination back to the source.

Preparations ¶

Use a Nais CLI version that includes the migration commands. Check with nais cloudsql migrate --help.
Choose a new SQLInstance name, different from the current instance name.
Connect naisdevice.
Ensure you have access to the cluster where the application runs.
Check which database connection environment variables your application reads. Without envVarPrefix, the variable names include the instance name and change at promotion. Prepare your application for the new names before starting. If you choose to set envVarPrefix, follow the linked reference's credential-reset requirements first.

Setting up the migration ¶

Run the setup command and follow the prompts:

shell

nais cloudsql migrate setup --team <team> --environment <environment> <appname> <new-sql-instance-name>

Use the URL returned by the command to check replication progress. Wait until replication is up to date before promoting. The initial data transfer can take time.

Setup takes a backup of the source and creates a temporary Application to provision the destination instance. It configures the source for logical replication, including database flags and the pglogical extension, then creates and starts the Google migration job.

Promoting the new SQLInstance ¶

Run the promotion command and follow the instructions:

shell

nais cloudsql migrate promote --team <team> --environment <environment> <appname> <new-sql-instance-name>

Check that the application runs as expected and that all data is available in the destination.
Update spec.gcp.sqlInstances in your Application manifest to match the live Application before your next deployment, preserving the other instance settings. Promotion changes the live Application, not the manifest in your repository. The migrator also sets cascadingDelete: false; decide deliberately whether to retain that protection.
Verify database object ownership and application-user permissions before finalizing.

Promotion scales the application to zero replicas and waits for replication lag to reach zero. It promotes the destination, adjusts database ownership, switches the live Application to the new instance and scales it back up. It also takes a backup of the destination.

Object ownership

Check for application objects still owned by cloudsqlsuperuser. Users with that role can access those objects. If ownership needs correcting, run the following in the application database with sufficient privileges, replacing the role name with the intended application user:

sql

REASSIGN OWNED BY cloudsqlsuperuser TO "intended-application-user";

This changes all objects owned by cloudsqlsuperuser in that database and can also change ownership of shared objects such as databases and tablespaces. Verify the affected objects before running it. Do not use this blanket statement if it would transfer objects that should remain owned by cloudsqlsuperuser, such as extension objects.

If you need to return to the source, read the rollback limitations before proceeding.

Finalizing the migration ¶

Run the finalization command:

shell

nais cloudsql migrate finalize --team <team> --environment <environment> <appname> <new-sql-instance-name>

Finalization removes the Google migration job and connection profiles, deletes the old instance and temporary migration resources, and removes the migration configuration from the cluster.

Rolling back the migration ¶

To abandon the migration before finalization, run:

shell

nais cloudsql migrate rollback --team <team> --environment <environment> <appname> <new-sql-instance-name>

Rollback attempts to remove the destination, helper Application, Google migration job and connection profiles, and migration resources. If the application has already switched, it updates the live Application to use the source again. Ensure your repository's Application manifest also points to the source before deploying.