Información general
En esta página se explica cómo usar un endpoint de escritura para conectar clientes de tu red de nube privada virtual (VPC) a una instancia de Cloud SQL mediante acceso a servicios privados (PSA).
Un endpoint de escritura es un nombre de servicio de nombres 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 de cambio de una réplica, este endpoint de escritura redirige automáticamente las conexiones entrantes a la nueva instancia principal. Puedes usar el endpoint de escritura en una cadena de conexión SQL a la instancia de Cloud SQL en lugar de una dirección IP. Si usas un endpoint de escritura, no tendrás que hacer cambios en la conexión de la aplicación cuando realices una conmutación por error o una conmutación de réplica para recuperarte de una interrupción en una región o para hacer una prueba de recuperación ante desastres.
Cada instancia de Cloud SQL aptas tiene un único endpoint de escritura integrado cuyo nombre, creación y actualización gestiona Cloud SQL. En el siguiente ejemplo se muestra su formato:
103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog.
El endpoint de escritura siempre termina con el sufijo .global.sql-psa.goog..
No puedes modificar el nombre ni el formato de este endpoint de escritura gestionado por Cloud SQL.
Puede usar el endpoint de escritura para todas las operaciones de escritura en la instancia principal, incluidas las inserciones, las actualizaciones, las eliminaciones y los cambios de DDL. También puedes usar el endpoint write para operaciones de lectura, como las consultas. Cloud SQL cambia automáticamente la dirección IP privada a la que apunta el endpoint de escritura cuando realizas una operación de conmutación por error o de cambio de réplica para convertir una instancia de réplica en la nueva instancia principal.
Generar el endpoint de escritura
Si creas una instancia de Cloud SQL, Cloud SQL creará automáticamente el endpoint de escritura cuando se cumplan los siguientes requisitos:
- Las siguientes APIs deben estar habilitadas
en el Google Cloud proyecto en el que se encuentra tu instancia de Cloud SQL:
Si no se habilita la API Cloud DNS en el proyecto, no se podrá crear la zona DNS de emparejamiento, lo que hará que los nombres DNS no se puedan usar.
Una vez que se haya creado correctamente la zona de DNS de emparejamiento, es importante que no se modifique de ninguna manera. Cualquier modificación, incluida la eliminación, hará que el DNS no se pueda usar para la conexión de la base de datos.
- La instancia de Cloud SQL debe ser de la edición Enterprise Plus de Cloud SQL.
- La instancia de Cloud SQL debe configurarse para usar una IP privada con el acceso privado a servicios (PSA) habilitado.
- La función requiere instancias en la nueva arquitectura de red. En la mayoría de los casos, las nuevas instancias se crean con la nueva arquitectura. Para verificarlo, comprueba la arquitectura de red de tu instancia.
Cuando actualizas una instancia de la edición Enterprise de Cloud SQL a una instancia de la edición Enterprise Plus de Cloud SQL, Cloud SQL genera automáticamente el endpoint de escritura si se cumplen los requisitos previos indicados anteriormente. Si tu instancia se encuentra en la antigua arquitectura de red, primero debes actualizarla a la nueva arquitectura de red para obtener el endpoint de escritura.
Si ya tienes una instancia de Cloud SQL Enterprise Plus sin el endpoint de escritura y quieres que Cloud SQL genere un endpoint de escritura automáticamente, crea una réplica que tenga habilitada la recuperación tras desastres avanzada.
Ver el endpoint de escritura
gcloud
Para encontrar el endpoint de escritura, usa el siguiente comando de gcloud CLI:
gcloud sql instances describe INSTANCE_NAME \ | grep psaWriteEndpoint
Haz las siguientes sustituciones:
INSTANCE_NAME: el nombre de la instancia de Cloud SQL.
Los endpoints de escritura siempre terminan con el sufijo .global.sql-psa.goog., como en el siguiente ejemplo:
103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog.
Si no ves el endpoint de escritura de una instancia apta, consulta la sección Solución de problemas.
Conectarse a una instancia de Cloud SQL mediante un endpoint de escritura
psql
Para conectar un cliente psql a una instancia de Cloud SQL mediante el endpoint de escritura, ejecuta el siguiente comando:
psql -U DATABASE_NAME -h WRITE_ENDPOINT
Haz las siguientes sustituciones:
- DATABASE_NAME: el nombre de la base de datos. Por ejemplo,
postgres. - WRITE_ENDPOINT: el nombre de DNS o el endpoint de escritura. Este valor alfanumérico
siempre termina con el sufijo
.global.sql-psa.goog.. Por ejemplo,103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog..
Conectar clientes de bases de datos con instancias de bases de datos mediante un endpoint de escritura a través de una conexión SSL/TLS
psql
Para conectar clientes de bases de datos a instancias mediante un endpoint de escritura a través de una conexión SSL/TLS, ejecuta el siguiente comando:
psql "sslmode=SSL_MODE \ sslrootcert=SSL_ROOT_SERVER \ sslcert=SSL_CERT \ sslkey=SSL_KEY \ host=WRITE_ENDPOINT \ port=PORT user=USERNAME \ dbname=DATABASE_NAME"
Haz las siguientes sustituciones:
- SSL_MODE: el modo SSL utilizado. Por ejemplo,
verify-full. - SSL_ROOT_SERVER: nombre del servidor raíz SSL. Por ejemplo,
server-ca.pem. - SSL_CERT: el nombre del certificado SSL que usa el cliente. Por ejemplo,
client-cert.pem. - SSL_KEY: el nombre de la clave SSL que usa el cliente. Por ejemplo,
client-key.pem. - WRITE_ENDPOINT: el nombre de DNS o el endpoint de escritura. Este valor alfanumérico
siempre termina con el sufijo
.global.sql-psa.goog.. Por ejemplo,103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog.. - PORT: número de puerto utilizado. Por ejemplo,
5432. - USERNAME: el nombre de usuario. Por ejemplo,
postgres. - DATABASE_NAME: el nombre de la base de datos. Por ejemplo,
postgres.
Conectar clientes de bases de datos a instancias mediante el proxy de autenticación de Cloud SQL o los conectores de lenguaje de Cloud SQL
Cuando configuras el proxy de autenticación de Cloud SQL o uno de los conectores de lenguaje de Cloud SQL mediante un nombre de DNS de endpoint de escritura, el conector de Cloud SQL comprueba periódicamente si se ha producido un cambio o una conmutación por error. Cuando el conector de Cloud SQL detecta que el nombre DNS del endpoint de escritura hace referencia a otra instancia, cierra todas las conexiones abiertas a la instancia antigua. Los intentos de conexión posteriores se dirigen a la nueva instancia.
Por ejemplo, supongamos que una aplicación está configurada para conectarse mediante el nombre DNS del endpoint 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 Cloud SQL my-project:region:instance-a.
Cuando se produce la conmutación por error o la conmutación, Cloud SQL actualiza el registro DNS de my-project:region:instance-a a la instancia de réplica de recuperación ante desastres
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 mediante el nombre DNS del endpoint 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 Auth Proxy cierra automáticamente todas las conexiones existentes a my-project:region:instance-a. De esta forma, se obliga a los grupos de conexiones que utilice la aplicación a establecer nuevas conexiones. 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.
Actualizar la configuración de red de la instancia
Si tu instancia se creó antes del 8 de agosto del 2025, es posible que tengas que 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 endpoint de escritura. Solo tienes que 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
Haz las siguientes sustituciones:
- PRIMARY_NAME: el nombre de la instancia. Por ejemplo,
my-instance
Conectar clientes de bases de datos a instancias mediante el proxy de autenticación de Cloud SQL
Para conectarte a una instancia de Cloud SQL mediante su endpoint de escritura y el proxy de autenticación de Cloud SQL, primero inicia el proxy con el endpoint de escritura en lugar del nombre de conexión de la instancia.
psql
$ cloud-sql-proxy --port PORT WRITE_ENDPOINT
A continuación, configura el cliente de la base de datos para que se conecte al proxy de autenticación de Cloud SQL:
psql host=127.0.0.1 \ port=PORT user=USERNAME \ dbname=DATABASE_NAME"
Haz las siguientes sustituciones:
- WRITE_ENDPOINT: el nombre de DNS o el endpoint de escritura. Este valor alfanumérico
siempre termina con el sufijo
.global.sql-psa.goog.. Por ejemplo,103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog.. - PORT: número de puerto utilizado. Por ejemplo,
5432. - USERNAME: el nombre de usuario. Por ejemplo,
postgres. - DATABASE_NAME: el nombre de la base de datos. Por ejemplo,
postgres.
Conectarse mediante conectores de lenguaje de Cloud SQL
Para conectarte mediante uno de los conectores de lenguaje de Cloud SQL, configura tu aplicación siguiendo las instrucciones de la documentación sobre cómo conectarse mediante conectores de lenguaje de Cloud SQL. A continuación, modifica la conexión de la base de datos para usar el endpoint de escritura en lugar del nombre DNS de la instancia.
Java
String jdbcUrl = "jdbc:postgresql://WRITE_ENDPOINT/DATABASE_NAME?" + "&socketFactory=com.google.cloud.sql.postgres.SocketFactory" + "&user=USERNAME" + "&password=PASSWORD";
Haz las siguientes sustituciones:
- WRITE_ENDPOINT: el nombre de DNS o el endpoint de escritura. Este valor alfanumérico
siempre termina con el sufijo
.global.sql-psa.goog.. - DATABASE_NAME: el nombre de la base de datos. Por ejemplo,
my-database. - USERNAME: nombre de usuario. Por ejemplo,
postgres. - PASSWORD: la contraseña de la base de datos.
Go
db, err := sql.Open( "cloudsql-postgres", "host=WRITE_ENDPOINT user=USERNAME password=PASSWORD dbname=DATABASE_NAME sslmode=disable", )
Haz las siguientes sustituciones:
- WRITE_ENDPOINT: el nombre de DNS o el endpoint de escritura. Este valor alfanumérico
siempre termina con el sufijo
.global.sql-psa.goog.. - DATABASE_NAME: el nombre de la base de datos. Por ejemplo,
my-database. - USERNAME: nombre de usuario. Por ejemplo,
postgres. - PASSWORD: la contraseña de la base de datos.
Python
engine = sqlalchemy.create_engine( "postgresql+pg8000://", creator=lambda: connector.connect( "WRITE_ENDPOINT", # using DNS name "pg8000", user="USERNAME", password="PASSWORD", db="DATABASE_NAME" ), )
Haz las siguientes sustituciones:
- WRITE_ENDPOINT: el nombre de DNS o el endpoint de escritura. Este valor alfanumérico
siempre termina con el sufijo
.global.sql-psa.goog.. - DATABASE_NAME: el nombre de la base de datos. Por ejemplo,
my-database. - USERNAME: nombre de usuario. Por ejemplo,
postgres. - PASSWORD: la contraseña de la base de datos.
Node.js
import pg from 'pg'; import {Connector} from '@google-cloud/cloud-sql-connector'; const {Pool} = pg; const connector = new Connector(); const clientOpts = await connector.getOptions({ domainName: 'WRITE_ENDPOINT', ipType: 'PUBLIC', }); const pool = new Pool({ ...clientOpts, user: 'USERNAME', password: 'PASSWORD', database: 'DATABASE_NAME', max: 5, });
Haz las siguientes sustituciones:
- WRITE_ENDPOINT: el nombre de DNS o el endpoint de escritura. Este valor alfanumérico
siempre termina con el sufijo
.global.sql-psa.goog.. - DATABASE_NAME: el nombre de la base de datos. Por ejemplo,
my-database. - USERNAME: nombre de usuario. Por ejemplo,
postgres. - PASSWORD: la contraseña de la base de datos.
Limitaciones
- Los endpoints de escritura no están disponibles para las creaciones de instancias de la edición Enterprise de Cloud SQL.
- Los endpoints de escritura no están disponibles para las instancias que solo tienen IP pública o las que solo tienen Private Service Connect.
Solución de problemas
En las siguientes secciones se describe la arquitectura de los endpoints de escritura y se abordan los problemas habituales.
Arquitectura de un endpoint de escritura
Cuando creas una instancia apta, se genera un endpoint de escritura de forma predeterminada.
Para crear un endpoint de escritura, Cloud SQL realiza la siguiente configuración:
- Crea una zona DNS privada en la red de VPC del productor del servicio Cloud SQL.
- Crea una zona DNS de emparejamiento en la red de VPC del cliente.
- Crea un registro DNS en la zona DNS privada de la red del productor de servicios.
En el siguiente diagrama se muestra cómo funciona este proceso:
Problemas de resolución de DNS
Si la resolución de DNS no funciona, comprueba cada uno de los siguientes elementos:
- Asegúrate de que se cumplen todos los requisitos previos.
- Asegúrate de que los clientes en los que se espera la resolución estén ubicados en la misma red a la que está conectada la instancia de Cloud SQL. Para comprobarlo, usa el comando
gcloud compute instances list:gcloud compute instances list \ --format="table( name, zone.basename(), networkInterfaces[].network )" \ --project=PROJECT_NAME
Sustituye PROJECT_NAME por el nombre del proyecto en el que se encuentra la red de consumidor de DNS.
- Verifica que la zona de emparejamiento exista. Para ello, usa el comando
gcloud dns managed-zones list:gcloud dns managed-zones list \ --project=PROJECT_NAME
Sustituye PROJECT_NAME por el nombre del proyecto en el que se encuentra la red de consumidor de DNS.
- Si la zona de emparejamiento no existe, puedes solucionar el problema con el comando
gcloud beta sql instances patch:gcloud beta sql instances patch INSTANCE_NAME --reconcile-psa-networking
Sustituye INSTANCE_NAME por el nombre de tu instancia de Cloud SQL.
La nueva instancia no tiene un endpoint de escritura
Si una instancia recién creada no contiene un endpoint de escritura, comprueba cada uno de los siguientes elementos:
- Asegúrate de que se cumplen todos los requisitos.
- Asegúrate de que no haya ninguna zona de DNS de emparejamiento con el nombre de DNS
sql-psa.goog..Una zona DNS de emparejamiento es una zona DNS residual si la red asociada a la zona DNS no tiene un emparejamiento de VPC con el ID de proyecto de la zona DNS de emparejamiento.
Si queda una zona DNS de emparejamiento con el sufijo
sql-psa.goog., elimínala.Para comprobar si quedan zonas DNS de emparejamiento, usa el comando
gcloud dns managed-zones list:gcloud dns managed-zones list \ --project=PROJECT_NAME
Sustituye PROJECT_NAME por el nombre del proyecto en el que se encuentra la red de consumidor de DNS.
Si existe una zona DNS con el sufijo
sql-psa.goog., elimínala después de comprobar que la zona DNS de emparejamiento es una zona DNS residual.Para eliminar una zona DNS, usa el comando
gcloud dns managed-zones delete:gcloud dns managed-zones delete ZONE_NAME
Sustituye ZONE_NAME por el nombre de la zona DNS asociada a los endpoints de escritura. Los valores son alfanuméricos y tienen el siguiente formato:
cloud-sql-psa-dns-1234567890. - Para corregir un endpoint de escritura que falta en una instancia apta, usa el comando
gcloud beta sql instances patch:gcloud beta sql instances patch INSTANCE_NAME --reconcile-psa-networking
Sustituye INSTANCE_NAME por el nombre de tu instancia de Cloud SQL.