Overview

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

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

Eacheligible Cloud SQL instance has asingle built-in write endpoint whose name, creation, and update are managed byCloud 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 writeendpoint for read operations, such as queries. The private IP address pointed toby the write endpoint is automatically changed by Cloud SQL when you perform areplica failover or switchover operation to promote a replica instance to be thenew primary instance.

Generate the write endpoint

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

• The following APIs must beenabled 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 beCloud SQL Enterprise Plus edition.
• The Cloud SQL instance must be configured to use a private IP withprivate 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 previouslylisted prerequisites are met. If your existing instance is in the old networkarchitecture, then you must firstupgrade 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 youwant Cloud SQL to generate a write endpoint automatically, thencreate areplica that's enabled foradvanced disaster recovery.

View the write endpoint

gcloudsqlinstancesdescribeINSTANCE_NAME\|greppsaWriteEndpoint

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 aneligibleinstance, then refer toTroubleshooting.

Connect to a Cloud SQL instance using a write endpoint

psql-UDATABASE_NAME-hWRITE_ENDPOINT

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

psql"sslmode=SSL_MODE \    sslrootcert=SSL_ROOT_SERVER \    sslcert=SSL_CERT \    sslkey=SSL_KEY \    host=WRITE_ENDPOINT \    port=PORT user=USERNAME \    dbname=DATABASE_NAME"

Connect database clients to instances using the Cloud SQL Auth Proxy or Cloud SQL Language Connectors

When you configure the Cloud SQL Auth Proxy or one of the Cloud SQL Language Connectors using awrite endpoint DNS name, the Cloud SQL connector periodically check foraswitchover orfailover operation.When the Cloud SQL connector detects that the write endpoint DNSname refers to a different instance, it closes all open connections to the oldinstance. Subsequent connection attempts are directed to the new instance.

When the failover or switchover occurs, Cloud SQL updates the DNS record frommy-project:region:instance-a to the designatedDR replica instance:my-project:other-region:instance-b.

The Cloud SQL connector used by the application detects the change tothis DNS record. When the application connects to its database using the writeendpoint DNS name103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog, it connects to themy-project:other-region:instance-b Cloud SQL instance.

The connector or Auth Proxy automatically closes all existing connections tomy-project:region:instance-a. This forces any connection pools used by theapplication to establish new connections. It can also cause database queries inprogress to fail.

The Cloud SQL Auth Proxy polls for changes to the DNS name every 30 seconds.

Update the instance network configuration

If your instance was created before August 8, 2025, you might need to update the instance's network configuration for Cloud SQL Language Connectors or the Cloud SQL Auth Proxy to be able to use the write endpoint. You only need to run this update task once for each instance. Run the following command:

# Update the primary instance DNS settingsgcloud\alphasqlinstancespatch"PRIMARY_NAME"\--reconcile-psa-networking

Connect database clients to instances using the Cloud SQL Auth Proxy

To connect to a Cloud SQL instance by its write endpoint and using theCloud SQL Auth Proxy, firststart the proxy using the write endpoint instead of the instance connectionname

$cloud-sql-proxy--portPORTWRITE_ENDPOINT

psqlhost=127.0.0.1\port=PORTuser=USERNAME\dbname=DATABASE_NAME"

Connect using Cloud SQL Language Connectors

To connect using one of the Cloud SQL Language Connectors, configure your applicationby following the instructions in theConnect using Cloud SQL LanguageConnectors documentation. Then,modify your database connection to use the write endpoint instead of theinstance DNS name.

StringjdbcUrl="jdbc:postgresql://WRITE_ENDPOINT/DATABASE_NAME?"+"&socketFactory=com.google.cloud.sql.postgres.SocketFactory"+"&user=USERNAME"+"&password=PASSWORD";

db,err:=sql.Open("cloudsql-postgres","host=WRITE_ENDPOINT user=USERNAME password=PASSWORD dbname=DATABASE_NAME sslmode=disable",)

engine=sqlalchemy.create_engine("postgresql+pg8000://",creator=lambda:connector.connect("WRITE_ENDPOINT",# using DNS name"pg8000",user="USERNAME",password="PASSWORD",db="DATABASE_NAME"),)

importpgfrom'pg';import{Connector}from'@google-cloud/cloud-sql-connector';const{Pool}=pg;constconnector=newConnector();constclientOpts=awaitconnector.getOptions({domainName:'WRITE_ENDPOINT',ipType:'PUBLIC',});constpool=newPool({...clientOpts,user:'USERNAME',password:'PASSWORD',database:'DATABASE_NAME',max:5,});

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.

Troubleshooting

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

Architecture of a write endpoint

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

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

• Creates aprivate DNS zone in the service Cloud SQL producer VPC network
• Creates apeering 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:

DNS resolutions issues

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

1. Make sure allprerequisites 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 thegcloud compute instances list command:

   gcloudcomputeinstanceslist\--format="table( name, zone.basename(), networkInterfaces[].network )"\--project=PROJECT_NAME

   ReplacePROJECT_NAME with the project name where the DNS consumer network resides.

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

   gclouddnsmanaged-zoneslist\--project=PROJECT_NAME

   ReplacePROJECT_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 thegcloud beta sql instances patch command:

   gcloudbetasqlinstancespatchINSTANCE_NAME--reconcile-psa-networking

   ReplaceINSTANCE_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 eachof the following items:

1. Make sure that allprerequisites are completed.
2. Make sure there isn't a leftover peering DNS zone with the DNS namesql-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 thesql-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 thegcloud dns managed-zones list command:

   gclouddnsmanaged-zoneslist\--project=PROJECT_NAME

   ReplacePROJECT_NAME with the name of the project where the DNS consumer network resides.

   If a DNS zone exists with thesql-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 thegcloud dns managed-zones deletecommand:

   gclouddnsmanaged-zonesdeleteZONE_NAME

   ReplaceZONE_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 thegcloud beta sql instances patchcommand:

   gcloudbetasqlinstancespatchINSTANCE_NAME--reconcile-psa-networking

   ReplaceINSTANCE_NAME with the name of your Cloud SQL instance.

What's next

• Learn more aboutCloud SQL troubleshooting.