Descripción general
En esta página, se muestra cómo usar un extremo de escritura para conectarte desde clientes en tu red de nube privada virtual (VPC) a una instancia de Cloud SQL con el acceso privado a servicios (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 caso de una réplica conmutación por error o cambio operación, 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 desastres o la simulación 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 de DDL. También puedes usar el extremo de escritura para operaciones de lectura, como 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 para que sea la nueva instancia principal.
Genera el extremo de escritura
Si creas una instancia de Cloud SQL nueva, Cloud SQL crea automáticamente el extremo de escritura cuando se cumplen los siguientes requisitos previos:
- Las siguientes APIs deben estar habilitadas
en el Google Cloud proyecto en el que reside tu instancia de Cloud SQL:
Si no se habilita la API de Cloud DNS en el proyecto, no se podrá crear la zona de DNS de intercambio, lo que hará que los nombres de DNS no se puedan usar.
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 no se pueda usar para la conexión de 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 estar configurada 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 instancias nuevas se crean con la nueva arquitectura. Para verificar esto, revisa la arquitectura de red de tu instancia.
Cuando actualizas una instancia existente de Cloud SQL Enterprise a una instancia de Cloud SQL Enterprise Plus, Cloud SQL genera automáticamente el extremo de escritura si se cumplen los requisitos previos enumerados 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., similar al siguiente ejemplo:
103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog.
Si no ves el extremo de escritura para una instancia apta, consulta Soluciona problemas.
Conéctate a una instancia de Cloud SQL con un extremo de escritura
psql
Para conectar un cliente psql a una instancia de Cloud SQL con el extremo de escritura,
ejecuta el siguiente comando:
psql -U DATABASE_NAME -h WRITE_ENDPOINT
Realiza los siguientes reemplazos:
- DATABASE_NAME: el nombre de la base de datos. Por ejemplo,
postgres. - WRITE_ENDPOINT: el nombre de DNS o el extremo de escritura. Este valor alfanumérico
siempre termina con el
.global.sql-psa.goog.sufijo. Por ejemplo,103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog..
Conecta clientes de bases de datos con instancias de bases de datos mediante el extremo de escritura a través de una conexión SSL/TLS
psql
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:
psql "sslmode=SSL_MODE \ sslrootcert=SSL_ROOT_SERVER \ sslcert=SSL_CERT \ sslkey=SSL_KEY \ host=WRITE_ENDPOINT \ port=PORT user=USERNAME \ dbname=DATABASE_NAME"
Realiza los siguientes reemplazos:
- SSL_MODE: el modo SSL que se usa. Por ejemplo,
verify-full. - SSL_ROOT_SERVER: el nombre del servidor raíz de 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 extremo de escritura. Este valor alfanumérico
siempre termina con el
.global.sql-psa.goog.sufijo. Por ejemplo,103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog.. - PORT: el número de puerto que se usa. Por ejemplo,
5432. - USERNAME: el nombre de usuario Por ejemplo,
postgres. - DATABASE_NAME: el nombre de la base de datos. Por ejemplo,
postgres.
Conecta clientes de bases de datos a instancias con 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 con un nombre de DNS de extremo de escritura, el conector de Cloud SQL verifica periódicamente si hay una operación de cambio o conmutación por error. Cuando el conector de Cloud SQL detecta que el nombre de 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.
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 de 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 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 cualquier grupo de conexiones que use la aplicación a establecer conexiones nuevas. También puede hacer 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 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.
psql
$ cloud-sql-proxy --port PORT WRITE_ENDPOINT
Luego, 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
Realiza los siguientes reemplazos:
- WRITE_ENDPOINT: el nombre de DNS o el extremo de escritura. Este valor alfanumérico
siempre termina con el
.global.sql-psa.goog.sufijo. Por ejemplo,103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog.. - PORT: el número de puerto que se usa. Por ejemplo,
5432. - USERNAME: el nombre de usuario Por ejemplo,
postgres. - DATABASE_NAME: el nombre de la base de datos. Por ejemplo,
postgres.
Conéctate con los 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 Conéctate 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:postgresql://WRITE_ENDPOINT/DATABASE_NAME?" + "&socketFactory=com.google.cloud.sql.postgres.SocketFactory" + "&user=USERNAME" + "&password=PASSWORD";
Realiza los siguientes reemplazos:
- WRITE_ENDPOINT: el nombre de DNS o el extremo de escritura. Este valor alfanumérico
siempre termina con el
.global.sql-psa.goog.sufijo. - DATABASE_NAME: el nombre de la base de datos. Por ejemplo,
my-database. - USERNAME: el 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", )
Realiza los siguientes reemplazos:
- WRITE_ENDPOINT: el nombre de DNS o el extremo de escritura. Este valor alfanumérico
siempre termina con el
.global.sql-psa.goog.sufijo. - DATABASE_NAME: el nombre de la base de datos. Por ejemplo,
my-database. - USERNAME: el 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" ), )
Realiza los siguientes reemplazos:
- WRITE_ENDPOINT: el nombre de DNS o el extremo de escritura. Este valor alfanumérico
siempre termina con el
.global.sql-psa.goog.sufijo. - DATABASE_NAME: el nombre de la base de datos. Por ejemplo,
my-database. - USERNAME: el 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, });
Realiza los siguientes reemplazos:
- WRITE_ENDPOINT: el nombre de DNS o el extremo de escritura. Este valor alfanumérico
siempre termina con el
.global.sql-psa.goog.sufijo. - DATABASE_NAME: el nombre de la base de datos. Por ejemplo,
my-database. - USERNAME: el nombre de usuario Por ejemplo,
postgres. - PASSWORD: la contraseña de la base de datos.
Limitaciones
- Los extremos de escritura no están disponibles para las creaciones de instancias de la edición 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 los 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 en la red de VPC del cliente.
- Crea un registro DNS en la zona de DNS privada en la red del productor de servicios.
En el siguiente diagrama, se ilustra cómo funciona este proceso:
Problemas con la resolución de DNS
Si la resolución de DNS no funciona, verifica cada uno de los siguientes elementos:
- Asegúrate de que se cumplan todos los requisitos previos.
- Asegúrate de que los clientes en los que se espera la resolución se encuentren en
la misma red a la que está adjunta la instancia de Cloud SQL. Para verificar
esto, usa el
gcloud compute instances listcomando: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 reside.
- Verifica que exista la zona de intercambio. Para ello, usa el
gcloud dns managed-zones listcomando: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 la zona de intercambio no existe, puedes solucionar el problema con el
gcloud sql instances patchcomando:gcloud 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:
- Asegúrate de que se completen todos los requisitos previos.
- Asegúrate de que no haya una zona de DNS de intercambio restante con el nombre de DNS
sql-psa.goog..Una zona de DNS de intercambio es una zona de DNS restante si la red asociada con la zona de DNS no tiene un intercambio de tráfico de VPC con el ID del proyecto de intercambio de la zona de DNS de intercambio.
Si hay una zona de DNS de intercambio restante con el
sql-psa.goog.sufijo, bórrala.Para verificar si hay zonas de DNS de intercambio restantes, usa el
gcloud dns managed-zones listcomando: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 de DNS con el sufijo
sql-psa.goog., bórrala después de verificar que la zona de DNS de intercambio sea una zona de DNS restante.Para borrar una zona de 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 de DNS asociada con los extremos de escritura. Los valores son alfanuméricos y usan el siguiente formato:
cloud-sql-psa-dns-1234567890. - Puedes corregir un extremo de escritura faltante 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.