| 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_PLUS",
"availability_type": "REGIONAL",
"tags": [{"environment": "prod"}]
}
|
| execute_sql |
Ejecutar cualquier instrucción de SQL válida, incluidas las instrucciones 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.
- 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. 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 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 que accedió 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
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.
|
| 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 o CLOUD_IAM_SERVICE_ACCOUNT.
- 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 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:
- No puedes crear un usuario integrado con una contraseña.
- 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 se debe crear 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 revocan TODOS los roles existentes que no son 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.
|
| list_users |
Enumera todos los usuarios de la base de datos de una instancia de Cloud SQL.
|
| 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.
|
