Clone instances

This page explains cloning, and describes how to clone an instance.

Overview

Cloning a Cloud SQL instance creates a new instance that is a copy of the source instance. The new instance is completely independent from the source instance.

Frequently asked questions

Question Answer
Does cloning impact performance? No. Cloning has no performance impact on the source instance.
Are backups copied to the new instance? No. The new instance creates new automated backups. Manual backups are not copied over from the source instance.
Does the new instance have the same IP address or addresses? No. The new instance has a new IP address or addresses.
Does the new instance have the same configuration settings? Yes. The new instance has the same settings such as database flags, connectivity options, machine type, and storage and memory settings.
Are replicas copied to the new instance? No. You need to create new replicas for the new instance.
Can you clone a replica? No. You can't clone a replica.
Can you make a clone from an earlier point in time? Yes. Point-in-time recovery uses cloning to restore an instance from an earlier point in time. This helps you recover your database from a destructive event.
Are the maintenance settings of the source instance automatically copied to the clone instance? No. You need to configure the maintenance settings for the clone instance.
Can you clone an instance that was once a clone? Yes. You can clone an instance that was cloned from another instance.
Are database users copied to the new instance? Yes, but database user passwords are not copied, and need to be recreated.

Clone an instance

You can clone a Cloud SQL instance by using the Google Cloud console, gcloud CLI, Terraform, or the API.

Console

  1. In the Google Cloud console, go to the Cloud SQL Instances page.

    Go to Cloud SQL Instances

  2. Find the row of the instance to clone.
  3. In the Actions column, click the More Actions menu.
  4. Click Create clone.
  5. On the Create a clone page, update the instance ID if needed, and click Create clone, leaving Clone current state of instance selected.

    You are returned to the instance listing page while the clone initializes.

gcloud

To clone an instance, use the gcloud sql instances clone command:

gcloud sql instances clone SOURCE_INSTANCE_NAME DESTINATION_INSTANCE_NAME \
--project PROJECT_ID \
--preferred-zone ZONE_NAME \
--preferred-secondary-zone SECONDARY_ZONE_NAME

Make the following replacements:

  • SOURCE_INSTANCE_NAME: the name of the Cloud SQL instance to clone.
  • DESTINATION_INSTANCE_NAME: the name of the cloned instance.
  • PROJECT_ID: the ID or project number of the Google Cloud project that contains the source and destination instances.
  • ZONE_NAME: Optional. The name of the primary zone for the destination instance. Use this if you want the destination instance to be in a different primary zone than the Cloud SQL instance that you're cloning. For a regional instance, this zone replaces the primary zone, but the secondary zone remains the same as the source instance.
  • SECONDARY_ZONE_NAME: Optional. The name of the secondary zone for the destination instance. Use this to specify a different secondary zone for the regional Cloud SQL instance that you want to clone.

If you're using the --preferred-zone and --preferred-secondary-zone parameters, then the following conditions apply:

  • Both the primary and secondary zones must be valid zones.
  • Both zones must belong to the same region as the source instance.
  • The primary and secondary zones must be different.
  • For zonal instances, you can't use the --preferred-secondary-zone parameter. If you do, then the process to clone the instance fails.
  • If you don't specify values for either the --preferred-zone or --preferred-secondary-zone parameters, then the cloned instance has the same primary and secondary zones as the source instance.

To run the gcloud sql instances clone command, you must have the cloudsql.instances.clone permission. For more information about required permissions to run gcloud CLI commands, see Cloud SQL permissions.

Terraform

To clone the instance, use a Terraform resource

resource "google_sql_database_instance" "clone" {
  name             = "mysql-instance-clone-name"
  region           = "us-central1"
  database_version = "MYSQL_8_0"
  clone {
    source_instance_name = google_sql_database_instance.source.id
  }
  # set `deletion_protection` to true, will ensure that one cannot accidentally delete this instance by
  # use of Terraform whereas `deletion_protection_enabled` flag protects this instance at the GCP level.
  deletion_protection = false
}

Apply the changes

To apply your Terraform configuration in a Google Cloud project, complete the steps in the following sections.

Prepare Cloud Shell

  1. Launch Cloud Shell.

  2. Set the default Google Cloud project where you want to apply your Terraform configurations.

    You only need to run this command once per project, and you can run it in any directory.

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

    Environment variables are overridden if you set explicit values in the Terraform configuration file.

Prepare the directory

Each Terraform configuration file must have its own directory (also called a root module).

  1. In Cloud Shell, create a directory and a new file within that directory. The filename must have the .tf extension—for example main.tf. In this tutorial, the file is referred to as main.tf. 
    mkdir DIRECTORY && cd DIRECTORY && touch main.tf

  2. If you are following a tutorial, you can copy the sample code in each section or step.

    Copy the sample code into the newly created main.tf.

    Optionally, copy the code from GitHub. This is recommended when the Terraform snippet is part of an end-to-end solution.

  3. Review and modify the sample parameters to apply to your environment.
  4. Save your changes.
  5. Initialize Terraform. You only need to do this once per directory. 
    terraform init

    Optionally, to use the latest Google provider version, include the -upgrade option: 

    terraform init -upgrade

Apply the changes

  1. Review the configuration and verify that the resources that Terraform is going to create or update match your expectations: 
    terraform plan

    Make corrections to the configuration as necessary.

  2. Apply the Terraform configuration by running the following command and entering yes at the prompt: 
    terraform apply

    Wait until Terraform displays the "Apply complete!" message.

  3. Open your Google Cloud project to view the results. In the Google Cloud console, navigate to your resources in the UI to make sure that Terraform has created or updated them.

Delete the changes

To delete your changes, do the following:

  1. To disable deletion protection, in your Terraform configuration file set the deletion_protection argument to false. 
    deletion_protection =  "false"
  2. Apply the updated Terraform configuration by running the following command and entering yes at the prompt: 
    terraform apply

  1. Remove resources previously applied with your Terraform configuration by running the following command and entering yes at the prompt:

    terraform destroy

REST v1

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

  • PROJECT_ID: the ID or project number of the Google Cloud project that contains the source and destination instances.
  • SOURCE_INSTANCE_NAME: the name of the Cloud SQL instance to clone.
  • DESTINATION_INSTANCE_NAME: the name of the cloned instance.
  • ZONE_NAME: Optional. The name of the primary zone for the destination instance. Use this if you want the destination instance to be in a different primary zone than the Cloud SQL instance that you're cloning. For a regional instance, this zone replaces the primary zone, but the secondary zone remains the same as the source instance.
  • SECONDARY_ZONE_NAME: Optional. The name of the secondary zone for the destination instance. Use this to specify a different secondary zone for the regional Cloud SQL instance that you want to clone.

HTTP method and URL: 

POST https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/SOURCE_INSTANCE_NAME/clone

Request JSON body: 

{
  "cloneContext":
  {
    "destinationInstanceName": "DESTINATION_INSTANCE_NAME",
    "preferredZone": "ZONE_NAME",
    "preferredSecondaryZone": "SECONDARY_ZONE_NAME"
  }
}

To send your request, expand one of these options:

You should receive a JSON response similar to the following:

If you're using the preferredZone and preferredSecondaryZone parameters, then the following conditions apply:

  • Both the primary and secondary zones must be valid zones.
  • Both zones must belong to the same region as the source instance.
  • The primary and secondary zones must be different.
  • For zonal instances, you can't use the preferredSecondaryZone parameter. If you do, then the process to clone the instance fails.
  • If you don't specify values for either the preferredZone or preferredSecondaryZone parameters, then the cloned instance has the same primary and secondary zones as the source instance.

To use the instances.clone API method, you must have the cloudsql.instances.clone permission. For more information about required permissions to use API methods, see Cloud SQL permissions.

REST v1beta4

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

  • PROJECT_ID: the ID or project number of the Google Cloud project that contains the source and destination instances.
  • SOURCE_INSTANCE_NAME: the name of the Cloud SQL instance to clone.
  • DESTINATION_INSTANCE_NAME: the name of the cloned instance.
  • ZONE_NAME: Optional. The name of the primary zone for the destination instance. Use this if you want the destination instance to be in a different primary zone than the Cloud SQL instance that you're cloning. For a regional instance, this zone replaces the primary zone, but the secondary zone remains the same as the source instance.
  • SECONDARY_ZONE_NAME: Optional. The name of the secondary zone for the destination instance. Use this to specify a different secondary zone for the regional Cloud SQL instance that you want to clone.

HTTP method and URL: 

POST https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/SOURCE_INSTANCE_NAME/clone

Request JSON body: 

{
  "cloneContext":
  {
    "destinationInstanceName": "DESTINATION_INSTANCE_NAME",
    "preferredZone": "ZONE_NAME",
    "preferredSecondaryZone": "SECONDARY_ZONE_NAME"
  }
}

To send your request, expand one of these options:

You should receive a JSON response similar to the following:

If you're using the preferredZone and preferredSecondaryZone parameters, then the following conditions apply:

  • Both the primary and secondary zones must be valid zones.
  • Both zones must belong to the same region as the source instance.
  • The primary and secondary zones must be different.
  • For zonal instances, you can't use the preferredSecondaryZone parameter. If you do, then the process to clone the instance fails.
  • If you don't specify values for either the preferredZone or preferredSecondaryZone parameters, then the cloned instance has the same primary and secondary zones as the source instance.

To use the instances.clone API method, you must have the cloudsql.instances.clone permission. For more information about required permissions to use API methods, see Cloud SQL permissions.

Clone an instance that uses an internal IP address

If your Cloud SQL instance uses an internal IP address, you can optionally specify an allocated IP range for the clone's new IP address. For example, google-managed-services-default.

gcloud

Clone the instance, optionally specifying the allocated IP range you want to use:

gcloud sql instances clone SOURCE_INSTANCE_NAME TARGET_INSTANCE_NAME \
--allocated-ip-range-name ALLOCATED_IP_RANGE_NAME

The user or service account that's running the gcloud sql instances clone command must have the cloudsql.instances.clone permission. For more information about required permissions to run gcloud CLI commands, see Cloud SQL permissions.

REST v1

Clone the instance, optionally specifying the allocated IP range you want to use:

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

  • project-id: the project ID
  • source-instance-id: the source instance ID
  • target-instance-id: the target instance ID
  • allocated-ip-range-name: the name of an allocated IP range

HTTP method and URL: 

POST https://sqladmin.googleapis.com/v1/projects/project-id/instances/source-instance-id/clone

Request JSON body: 

{
  "cloneContext":
  {
    "destinationInstanceName": "target-instance-id",
    "allocatedIpRange": "allocated-ip-range-name"
  }
}

To send your request, expand one of these options:

You should receive a JSON response similar to the following:

The user or service account that's using the instances.clone API method must have the cloudsql.instances.clone permission. For more information about required permissions to use API methods, see Cloud SQL permissions.

REST v1beta4

Clone the instance, optionally specifying the allocated IP range you want to use:

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

  • project-id: the project ID
  • source-instance-id: the source instance ID
  • target-instance-id: the target instance ID
  • allocated-ip-range-name: the name of an allocated IP range

HTTP method and URL: 

POST https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/source-instance-id/clone

Request JSON body: 

{
  "cloneContext":
  {
    "destinationInstanceName": "target-instance-id",
    "allocatedIpRange": "allocated-ip-range-name"
  }
}

To send your request, expand one of these options:

You should receive a JSON response similar to the following:

The user or service account that's using the instances.clone API method must have the cloudsql.instances.clone permission. For more information about required permissions to use API methods, see Cloud SQL permissions.

If you don't specify an allocated IP range, the following behavior is applied:

  • If the source instance was created with a specified range, the cloned instance is created in the same range.
  • If the source instance was not created with a specified range, the cloned instance is created in a random range.

Troubleshoot

Issue Troubleshooting
Cloning fails with constraints/sql.restrictAuthorizedNetworks error. The cloning operation is blocked by the Authorized Networks configuration. Authorized Networks are configured for public IP addresses in the Connectivity section of the Google Cloud console, and cloning is not permitted due to security considerations.

Remove all Authorized Networks entries from the Cloud SQL instance if you can. Otherwise, create a replica without any Authorized Networks entries.
Error message: Failed to create subnetwork. Couldn't find free blocks in allocated IP ranges. Please allocate new ranges for this service provider. Help Token: [help-token-id].

You're trying to use the Google Cloud console to clone an instance with a private IP address, but you didn't specify the allocated IP range that you want to use and the source instance isn't created with the specified range. As a result, the cloned instance is created in a random range.

Use gcloud to clone the instance and provide a value for the
--allocated-ip-range-name parameter. For more information, see Cloning an instance with a private IP.