| list_instances |
Enumera todas las instancias de Cloud SQL en el proyecto.
|
| get_instance |
Obtén los detalles de una instancia de Cloud SQL.
|
| create_instance |
Inicia la creación de una instancia de Cloud SQL.
A menos que se especifique lo contrario, una instancia recién creada usa la configuración de instancia predeterminada de un entorno de desarrollo. A continuación, se muestra la configuración predeterminada para una instancia en un entorno de desarrollo:
{
"tier": "db-perf-optimized-N-2",
"data_disk_size_gb": 100,
"region": "us-central1",
"database_version": "POSTGRES_18",
"edition": "ENTERPRISE_PLUS",
"availability_type": "ZONAL",
"tags": [{"environment": "dev"}]
}
Se recomienda la siguiente configuración para una instancia en un entorno de producción:
{
"tier": "db-perf-optimized-N-8",
"data_disk_size_gb": 250,
"region": "us-central1",
"database_version": "POSTGRES_18",
"edition": "ENTERPRISE_PLUS",
"availability_type": "REGIONAL",
"tags": [{"environment": "prod"}]
}
Se recomienda la siguiente configuración de instancias para SQL Server:
{
"tier": "db-perf-optimized-N-8",
"data_disk_size_gb": 250,
"region": "us-central1",
"database_version": "SQLSERVER_2022_STANDARD",
"edition": "ENTERPRISE",
"availability_type": "REGIONAL",
"tags": [{"environment": "prod"}]
}
|
| execute_sql |
Ejecutar cualquier instrucción de SQL válida, incluidas las sentencias del lenguaje de definición de datos (DDL), el lenguaje de control de datos (DCL), el lenguaje de consulta de datos (DQL) o el lenguaje de manipulación de datos (DML) en una instancia de Cloud SQL. Para admitir la herramienta execute_sql, una instancia de Cloud SQL debe cumplir con los siguientes requisitos:
- El valor de
data_api_access debe establecerse en ALLOW_DATA_API.
- Para los usuarios integrados, se debe configurar password_secret_version.
- De lo contrario, para los usuarios de IAM, en una instancia de MySQL, la marca de base de datos
cloudsql_iam_authentication debe establecerse en on. En el caso de una instancia de PostgreSQL, la marca de base de datos cloudsql.iam_authentication debe establecerse en on.
- Después de usar la herramienta
create_instance para crear una instancia, puedes usar la herramienta create_user para crear una cuenta de usuario de IAM para el usuario que actualmente accedió al proyecto.
La herramienta execute_sql tiene las siguientes limitaciones:
- Si una instrucción de SQL devuelve una respuesta de más de 10 MB, la respuesta se truncará.
- La herramienta
execute_sql tiene un tiempo de espera predeterminado de 30 segundos. Si una consulta se ejecuta durante más de 30 segundos, la herramienta devuelve un error de DEADLINE_EXCEEDED.
- La herramienta
execute_sql no es compatible con SQL Server.
Si recibes errores similares a "La autenticación de IAM no está habilitada para la instancia", puedes usar la herramienta get_instance para verificar el valor de la marca de autenticación de la base de datos de IAM para la instancia. Si recibes errores como "La instancia no permite usar executeSql para acceder a esta instancia", puedes usar la herramienta get_instance para verificar el parámetro de configuración data_api_access. Cuando recibas errores de autenticación, haz lo siguiente:
- Verifica si la cuenta de usuario con la que se accedió actualmente existe como usuario de IAM en la instancia con la herramienta
list_users.
- Si la cuenta de usuario de IAM no existe, usa la herramienta
create_user para crearla para el usuario que accedió.
- Si el usuario conectado actualmente no tiene los roles de usuario de la base de datos adecuados, puedes usar la herramienta
update_user para otorgarle roles de base de datos. Por ejemplo, el rol cloudsqlsuperuser puede proporcionar a un usuario de IAM muchos permisos requeridos.
Verifica si el usuario que accedió actualmente tiene los permisos de IAM correctos asignados para el proyecto. Puedes usar el comando gcloud projects get-iam-policy [PROJECT_ID] para verificar si el usuario tiene los roles o permisos de IAM adecuados asignados para el proyecto.
- El usuario debe tener permiso de
cloudsql.instance.login para realizar la autenticación automática de la base de datos de IAM.
- El usuario debe tener permiso
cloudsql.instances.executeSql para ejecutar instrucciones SQL con la herramienta execute_sql o la API de executeSql.
- Roles de IAM comunes que contienen los permisos requeridos: Usuario de instancia de Cloud SQL (
roles/cloudsql.instanceUser) o Administrador de Cloud SQL (roles/cloudsql.admin)
Cuando recibas un ExecuteSqlResponse, siempre verifica los campos message y status dentro del cuerpo de la respuesta. Un código de estado HTTP correcto no garantiza el éxito total de todas las sentencias SQL. Los campos message y status indicarán si hubo errores o advertencias parciales durante la ejecución de la instrucción de SQL.
|
| execute_sql_readonly |
Ejecutar cualquier instrucción de SQL de solo lectura válida en una instancia de Cloud SQL Para admitir la herramienta execute_sql_readonly, una instancia de Cloud SQL debe cumplir con los siguientes requisitos:
- El valor de
data_api_access debe establecerse en ALLOW_DATA_API.
- En el caso de una instancia de MySQL, la marca de base de datos
cloudsql_iam_authentication debe establecerse en on. En el caso de una instancia de PostgreSQL, la marca de base de datos cloudsql.iam_authentication debe establecerse en on.
- Se requiere una cuenta de usuario o una cuenta de servicio de IAM (
CLOUD_IAM_USER o CLOUD_IAM_SERVICE_ACCOUNT) para llamar a la herramienta execute_sql_readonly. La herramienta ejecuta las sentencias SQL con los privilegios del usuario de la base de datos que accedió con la autenticación de la base de datos de IAM.
Después de usar la herramienta create_instance para crear una instancia, puedes usar la herramienta create_user para crear una cuenta de usuario de IAM para el usuario que actualmente accedió al proyecto. La herramienta execute_sql_readonly tiene las siguientes limitaciones:
- Si una instrucción de SQL devuelve una respuesta de más de 10 MB, la respuesta se truncará.
- La herramienta tiene un tiempo de espera predeterminado de 30 segundos. Si una consulta se ejecuta durante más de 30 segundos, la herramienta devuelve un error de
DEADLINE_EXCEEDED.
- La herramienta no es compatible con SQL Server.
Si recibes errores similares a "La autenticación de IAM no está habilitada para la instancia", puedes usar la herramienta get_instance para verificar el valor de la marca de autenticación de la base de datos de IAM para la instancia. Si recibes errores como "La instancia no permite usar executeSql para acceder a esta instancia", puedes usar la herramienta get_instance para verificar el parámetro de configuración data_api_access. Cuando recibas errores de autenticación, haz lo siguiente:
- Verifica si la cuenta de usuario con la que se accedió actualmente existe como usuario de IAM en la instancia con la herramienta
list_users.
- Si la cuenta de usuario de IAM no existe, usa la herramienta
create_user para crearla para el usuario que accedió.
- Si el usuario conectado actualmente no tiene los roles de usuario de la base de datos adecuados, puedes usar la herramienta
update_user para otorgarle roles de base de datos. Por ejemplo, el rol cloudsqlsuperuser puede proporcionar a un usuario de IAM muchos permisos requeridos.
Verifica si el usuario que accedió actualmente tiene los permisos de IAM correctos asignados para el proyecto. Puedes usar el comando gcloud projects get-iam-policy [PROJECT_ID] para verificar si el usuario tiene los roles o permisos de IAM adecuados asignados para el proyecto.
- El usuario debe tener permiso de
cloudsql.instance.login para realizar la autenticación automática de la base de datos de IAM.
- El usuario debe tener permiso
cloudsql.instances.executeSql para ejecutar instrucciones SQL con la herramienta execute_sql_readonly o la API de executeSql.
- Roles de IAM comunes que contienen los permisos requeridos: Usuario de instancia de Cloud SQL (
roles/cloudsql.instanceUser) o Administrador de Cloud SQL (roles/cloudsql.admin)
Cuando recibas un ExecuteSqlResponse, siempre verifica los campos message y status dentro del cuerpo de la respuesta. Un código de estado HTTP correcto no garantiza el éxito total de todas las sentencias SQL. Los campos message y status indicarán si hubo errores o advertencias parciales durante la ejecución de la instrucción de SQL.
|
| get_operation |
Obtiene el estado de una operación de larga duración. Una operación de larga duración puede tardar varios minutos en completarse. Si una operación tarda mucho tiempo, usa una herramienta de línea de comandos para pausarla durante 30 segundos antes de volver a verificar su estado.
|
| create_user |
Crea un usuario de base de datos para una instancia de Cloud SQL.
- Esta herramienta devuelve una operación de larga duración. Usa la herramienta
get_operation para sondear su estado hasta que se complete la operación.
- Cuando uses la herramienta
create_user, especifica el tipo de usuario: CLOUD_IAM_USER, CLOUD_IAM_SERVICE_ACCOUNT o BUILT_IN.
- De forma predeterminada, al usuario recién creado se le asigna el rol
cloudsqlsuperuser, a menos que especifiques otros roles de base de datos de forma explícita en la solicitud.
- Puedes usar un usuario recién creado con la herramienta
execute_sql si el usuario es un usuario de IAM que accedió actualmente. La herramienta execute_sql ejecuta las sentencias de SQL con los privilegios del usuario de la base de datos que accedió con la autenticación de la base de datos de IAM.
La herramienta create_user tiene las siguientes limitaciones:
- Para crear un usuario integrado con contraseña, usa el campo
password_secret_version para proporcionar la contraseña con Google Cloud Secret Manager. El valor de password_secret_version debe ser el nombre del recurso de la versión secreta, como projects/12345/locations/us-central1/secrets/my-password-secret/versions/1 o projects/12345/locations/us-central1/secrets/my-password-secret/versions/latest. El emisor debe tener el permiso secretmanager.secretVersions.access en la versión del secreto.
- La herramienta
create_user no admite la creación de un usuario para SQL Server.
Para crear un usuario de IAM en PostgreSQL, haz lo siguiente:
- El nombre de usuario de la base de datos debe ser la dirección de correo electrónico del usuario de IAM y estar en minúsculas. Por ejemplo, para crear un usuario para el usuario de IAM de PostgreSQL
example-user@example.com, puedes usar la siguiente solicitud:
{
"name": "example-user@example.com",
"type": "CLOUD_IAM_USER",
"instance":"test-instance",
"project": "test-project"
}
El nombre de usuario de la base de datos creado para el usuario de IAM es example-user@example.com. Para crear una cuenta de servicio de IAM en PostgreSQL, haz lo siguiente:
- El nombre de usuario de la base de datos debe crearse sin el sufijo
.gserviceaccount.com, aunque la dirección de correo electrónico completa de la cuenta seaservice-account-name@project-id.iam.gserviceaccount.com. Por ejemplo, para crear una cuenta de servicio de IAM para PostgreSQL, puedes usar el siguiente formato de solicitud:
{
"name": "test@test-project.iam",
"type": "CLOUD_IAM_SERVICE_ACCOUNT",
"instance": "test-instance",
"project": "test-project"
}
El nombre de usuario de la base de datos creado para la cuenta de servicio de IAM es test@test-project.iam. Para crear un usuario o una cuenta de servicio de IAM en MySQL, haz lo siguiente:
- Cuando Cloud SQL para MySQL almacena un nombre de usuario, trunca el signo @ y el nombre de dominio de la dirección de correo electrónico del usuario o la cuenta de servicio. Por ejemplo,
example-user@example.com se convierte en example-user.
- Por esta razón, no puedes agregar dos usuarios o cuentas de servicio de IAM con el mismo nombre de usuario, pero con nombres de dominio diferentes a la misma instancia de Cloud SQL.
- Por ejemplo, para crear un usuario para el usuario de IAM de MySQL
example-user@example.com, usa la siguiente solicitud:
{
"name": "example-user@example.com",
"type": "CLOUD_IAM_USER",
"instance": "test-instance",
"project": "test-project"
}
El nombre de usuario de la base de datos creado para el usuario de IAM es example-user.
- Por ejemplo, para crear la cuenta de servicio de IAM de MySQL
service-account-name@project-id.iam.gserviceaccount.com, usa la siguiente solicitud:
{
"name": "service-account-name@project-id.iam.gserviceaccount.com",
"type": "CLOUD_IAM_SERVICE_ACCOUNT",
"instance": "test-instance",
"project": "test-project"
}
El nombre de usuario de la base de datos creado para la cuenta de servicio de IAM es service-account-name.
|
| update_user |
Actualiza un usuario de base de datos para una instancia de Cloud SQL. Un caso de uso común para update_user es otorgarle a un usuario el rol de cloudsqlsuperuser, que puede proporcionarle muchos permisos obligatorios. Esta herramienta solo admite la actualización de usuarios para asignar roles de base de datos.
- Esta herramienta devuelve una operación de larga duración. Usa la herramienta
get_operation para sondear su estado hasta que se complete la operación.
- Antes de llamar a la herramienta
update_user, siempre verifica la configuración existente del usuario, como el tipo de usuario con la herramienta list_users.
- Como caso especial para MySQL, si la herramienta
list_users devuelve una dirección de correo electrónico completa para el campo iamEmail, por ejemplo, {name=test-account,
iamEmail=test-account@project-id.iam.gserviceaccount.com}, en tu solicitud update_user, usa la dirección de correo electrónico completa en el campo iamEmail del campo name de tu toolrequest. Por ejemplo, name=test-account@project-id.iam.gserviceaccount.com.
Parámetros clave para actualizar los roles de los usuarios:
database_roles: Es una lista de roles de base de datos que se asignarán al usuario.revokeExistingRoles: Es un campo booleano (el valor predeterminado es falso) que controla cómo se controlan los roles existentes. Cómo funcionan las actualizaciones de roles:
Si revokeExistingRoles es verdadero, haz lo siguiente:
- Se REVOCARÁN todos los roles existentes que se hayan otorgado al usuario, pero que NO estén en la lista de
database_roles proporcionada.
- La revocación solo se aplica a los roles que no son del sistema. No se revocarán los roles del sistema, como
cloudsqliamuser, etc.
- Se OTORGARÁN todos los roles de la lista
database_roles que el usuario NO tenga.
- Si
database_roles está vacío, se revocarán TODOS los roles existentes que no sean del sistema.
Si revokeExistingRoles es falso (predeterminado):
- Se OTORGARÁN todos los roles de la lista
database_roles que el usuario NO tenga.
- Los roles existentes que NO están en la lista
database_roles se CONSERVAN.
- Si
database_roles está vacío, no se realizan cambios en los roles del usuario.
Ejemplos:
|
| clone_instance |
Crea una instancia de Cloud SQL como un clon de una instancia de origen.
- Esta herramienta devuelve una operación de larga duración. Usa la herramienta
get_operation para sondear su estado hasta que se complete la operación.
- La operación de clonación puede tardar varios minutos. Usa una herramienta de línea de comandos para pausar la verificación del estado durante 30 segundos.
|
| update_instance |
Actualiza de forma parcial la configuración de una instancia de Cloud SQL.
- Esta herramienta devuelve una operación de larga duración. Usa la herramienta
get_operation para sondear su estado hasta que se complete la operación.
- Algunas operaciones de actualización, como cambiar la actualización de la edición o el nivel de la instancia, etc., pueden hacer que la instancia se reinicie, lo que genera tiempo de inactividad. Antes de continuar con esas operaciones, obtén la confirmación del usuario.
|
| list_users |
Enumera todos los usuarios de la base de datos de una instancia de Cloud SQL.
|
| create_backup |
Crea una copia de seguridad en una instancia de Cloud SQL. Siempre completa los campos de proyecto y de instancia en la solicitud. También se pueden proporcionar de forma opcional la ubicación (región) y la descripción de la copia de seguridad, en cuyo caso también se deben completar los campos de solicitud correspondientes.
|
| restore_backup |
Restablece una copia de seguridad en una instancia de Cloud SQL. Se deben proporcionar y completar target_instance y target_project en la solicitud. El identificador de copia de seguridad se puede proporcionar de varias maneras:
- Un backup_run_id (que es un número entero)
- Es un URI de copia de seguridad con el formato
projects/{project-id}/backups/{backup-uid}.
- Es un URI de copia de seguridad con el formato
projects/{project-id}/locations/{location}/backupVaults/{backupvault}/dataSources/{datasource}/backups/{backup-uid}.
Usa el identificador para completar el campo backup_id en la solicitud. El campo source_project debe completarse en la solicitud. Si el identificador es un backup_run_id, se proporcionará el source_project. Si el identificador es un URI de copia de seguridad, es posible que deba extraerse el source_project del URI. No confundas el source_project extraído con el target_project, que se proporcionará de otras maneras. Además, si el identificador es un backup_run_id, se debe proporcionar y completar el source_instance en la solicitud. No intentes crear la instancia antes de la restauración. La restauración creará la instancia si es necesario. Confirma los parámetros con el usuario antes de ejecutar la restauración.
|
| import_data |
Importa datos a una instancia de Cloud SQL. Si el archivo no comienza con gs://, se supone que está almacenado de forma local. Si el archivo es local, debes subirlo a Cloud Storage antes de realizar la llamada import_data real. Para subir el archivo a Cloud Storage, puedes usar los comandos gcloud o gsutil. Antes de subir el archivo a Cloud Storage, considera si quieres usar un bucket existente o crear uno nuevo en el proyecto proporcionado. Después de que se sube el archivo a Cloud Storage, la cuenta de servicio de la instancia debe tener permisos suficientes para leer el archivo subido desde el bucket de Cloud Storage. Esto se puede lograr de la siguiente manera:
- Usa la herramienta
get_instance para obtener la dirección de correo electrónico de la cuenta de servicio de la instancia. En el resultado de la herramienta, obtén el valor del campo serviceAccountEmailAddress.
- Otorga a la cuenta de servicio de la instancia el rol de
storage.objectAdmin en el bucket de Cloud Storage proporcionado. Usa un comando como gcloud storage buckets
add-iam-policy-binding o una solicitud a la API de Cloud Storage. La propagación de los permisos a la cuenta de servicio en Cloud Storage y el otorgamiento del rol pueden tardar entre dos y siete minutos, o incluso más. Si encuentras un error de permisos después de actualizar la política de IAM, espera unos minutos y vuelve a intentarlo.
Una vez que se otorguen los permisos, podrás importar los datos. Te recomendamos que dejes los parámetros opcionales vacíos y uses los valores predeterminados del sistema. Por lo general, el tipo de archivo se puede determinar por la extensión del archivo. Por ejemplo, si el archivo es un archivo SQL, .sql o .csv para un archivo CSV. A continuación, se muestra un ejemplo de importContext de SQL para MySQL.
{
"uri": "gs://sample-gcs-bucket/sample-file.sql",
"kind": "sql#importContext",
"fileType": "SQL"
}
No hay ningún parámetro database presente para MySQL, ya que se espera que el nombre de la base de datos esté presente en el archivo SQL. Especifica solo un URI. No se requieren otros campos fuera de importContext. En el caso de PostgreSQL, el campo database es obligatorio. A continuación, se muestra un ejemplo de importContext de PostgreSQL con el campo database especificado.
{
"uri": "gs://sample-gcs-bucket/sample-file.sql",
"kind": "sql#importContext",
"fileType": "SQL",
"database": "sample-db"
}
La herramienta import_data devuelve una operación de larga duración. Usa la herramienta get_operation para sondear su estado hasta que se complete la operación.
|
| postgres_upgrade_precheck |
Verifica si una instancia de Cloud SQL para PostgreSQL está lista para una actualización de versión principal a la versión de destino especificada. Se DEBE proporcionar el target_database_version en la solicitud (p.ej., POSTGRES_15). Esta herramienta ayuda a identificar posibles problemas antes de intentar la actualización real, lo que reduce el riesgo de fallas o tiempo de inactividad. Esta herramienta solo es compatible con las instancias principales de PostgreSQL y no se ejecuta en las réplicas de lectura. Por lo general, la verificación previa evalúa lo siguiente:
- Compatibilidad del esquema de la base de datos con la versión de destino
- Limitaciones de Cloud SQL y funciones no compatibles
- Restricciones de recursos de la instancia (p. ej., cantidad de relaciones)
- Compatibilidad de la configuración y las extensiones de la base de datos actual
- Estado general y disponibilidad de la instancia
Esta herramienta devuelve una operación de larga duración. Usa la herramienta get_operation con el nombre de la operación que muestra esta llamada para sondear su estado. IMPORTANTE: Una vez que el estado de la operación sea DONE, los resultados detallados de la verificación previa estarán disponibles en el recurso Operation. Deberás inspeccionar la respuesta de get_operation. Los hallazgos se encuentran en el campo pre_check_major_version_upgrade_context.pre_check_response. Los hallazgos están estructurados y señalan lo siguiente:
- INFO: Información general.
- ADVERTENCIA: Problemas potenciales que no bloquean la actualización, pero que se deben revisar.
- ERROR: Problemas críticos que SE DEBEN resolver antes de intentar la actualización.
Cada hallazgo debe incluir un mensaje y las acciones requeridas. Es fundamental abordar los problemas informados antes de continuar con la actualización de la versión principal. Si pre_check_response está vacío o falta, indica que no se identificaron problemas durante la verificación previa. La ejecución de esta verificación previa no afecta la disponibilidad de la instancia.
|
