Connect to an instance using a write endpoint

MySQL   |  PostgreSQL   |  SQL Server

Overview

This page shows you how to use a write endpoint to connect from clients in your Virtual Private Cloud (VPC) network to a Cloud SQL instance using private services access (PSA).

A write endpoint is a global domain name service (DNS) name that resolves to the IP address of the current primary instance automatically. In the case of a replica failover or switchover operation, this write endpoint redirects incoming connections to the new primary instance automatically. You can use the write endpoint in a SQL connection string to the Cloud SQL instance instead of using an IP address. By using a write endpoint, you can avoid having to make application connection changes when you perform a replica failover or switchover operation for regional outage recovery or disaster recovery drill.

Each eligible Cloud SQL instance has a single built-in write endpoint whose name, creation, and update are managed by Cloud SQL. The following example illustrates its format:

  103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog.
  

The write endpoint always ends with the .global.sql-psa.goog. suffix. You can't modify the name or format of this write endpoint managed by Cloud SQL.

You can use the write endpoint for all write operations on the primary instance, including inserts, updates, deletes, and DDL changes. You can also use the write endpoint for read operations, such as queries. The private IP address pointed to by the write endpoint is automatically changed by Cloud SQL when you perform a replica failover or switchover operation to promote a replica instance to be the new primary instance.

Generate the write endpoint

If you create a new Cloud SQL instance, then Cloud SQL automatically creates the write endpoint when the following prerequisites are met:

• The following APIs must be enabled in the Google Cloud project where your Cloud SQL instance resides:
  • Compute Engine API
  • Cloud DNS API

  Failure to enable the Cloud DNS API in the project leads to the failure to create the peering DNS zone which will make the DNS names unusable.

  Once the peering DNS zone has been successfully created, it is important that it is not modified in any way. Any modifications including delete will render the DNS to be unusable for database connection.

• The Cloud SQL instance must be Cloud SQL Enterprise Plus edition.
• The Cloud SQL instance must be configured to use a private IP with private service access (PSA) enabled.
• The feature requires instances on the new network architecture. In most cases, new instances are created with the new architecture. To verify this, check the network architecture of your instance.

When you upgrade an existing Cloud SQL Enterprise edition instance to an Cloud SQL Enterprise Plus edition instance, Cloud SQL automatically generates the write endpoint if the previously listed prerequisites are met. If your existing instance is in the old network architecture, then you must first upgrade the instance to the new network architecture to get the write endpoint.

If you already have a Cloud SQL Enterprise Plus edition instance without the write endpoint and you want Cloud SQL to generate a write endpoint automatically, then create a replica that's enabled for advanced disaster recovery.

View the write endpoint

gcloud

To find the write endpoint, use the following gcloud CLI command:

      gcloud sql instances describe INSTANCE_NAME \
      | grep psaWriteEndpoint
    

Make the following replacements:

INSTANCE_NAME: the name of the Cloud SQL instance.

Write endpoints always end with the .global.sql-psa.goog. suffix, similar to the following example:

  103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog.
  

If you don't see the write endpoint for an eligible instance, then refer to Troubleshooting.

Connect to a Cloud SQL instance using a write endpoint

mysql

To connect a mysql client to a Cloud SQL instance using the write endpoint, run the following command:

    mysql -u root -h WRITE_ENDPOINT -p
  

Make the following replacements:

WRITE_ENDPOINT: the DNS name or write endpoint. This alphanumeric value always ends with the .global.sql-psa.goog. suffix. For example, 103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog..

Connect database clients with database instances using write endpoint over an SSL/TLS connection

mysql

To connect database clients to instances using a write endpoint over an SSL/TLS connection, run the following command:

  mysql -uroot -pcloudsql -h 103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog. \
    --ssl-ca=SERVER_CA_SSL \
    --ssl-cert=SSL_CERT \
    --ssl-key=SSL_KEY \
    --ssl-verify-server-cert
  

Make the following replacements:

• SERVER_CA_SSL: the name of the server certificate authority SSL file. For example, server-ca.pem.
• SSL_CERT: the name of the SSL certificate for the client. For example, client-cert.pem.
• SSL_KEY: the name of the client's SSL key. For example, client-key.pem.

Limitations

• Write endpoints aren't available for Cloud SQL Enterprise edition instance creations.
• Write endpoints aren't available for public IP only instances or Private Service Connect only instances.
• Write endpoints aren't available for use with the Cloud SQL Auth Proxy or language connectors.

Troubleshooting

The following sections describe the architecture of write endpoints and address common troubleshooting issues.

Architecture of a write endpoint

When you create an eligible instance, a write endpoint is generated by default.

To create a write endpoint, Cloud SQL performs the following setup:

• Creates a private DNS zone in the service Cloud SQL producer VPC network
• Creates a peering DNS zone in the customer VPC network
• Creates a DNS record in the private DNS zone in the service producer network

The following diagram illustrates how this process works:

Figure 1. Diagram showing how VPC peering supports DNS zone peering between a service producer network and a customer network.

DNS resolutions issues

If DNS resolution isn't working, then check each of the following items:

1. Make sure all prerequisites are met.
2. Make sure that the clients where the resolution is expected are located in the same network to which the Cloud SQL instance is attached. To check this, use the gcloud compute instances list command:

   gcloud compute instances list \
      --format="table( name, zone.basename(), networkInterfaces[].network )" \
      --project=PROJECT_NAME

   Replace PROJECT_NAME with the project name where the DNS consumer network resides.

3. Verify that the peering zone exists. To do so, use the gcloud dns managed-zones list command:

   gcloud dns managed-zones list \
       --project=PROJECT_NAME

   Replace PROJECT_NAME with the project name where the DNS consumer network resides.

4. If the peering zone doesn't exist, then you can fix the issue by using the gcloud beta sql instances patch command:

   gcloud beta sql instances patch INSTANCE_NAME --reconcile-psa-networking

   Replace INSTANCE_NAME with the name of your Cloud SQL instance.

New instance doesn't have a write endpoint

If a newly created instance doesn't contain a write endpoint, then check each of the following items:

1. Make sure that all prerequisites are completed.
2. Make sure there isn't a leftover peering DNS zone with the DNS name sql-psa.goog..

   A peering DNS zone is a leftover DNS zone if the network associated with the DNS zone doesn't have a VPC peering with the peer project ID of the peering DNS zone.

   If there's a leftover peering DNS zone with the sql-psa.goog. suffix, then delete it.

   Caution: Use extreme caution when you delete the peering DNS zone. If you delete the incorrect DNS zone, then you can cause connectivity loss for all instances attached to the network.

   To check for leftover peering DNS zones, use the gcloud dns managed-zones list command:

   gcloud dns managed-zones list \
      --project=PROJECT_NAME

   Replace PROJECT_NAME with the name of the project where the DNS consumer network resides.

   If a DNS zone exists with the sql-psa.goog. suffix, then delete the DNS zone after double-checking that the peering DNS zone is a leftover DNS zone.

   To delete a DNS zone, use the gcloud dns managed-zones delete command:

   gcloud dns managed-zones delete ZONE_NAME

   Replace ZONE_NAME with the DNS zone name associated with the write endpoints. Values are alphanumeric and use the following format: cloud-sql-psa-dns-1234567890.

3. You can fix a missing write endpoint for an eligible instance by using the gcloud beta sql instances patch command:

   gcloud beta sql instances patch INSTANCE_NAME --reconcile-psa-networking

   Replace INSTANCE_NAME with the name of your Cloud SQL instance.

What's next

• Learn more about Cloud SQL troubleshooting.