Descripción general
En esta página, se muestra cómo usar un extremo de escritura para conectarte desde clientes de 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 en la dirección IP de la instancia principal actual de forma automática. En el caso de una operación de conmutación por error o cambio de réplica, este extremo de escritura redirecciona las conexiones entrantes a la nueva instancia principal automáticamente. 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 de la región o el simulacro de recuperación ante desastres.
Cada instancia elegible de Cloud SQL tiene un único extremo de escritura integrado cuyo nombre, creación y actualización administra Cloud SQL. En el siguiente ejemplo, se ilustra su formato:
primary.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, actualizaciones, eliminaciones y 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 ascender una instancia de réplica a 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 proyecto de Google Cloud 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 del DNS de intercambio de tráfico, lo que hará que los nombres de DNS no se puedan usar.
Una vez que se haya creado correctamente la zona del DNS de intercambio de tráfico, 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 edición Cloud SQL Enterprise Plus.
- 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 instancias nuevas se crean con la arquitectura nueva. Para verificar esto, comprueba la arquitectura de red de tu instancia.
Cuando actualizas una instancia existente de Cloud SQL edición Enterprise a una instancia de Cloud SQL edición Enterprise Plus, Cloud SQL genera automáticamente el extremo de escritura si se cumplen los requisitos previos mencionados antes. Si tu instancia existente está en la arquitectura de red anterior, primero debes actualizarla 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 writeEndpoint
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.,
como en el siguiente ejemplo:
primary.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
sqlcmd
Para conectar un cliente de sqlcmd a una instancia de Cloud SQL con el extremo de escritura,
ejecuta el siguiente comando:
sqlcmd -S WRITE_ENDPOINT -U USERNAME -d DATABASE_NAME
Realiza los siguientes reemplazos:
- DATABASE_NAME: Es el nombre de la base de datos. Por ejemplo,
main. - USERNAME: el nombre de usuario Por ejemplo,
sqlserver - 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,primary.103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog..
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 de forma periódica si hay una operación de conmutación 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 primary.103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog.
Al principio, la zona del 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 de 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
primary.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 provocar que fallen las consultas de la base 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 30 de junio de 2026, 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 necesitas ejecutar esta tarea de actualización una vez por cada instancia. Ejecuta el comando siguiente:
gcloud CLI
# 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.
sqlcmd
$ cloud-sql-proxy --port PORT WRITE_ENDPOINT --private-ip
Luego, configura el cliente de la base de datos para que se conecte al proxy de autenticación de Cloud SQL:
sqlcmd -S 127.0.0.1, PORT -U USERNAME \ -d 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,primary.103uufa2svq8u.2rb3qdj9tkf4d.global.sql-psa.goog.. - PORT: Es el número de puerto que se usa. Por ejemplo,
1433 - USERNAME: el nombre de usuario Por ejemplo,
sqlserver-user - DATABASE_NAME: Es el nombre de la base de datos. Por ejemplo,
sqlserver-database.
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 de Conexión con 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:sqlserver://WRITE_ENDPOINT:1433;" "databaseName=DATABASE_NAME;" + "socketFactoryClass=com.google.cloud.sql.sqlserver.SocketFactory;" + "socketFactoryConstructorArg=WRITE_ENDPOINT?ipTypes=PRIVATE;" + "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,
sqlserver-user - PASSWORD: Es la contraseña de la base de datos.
Go
db, err := sql.Open( "cloudsql-sqlserver", "sqlserver://USERNAME:PASSWORD@WRITE_ENDPOINT?database=DATABASE_NAME&encrypt=disable", )
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,
sqlserver-user - PASSWORD: Es la contraseña de la base de datos.
Python
Connector = Connector(resolver=DnsResolver) engine = sqlalchemy.create_engine( "mssql+pytds://", creator=lambda: connector.connect( "WRITE_ENDPOINT", # using DNS name "pytds", 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,
sqlserver-user - PASSWORD: Es la contraseña de la base de datos.
Node.js
import sql from 'mssql'; import {Connector} from '@google-cloud/cloud-sql-connector'; const connector = new Connector(); const clientOpts = await connector.getTediousOptions({ domainName: 'WRITE_ENDPOINT', ipType: 'PRIVATE', }); const pool = new sql.ConnectionPool({ ...clientOpts, user: 'USERNAME', password: 'PASSWORD', database: 'DATABASE_NAME', pool: { max: 5, } }); Await pool.connect();
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,
sqlserver-user - PASSWORD: Es la contraseña de la base de datos.
Limitaciones
- Los extremos de escritura no están disponibles para las creaciones de instancias de Cloud SQL edición Enterprise.
- Los extremos de escritura no están disponibles para las instancias solo de IP pública o solo de 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 del DNS privada en la red de VPC del productor de Cloud SQL de servicio.
- Crea una zona del DNS de intercambio de tráfico en la red de VPC del cliente.
- Crea un registro DNS en la zona del DNS privado 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á conectada la instancia de Cloud SQL. Para verificarlo, 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 de consumidor de DNS.
- Verifica que exista la zona de intercambio de tráfico. Para hacerlo, 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 de consumidor de DNS.
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 del DNS de intercambio de tráfico restante con el nombre de DNS
sql-psa.goog..Una zona del DNS de intercambio de tráfico es una zona del DNS restante si la red asociada con la zona del DNS no tiene un intercambio de tráfico de VPC con el ID del proyecto de intercambio de tráfico de la zona del DNS de intercambio de tráfico.
Si hay una zona del DNS de intercambio de tráfico restante con el sufijo
sql-psa.goog., bórrala.Para verificar si hay zonas del DNS de intercambio de tráfico restantes, 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 de consumidor de DNS.
Si existe una zona del DNS con el sufijo
sql-psa.goog., bórrala después de verificar que la zona del DNS de intercambio de tráfico sea una zona del DNS restante.Para borrar una zona del 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 del DNS asociado 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 sql instances patch:gcloud 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 sobre la solución de problemas de Cloud SQL.