Upgrade the database major version by migrating data

MySQL  |  PostgreSQL  |  SQL Server

This page describes how to migrate your data to an instance running a laterversion of PostgreSQL. Before proceeding with this method, considerupgrading the database major version in-place.

There are two ways to upgrade the database major version of your Cloud SQLfor PostgreSQL instance by migrating your data.

  • Option 1. Use theDatabase Migration Service (DMS). DMS supports migrating from a Cloud SQL for PostgreSQL instance. You can also use it to upgrade your database version.
  • Option 2. Move your data from one version of PostgreSQL to another byexporting data from the current instance andimporting that data into a new instance running the later version of PostgreSQL. This process involves downtime; you put the current instance into read-only mode before starting the export.

The rest of this page discusses the second option.

Plan a major version upgrade

  1. Choose a target major version.

    See thelist of versions that Cloud SQL supports.

  2. Consider the features offered in each PostgreSQL version and addressincompatibilities.

    New major versions introduce incompatible changes that might require you tomodify the application code, the schema, or the database settings beforeyou can upgrade your database instance. Review the release notes of yourtarget major version to determine the incompatibilities that you need toaddress. If you're skipping major versions, address the incompatibilitieslisted for each version that you're skipping.

  3. Test the upgrade with a dry run.

    Perform a dry run of the end-to-end upgrade process with a test instancebefore you upgrade the production database. You might want to test the upgradeusing acloneinstead of your production database to avoid any performance impact from theexport on your production workload.

    In addition to validating that the upgrade completes successfully, runtests to understand the expected downtime of the upgrade, confirm yourupgrade workflow, and ensure that the application behaves as expected on the upgradeddatabase. If you haven't enabledautomatic storage increases,take note of the disk storage used by the upgraded dry run instance todetermine whether you need to increase the storage capacity for theproduction instance before upgrading.

  4. Decide when you want to upgrade.

    Note: Upgrades require the instance to become unavailable for a period oftime. Be sure to schedule your upgrade when database activity is low.

Migrate your data

Migrating entails using thepg_dumpcommand toexport the datafrom the source instance and thepg_restorecommand toimport the datainto the target instance.

To migrate your data to a Cloud SQL instance running a more recent databaseversion, follow these steps:

  1. Create the target instance with the desired PostgreSQL version.

    Make sure the target instance has:

    • Sufficient storage to hold all of the current instance's data.
    • The same authorized networks as the current instance.Learn more.
    • The same user accounts, with the same PostgreSQL privileges and passwords.

    For more information, seeCreating an instance.

  2. Confirm that you canconnect to the new instance with your local PostgreSQLtools and update them, if necessary.

  3. Export the current instance's data to a PostgreSQL dump file, following theinstructions inExporting data for Import into Cloud SQL.

    Donot export thepostgres system database. Thepostgres database isthe default database you connect to before you have created any otherdatabases. Once you create another database, switch to it in orderto create tables and insert data. Don't use thepostgres database for yourapplication's data.

  4. Create a Cloud Storage bucketif needed, and upload your SQL dump file to the bucket.

  5. Import the data to the target instance, following the instructions inImporting PostgreSQL databases from Cloud Storage.

  6. Optional. After completing the upgrade process, set up replicationbetween the source and target instances usingpglogical to update thetarget with all changes that have occurred since the initial dump wasstarted. Once the two instances are in sync, you can promote the targetinstance.

    For information about usingpglogical to implement continuous replication,seeConfigure your source.

  7. Update your applications to connect to the new instance.

  8. When you're confident that your new instance is operating successfully,delete the old instance.

What's next

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-07-14 UTC.