Conéctate a una instancia con un extremo de escritura

MySQL   |  PostgreSQL   |  SQL Server

Descripción general

En esta página, se muestra cómo usar un extremo de escritura para conectarse desde clientes en tu red de nube privada virtual (VPC) a una instancia de Cloud SQL con acceso a servicios privados (PSA).

Un extremo de escritura es un nombre de servicio de nombre de dominio (DNS) global que se resuelve automáticamente en la dirección IP de la instancia principal actual. En el caso de una operación de conmutación por error o cambio de réplica, este extremo de escritura redirecciona automáticamente las conexiones entrantes a la nueva instancia principal. Puedes usar el extremo de escritura en una cadena de conexión de SQL a la instancia de Cloud SQL en lugar de usar una dirección IP. Cuando usas un extremo de escritura, puedes evitar tener que realizar cambios en la conexión de la aplicación cuando realizas una operación de conmutación por error o cambio de réplica para la recuperación ante interrupciones regionales o simulacros de recuperación ante desastres.

Cada instancia de Cloud SQL apta tiene un solo extremo de escritura integrado cuyo nombre, creación y actualización administra Cloud SQL. En el siguiente ejemplo, se ilustra su formato:

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

El extremo de escritura siempre termina con el sufijo .global.sql-psa.goog.. No puedes modificar el nombre ni el formato de este extremo de escritura administrado por Cloud SQL.

Puedes usar el extremo de escritura para todas las operaciones de escritura en la instancia principal, incluidas las inserciones, las actualizaciones, las eliminaciones y los cambios en el DDL. También puedes usar el extremo de escritura para operaciones de lectura, como las consultas. Cloud SQL cambia automáticamente la dirección IP privada a la que apunta el extremo de escritura cuando realizas una operación de conmutación por error o cambio de réplica para promover una instancia de réplica como la nueva instancia principal.

Genera el extremo de escritura

Si creas una instancia de Cloud SQL nueva, Cloud SQL creará automáticamente el extremo de escritura cuando se cumplan los siguientes requisitos previos:

• Las siguientes APIs deben estar habilitadas en el proyecto Google Cloud en el que reside tu instancia de Cloud SQL:
  • API de Compute Engine
  • APIs de Cloud DNS

  Si no se habilita la API de Cloud DNS en el proyecto, no se podrá crear la zona de DNS de intercambio de tráfico, lo que hará que los nombres de DNS sean inutilizables.

  Una vez que se haya creado correctamente la zona de DNS de intercambio, es importante que no se modifique de ninguna manera. Cualquier modificación, incluida la eliminación, hará que el DNS sea inutilizable para la conexión a la base de datos.

• La instancia de Cloud SQL debe ser de la edición Cloud SQL Enterprise Plus.
• La instancia de Cloud SQL debe configurarse para usar una IP privada con el acceso a servicios privados (PSA) habilitado.
• La función requiere instancias en la nueva arquitectura de red. En la mayoría de los casos, las instancias nuevas se crean con la nueva arquitectura. Para verificar esto, consulta la arquitectura de red de tu instancia.

Cuando actualizas una instancia existente de la edición de Cloud SQL Enterprise a una instancia de la edición de Cloud SQL Enterprise Plus, Cloud SQL genera automáticamente el extremo de escritura si se cumplen los requisitos previos mencionados anteriormente. Si tu instancia existente está en la arquitectura de red anterior, primero debes actualizar la instancia a la nueva arquitectura de red para obtener el extremo de escritura.

Si ya tienes una instancia de la edición de Cloud SQL Enterprise Plus sin el extremo de escritura y deseas que Cloud SQL genere un extremo de escritura automáticamente, crea una réplica que esté habilitada para la recuperación ante desastres avanzada.

Visualiza el extremo de escritura

gcloud

Para encontrar el extremo de escritura, usa el siguiente comando de gcloud CLI:

      gcloud sql instances describe INSTANCE_NAME \
      | grep psaWriteEndpoint
    

Realiza los siguientes reemplazos:

INSTANCE_NAME: el nombre de la instancia de Cloud SQL.

Los extremos de escritura siempre terminan con el sufijo .global.sql-psa.goog., de manera similar al siguiente ejemplo:

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

Si no ves el extremo de escritura de una instancia apta, consulta Solución de problemas.

Conéctate a una instancia de Cloud SQL con un extremo de escritura

mysql

Para conectar un cliente de mysql a una instancia de Cloud SQL con el extremo de escritura, ejecuta el siguiente comando:

    mysql -u root -h WRITE_ENDPOINT -p
  

Realiza los siguientes reemplazos:

WRITE_ENDPOINT: Es el nombre de DNS o el extremo de escritura. Este valor alfanumérico siempre termina con el sufijo .global.sql-psa.goog.. Por ejemplo, 103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog..

Conecta clientes de bases de datos con instancias de bases de datos a través de un extremo de escritura en una conexión SSL/TLS

mysql

Para conectar clientes de bases de datos a instancias con un extremo de escritura a través de una conexión SSL/TLS, ejecuta el siguiente comando:

  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
  

Realiza los siguientes reemplazos:

• SERVER_CA_SSL: Es el nombre del archivo SSL de la entidad de certificación del servidor. Por ejemplo, server-ca.pem
• SSL_CERT: Es el nombre del certificado SSL para el cliente. Por ejemplo: client-cert.pem
• SSL_KEY: Es el nombre de la clave SSL del cliente. Por ejemplo, client-key.pem.

Conecta clientes de bases de datos a instancias con el proxy de Cloud SQL Auth o los conectores de lenguaje de Cloud SQL

Cuando configuras el proxy de Cloud SQL Auth o uno de los conectores de lenguaje de Cloud SQL con un nombre de DNS de extremo de escritura, el conector de Cloud SQL verifica periódicamente si hay una operación de conmutación o conmutación por error. Cuando el conector de Cloud SQL detecta que el nombre DNS del extremo de escritura hace referencia a una instancia diferente, cierra todas las conexiones abiertas a la instancia anterior. Los intentos de conexión posteriores se dirigen a la instancia nueva.

Precaución: Asegúrate de notificar a los propietarios de las aplicaciones antes de iniciar una operación de conmutación o de conmutación por error. Durante el cambio y la conmutación por error, el conector o el proxy de autenticación finalizan de forma forzada todas las conexiones abiertas a la base de datos.

Por ejemplo, supongamos que una aplicación está configurada para conectarse con el nombre de DNS del extremo de escritura 103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog. Inicialmente, la zona DNS se configura con un registro que apunta a la instancia principal, my-project:region:instance-a. La aplicación establece conexiones con la instancia de my-project:region:instance-a Cloud SQL.

Cuando se produce la conmutación por error o el cambio, Cloud SQL actualiza el registro DNS de my-project:region:instance-a a la instancia de réplica de DR designada: my-project:other-region:instance-b.

El conector de Cloud SQL que usa la aplicación detecta el cambio en este registro DNS. Cuando la aplicación se conecta a su base de datos con el nombre de DNS del extremo de escritura 103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog, se conecta a la instancia de Cloud SQL my-project:other-region:instance-b.

El conector o el proxy de autenticación cierran automáticamente todas las conexiones existentes a my-project:region:instance-a. Esto obliga a los grupos de conexiones que usa la aplicación a establecer conexiones nuevas. También puede provocar que fallen las consultas de bases de datos en curso.

El proxy de autenticación de Cloud SQL sondea los cambios en el nombre de DNS cada 30 segundos.

Actualiza la configuración de red de la instancia

Si tu instancia se creó antes del 8 de agosto de 2025, es posible que debas actualizar la configuración de red de la instancia para que los conectores de lenguaje de Cloud SQL o el proxy de autenticación de Cloud SQL puedan usar el extremo de escritura. Solo debes ejecutar esta tarea de actualización una vez por cada instancia. Ejecuta el siguiente comando:

CLI de gcloud

  # Update the primary instance DNS settings
  gcloud \
      alpha sql instances patch "PRIMARY_NAME" \
      --reconcile-psa-networking
  

Realiza los siguientes reemplazos:

• PRIMARY_NAME: El nombre de la instancia. Por ejemplo, my-instance

Conecta clientes de bases de datos a instancias con el proxy de autenticación de Cloud SQL

Para conectarte a una instancia de Cloud SQL por su extremo de escritura y con el proxy de autenticación de Cloud SQL, primero inicia el proxy con el extremo de escritura en lugar del nombre de conexión de la instancia.

mysql

  $ cloud-sql-proxy --port PORT WRITE_ENDPOINT
  

Luego, configura el cliente de la base de datos para que se conecte al proxy de Cloud SQL Auth:

  mysql -uUSERNAME -h 127.0.0.1 -p PORT DATABASE_NAME
  

Realiza los siguientes reemplazos:

• WRITE_ENDPOINT: Es el nombre de DNS o el extremo de escritura. Este valor alfanumérico siempre termina con el sufijo .global.sql-psa.goog.. Por ejemplo, 103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog..
• PORT: Es el número de puerto que usa el proxy para escuchar las conexiones. Por ejemplo, 3306
• USERNAME: Es el nombre de usuario de MySQL. Por ejemplo, root
• DATABASE_NAME: Es el nombre de la base de datos. Por ejemplo, mysql.

Conéctate mediante conectores de lenguaje de Cloud SQL

Para conectarte con uno de los conectores de lenguaje de Cloud SQL, configura tu aplicación siguiendo las instrucciones de la documentación sobre cómo conectarse con los conectores de lenguaje de Cloud SQL. Luego, modifica la conexión de la base de datos para usar el extremo de escritura en lugar del nombre de DNS de la instancia.

Java

  String jdbcUrl = "jdbc:mysql://WRITE_ENDPOINT/DATABASE_NAME?"
    +   "&socketFactory=com.google.cloud.sql.mysql.SocketFactory"
    +   "&user=USERNAME"
    +   "&password=PASSWORD";
  

Realiza los siguientes reemplazos:

• WRITE_ENDPOINT: Es el nombre de DNS o el extremo de escritura. Este valor alfanumérico siempre termina con el sufijo .global.sql-psa.goog..
• DATABASE_NAME: Es el nombre de la base de datos. Por ejemplo, my-database
• USERNAME: El nombre de usuario Por ejemplo, postgres
• PASSWORD: Es la contraseña de la base de datos.

Para obtener más información, consulta la documentación del conector de Java en GitHub.

Go

    db, err := sql.Open(
        "cloudsql-mysql",
        "USERNAME:PASSWORD@cloudsql-mysql(WRITE_ENDPOINT)/DATABASE_NAME",
    )
  

Realiza los siguientes reemplazos:

• WRITE_ENDPOINT: Es el nombre de DNS o el extremo de escritura. Este valor alfanumérico siempre termina con el sufijo .global.sql-psa.goog..
• DATABASE_NAME: Es el nombre de la base de datos. Por ejemplo, my-database
• USERNAME: El nombre de usuario Por ejemplo, postgres
• PASSWORD: Es la contraseña de la base de datos.

Para obtener más información, consulta la documentación del conector de Go en GitHub.

Python

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

Realiza los siguientes reemplazos:

• WRITE_ENDPOINT: Es el nombre de DNS o el extremo de escritura. Este valor alfanumérico siempre termina con el sufijo .global.sql-psa.goog..
• DATABASE_NAME: Es el nombre de la base de datos. Por ejemplo, my-database
• USERNAME: El nombre de usuario Por ejemplo, postgres
• PASSWORD: Es la contraseña de la base de datos.

Para obtener más información, consulta la documentación del conector de Python en GitHub.

Node.js

  import mysql from 'mysql2/promise';
  import {Connector} from '@google-cloud/cloud-sql-connector';

  const connector = new Connector();
  const clientOpts = await connector.getOptions({
    domainName: 'WRITE_ENDPOINT',
    ipType: 'PUBLIC',
  });

  const pool = await mysql.createPool({
    ...clientOpts,
    user: 'USERNAME',
    password: 'PASSWORD',
    database: 'DATABASE_NAME',
  });
  

Realiza los siguientes reemplazos:

• WRITE_ENDPOINT: Es el nombre de DNS o el extremo de escritura. Este valor alfanumérico siempre termina con el sufijo .global.sql-psa.goog..
• DATABASE_NAME: Es el nombre de la base de datos. Por ejemplo, my-database
• USERNAME: El nombre de usuario Por ejemplo, postgres
• PASSWORD: Es la contraseña de la base de datos.

Para obtener más información, consulta la documentación del conector de Node.js en GitHub.

Limitaciones

• Los extremos de escritura no están disponibles para la creación de instancias de la edición de Cloud SQL Enterprise.
• Los extremos de escritura no están disponibles para instancias solo con IP pública ni para instancias solo con Private Service Connect.

Soluciona problemas

En las siguientes secciones, se describe la arquitectura de los extremos de escritura y se abordan problemas comunes de solución de problemas.

Arquitectura de un extremo de escritura

Cuando creas una instancia apta, se genera un extremo de escritura de forma predeterminada.

Para crear un extremo de escritura, Cloud SQL realiza la siguiente configuración:

• Crea una zona de DNS privada en la red de VPC del productor de servicios de Cloud SQL.
• Crea una zona de DNS de intercambio de tráfico en la red de VPC del cliente.
• Crea un registro DNS en la zona de DNS privado de la red del productor de servicios

En el siguiente diagrama, se ilustra cómo funciona este proceso:

Figura 1: Diagrama que muestra cómo el intercambio de tráfico entre VPC admite el intercambio de tráfico entre zonas de DNS entre una red de productor de servicios y una red de cliente.

Problemas con la resolución de DNS

Si la resolución de DNS no funciona, verifica cada uno de los siguientes elementos:

1. Asegúrate de que se cumplan todos los requisitos.
2. Asegúrate de que los clientes en los que se espera la resolución se encuentren en la misma red a la que está conectada la instancia de Cloud SQL. Para verificar esto, usa el comando gcloud compute instances list:

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

   Reemplaza PROJECT_NAME por el nombre del proyecto en el que reside la red del consumidor de DNS.

3. Verifica que exista la zona de intercambio de tráfico. Para ello, usa el comando gcloud dns managed-zones list:

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

   Reemplaza PROJECT_NAME por el nombre del proyecto en el que reside la red del consumidor de DNS.

4. Si la zona de peering no existe, puedes solucionar el problema con el comando gcloud beta sql instances patch:

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

   Reemplaza INSTANCE_NAME por el nombre de tu instancia de Cloud SQL.

La instancia nueva no tiene un extremo de escritura

Si una instancia recién creada no contiene un extremo de escritura, verifica cada uno de los siguientes elementos:

1. Asegúrate de que se cumplan todos los requisitos previos.
2. Asegúrate de que no haya una zona de intercambio de tráfico de DNS residual con el nombre de DNS sql-psa.goog..

   Una zona de DNS de intercambio de tráfico es una zona de DNS residual si la red asociada a la zona de DNS no tiene un intercambio de tráfico de VPC con el ID del proyecto de intercambio de tráfico de la zona de DNS de intercambio de tráfico.

   Si queda una zona DNS de intercambio de tráfico con el sufijo sql-psa.goog., bórrala.

   Precaución: Ten mucho cuidado cuando borres la zona DNS de intercambio de tráfico. Si borras la zona DNS incorrecta, puedes provocar la pérdida de conectividad de todas las instancias adjuntas a la red.

   Para verificar si quedan zonas de DNS de intercambio de tráfico, usa el comando gcloud dns managed-zones list:

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

   Reemplaza PROJECT_NAME por el nombre del proyecto en el que reside la red del consumidor de DNS.

   Si existe una zona DNS con el sufijo sql-psa.goog., bórrala después de verificar que la zona DNS de intercambio de tráfico sea una zona DNS residual.

   Para borrar una zona DNS, usa el comando gcloud dns managed-zones delete:

   gcloud dns managed-zones delete ZONE_NAME

   Reemplaza ZONE_NAME por el nombre de la zona DNS asociada con los extremos de escritura. Los valores son alfanuméricos y usan el siguiente formato: cloud-sql-psa-dns-1234567890.

3. Puedes corregir la falta de un extremo de escritura para una instancia apta con el comando gcloud beta sql instances patch:

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

   Reemplaza INSTANCE_NAME por el nombre de tu instancia de Cloud SQL.

¿Qué sigue?

• Obtén más información para solucionar problemas de Cloud SQL.