Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Ejecuta instrucciones de SQL con la API de Cloud SQL Data

MySQL | PostgreSQL | SQL Server

En esta página, se describe cómo ejecutar instrucciones de SQL en bases de datos en instancias de Cloud SQL con la API de datos. Con la API de datos, usas la API de Cloud SQL Admin y la CLI de gcloud para ejecutar instrucciones de SQL en cualquier instancia en la que hayas habilitado el acceso a la API de datos.

Puedes usar la API de datos con instancias que usan direcciones IP públicas, acceso privado a servicios o Private Service Connect. La API de datos admite todos los tipos de instrucciones de SQL, incluidos el lenguaje de manipulación de datos (DML), el lenguaje de definición de datos (DDL) y el lenguaje de consulta de datos (DQL). La API de datos es adecuada para ejecutar instrucciones administrativas pequeñas y rápidas, como crear roles o usuarios de bases de datos y realizar pequeñas actualizaciones de esquemas.

Antes de comenzar

Antes de ejecutar instrucciones de SQL en una instancia, sigue estos pasos.

Configura el usuario de la base de datos

La API de datos debe autenticarse como un usuario de la base de datos para ejecutar instrucciones de SQL. Puedes autenticarte como un usuario integrado, un usuario de IAM, una cuenta de servicio de IAM o un grupo de IAM.

Para autenticarte con IAM, haz lo siguiente:

Configura la instancia para la autenticación de bases de datos de IAM.
Agrega un usuario, una cuenta de servicio o un grupo de IAM a la instancia.
Otorga a la cuenta los roles o privilegios necesarios para ejecutar instrucciones de SQL. Puedes asignar roles de base de datos mientras creas la cuenta o actualizas la cuenta. Si creaste roles de base de datos personalizados con privilegios mínimos, asígnalos a la cuenta. De lo contrario, asigna el rol cloudsqlsuperuser predefinido a la cuenta, usa la API de datos para crear roles de base de datos personalizados nuevos con menos privilegios y, luego, otorga los roles nuevos a la cuenta en lugar de cloudsqlsuperuser.

Para autenticarte como un usuario integrado con contraseña, haz lo siguiente:

Crea un usuario. Ten en cuenta que la API de datos no puede autenticarse como el usuario predeterminado root.
Usa Secret Manager para crear un secreto regional para almacenar la contraseña. Por motivos de seguridad, la API de datos solicita el nombre del recurso del secreto en lugar de la contraseña en la solicitud a la API. El secreto regional debe almacenarse en la misma región que tu Cloud SQL instance. No se admiten los secretos creados con el extremo global de Secret Manager, incluso si se almacenan en la misma región.
define condiciones opcionales de IAM para permitir que un usuario acceda a un secreto específico, pero no a otros secretos del proyecto.

Roles o permisos requeridos

De forma predeterminada, las cuentas de servicio o usuario con uno de los siguientes roles tienen permiso para ejecutar instrucciones de SQL en una instancia de Cloud SQL (cloudsql.instances.executesql):

Cloud SQL Admin (roles/cloudsql.admin)
Cloud SQL Instance User (roles/cloudsql.instanceUser)
Cloud SQL Studio User (roles/cloudsql.studioUser)

También puedes definir un rol personalizado de IAM para la cuenta de servicio o usuario que incluya el cloudsql.instances.executesql permiso. Este permiso es compatible con los roles personalizados de IAM.

Habilita o inhabilita la API de datos

Para usar la API de datos, debes habilitarla para cada instancia. Puedes inhabilitar la API de datos en cualquier momento.

Console

En la Google Cloud consola de, ve a la página Instancias de Cloud SQL.

Ir a Instancias de Cloud SQL
Para abrir la página de Descripción general de una instancia, haz clic en su nombre.
En el menú de navegación de SQL, selecciona Conexiones.
Haz clic en la pestaña Herramientas de redes.
Selecciona la casilla de verificación Permitir la API de datos.
Haz clic en Guardar.

gcloud

Para habilitar el acceso a la API de datos en una instancia, usa el gcloud sql instances patch comando con la --data-api-access=ALLOW_DATA_API marca:

gcloud sql instances patch INSTANCE_NAME --data-api-access=ALLOW_DATA_API

Para inhabilitar el acceso a la API de datos, usa la marca --data-api-access=DISALLOW_DATA_API:

gcloud sql instances patch INSTANCE_NAME --data-api-access=DISALLOW_DATA_API

Reemplaza INSTANCE_NAME por el nombre de la instancia en la que se habilitará o inhabilitará la API de datos.

Ejecuta una instrucción de SQL

Puedes ejecutar instrucciones de SQL en bases de datos en tu instancia de Cloud SQL con gcloud CLI o la API de REST.

gcloud

Para ejecutar una instrucción de SQL en una base de datos en una instancia con la gcloud CLI, usa el comando gcloud sql instances execute-sql.

Para conectarte con IAM, haz lo siguiente:

gcloud sql instances execute-sql INSTANCE_NAME \
--database=DATABASE_NAME \
--sql=SQL_STATEMENT \
--partial-result-mode=PARTIAL_RESULT_MODE

Realiza los siguientes reemplazos:

INSTANCE_NAME: El nombre de la instancia.
DATABASE_NAME: El nombre de la base de datos dentro de la instancia.
SQL_STATEMENT: La instrucción de SQL que se ejecutará. Si la instrucción contiene espacios o caracteres especiales de shell, debe estar entre comillas.
PARTIAL_RESULT_MODE: Es opcional. Controla cómo responder cuando el resultado está incompleto. Puede ser ALLOW_PARTIAL_RESULT, FAIL_PARTIAL_RESULT o PARTIAL_RESULT_MODE_UNSPECIFIED. Consulta Modifica el comportamiento de truncamiento.

También puedes incluir la marca --project=PROJECT_ID si es necesario.

Para conectarte como un usuario integrado con contraseña, haz lo siguiente:

gcloud sql instances execute-sql INSTANCE_NAME \
--database=DATABASE_NAME \
--sql=SQL_STATEMENT \
--user=USER \
--password-secret-version=PASSWORD_SECRET_VERSION \
--partial-result-mode=PARTIAL_RESULT_MODE

Realiza los siguientes reemplazos:

USER: El usuario de la base de datos para autenticarse. Omite el @ y el nombre de host.
PASSWORD_SECRET_VERSION: El nombre del recurso del secreto de Secret Manager que contiene la contraseña del usuario de la base de datos. El secreto debe ser un secreto regional y almacenarse en la misma región que la instancia de Cloud SQL. El formato esperado del nombre del recurso es projects/{project}/locations/{location}/secrets/{secret}/versions/{secret_version}.

Terraform

Puedes usar la API de datos en Terraform para aprovisionar recursos en la base de datos, como bases de datos, tablas, extensiones, usuarios y otorgamientos de privilegios, sin conectarte de forma manual a la instancia. Para ejecutar una secuencia de comandos de SQL en Terraform, usa el google_sql_provision_script recurso de Terraform.

resource "google_sql_database_instance" "instance" {
  name             = "my-instance"
  database_version = "MYSQL_8_4"

  settings {
    tier            = "db-perf-optimized-N-2"
    data_api_access = "ALLOW_DATA_API"  # This allows the use of Data API.
    database_flags {
      name  = "cloudsql_iam_authentication"
      value = "on"
    }
  }
}

/*
 * Create a database user for your account and grant roles so it has privilege
 * to access the database. Set the type to CLOUD_IAM_USER for huamn
 * account or CLOUD_IAM_SERVICE_ACCOUNT for service account.
 */
resource "google_sql_user" "iam_user" {
  name     = "account-used-to-apply-this-config@example.com"
  instance = google_sql_database_instance.instance.name
  type     = "CLOUD_IAM_USER"

  # Roles granted to the user. To follow the principle of least privilege, you
  can first use `google_sql_provision_script` to create custom database role(s)
  with lesser privileges and then assign them to this user in place of
  `cloudsqlsuperuser`.
  # This field doesn't support MySQL 5.6 and 5.7.
  database_roles = ["cloudsqlsuperuser"]
}

resource "google_sql_provision_script" "script" {
  # You can inline the script or import from a file like script  = file("${path.module}/script.sql")
  # When modified, the whole script will be executed again. It's recommended to
  # make the script idempotent with patterns like create if not exists ... or
  # if not exists (select ...) then ... end if.
  script = "CREATE DATABASE pets;"
  instance = google_sql_database_instance.instance.name

  # Some of your queries may require a database. You can create and use a
  # database in the script or explicitly create and reference a database
  # like database = google_sql_database.database.name.

  description = "sql script to create DBs"

  # The identity account used to apply your Terraform config must exist as an
  # IAM user or IAM service account in the instance. Terraform connects to the
  # instance via IAM database authentication to execute the script.
  depends_on = [google_sql_user.iam_user]
}

Aplica los cambios

Para aplicar tu configuración de Terraform en un Google Cloud proyecto, completa los pasos de las siguientes secciones.

Prepara Cloud Shell

Inicia Cloud Shell.
Establece el proyecto predeterminado en el que deseas aplicar tus configuraciones de Terraform. Google Cloud

Solo necesitas ejecutar este comando una vez por proyecto y puedes ejecutarlo en cualquier directorio.
```
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
```
Las variables de entorno se anulan si configuras valores explícitos en el archivo de configuración de Terraform.

Prepara el directorio

Cada archivo de configuración de Terraform debe tener su propio directorio (también llamado módulo raíz).

En Cloud Shell, crea un directorio y un archivo nuevo dentro de ese directorio. El nombre del archivo debe tener la extensión .tf, por ejemplo, main.tf. En este instructivo, el archivo se denomina main.tf.
```
mkdir DIRECTORY && cd DIRECTORY && touch main.tf
```
Si sigues un instructivo, puedes copiar el código de muestra en cada sección o paso.

Copia el código de muestra en el main.tf recién creado.

De manera opcional, copia el código de GitHub. Esto se recomienda cuando el fragmento de Terraform es parte de una solución de extremo a extremo.
Revisa y modifica los parámetros de muestra que se aplicarán a tu entorno.
Guarda los cambios.
Inicializa Terraform. Solo debes hacerlo una vez por directorio.
```
terraform init
```
De manera opcional, incluye la opción -upgrade para usar la última versión del proveedor de Google:
```
terraform init -upgrade
```

Aplica los cambios

Revisa la configuración y verifica que los recursos que creará o actualizará Terraform coincidan con tus expectativas:
```
terraform plan
```
Corrige la configuración según sea necesario.
Para aplicar la configuración de Terraform, ejecuta el siguiente comando y, luego, escribe yes cuando se te solicite:
```
terraform apply
```
Espera hasta que Terraform muestre el mensaje “¡Aplicación completa!”.
Abre tu Google Cloud proyecto para ver los resultados. En la Google Cloud consola de, navega a tus recursos en la IU para asegurarte de que Terraform los haya creado o actualizado.

Borra los cambios

Borrar un recurso google_sql_provision_script no borrará los recursos en la base de datos que creó. Para borrarlos, puedes agregar instrucciones de forma explícita en la secuencia de comandos, como drop ... if exists y, luego, aplicar los cambios.

REST

Para ejecutar una instrucción de SQL en una base de datos en una instancia con la API de REST, envía una solicitud POST al extremo executeSql:

POST https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME/executeSql

El cuerpo de la solicitud debe contener el nombre de la base de datos y la instrucción de SQL:

{
  "database": "DATABASE_NAME",
  "sqlStatement": "SQL_STATEMENT",
  "partialResultMode": "PARTIAL_RESULT_MODE"
  "autoIamAuthn": true
}

Realiza los siguientes reemplazos:

PROJECT_ID: ID del proyecto
INSTANCE_NAME: El nombre de la instancia.
DATABASE_NAME: El nombre de la base de datos dentro de la instancia.
SQL_STATEMENT: La instrucción de SQL que se ejecutará.
PARTIAL_RESULT_MODE: Es opcional. Controla cómo responde la API cuando el resultado supera los 10 MB. Puede ser FAIL_PARTIAL_RESULT, ALLOW_PARTIAL_RESULT o PARTIAL_RESULT_MODE_UNSPECIFIED. Consulta Modifica el comportamiento de truncamiento.

Modifica el comportamiento de truncamiento

Puedes controlar cómo se manejan los resultados grandes cuando se ejecuta SQL. Para ello, incluye el "partialResultMode" campo en la solicitud. Este campo acepta los siguientes valores:

FAIL_PARTIAL_RESULT: Predeterminado. Muestra un error si el resultado supera los 10 MB o si solo se puede recuperar un resultado parcial. No muestra el resultado.
ALLOW_PARTIAL_RESULT: Muestra un resultado truncado y establece partial_result como verdadero si el resultado supera los 10 MB o si solo se puede recuperar un resultado parcial debido a un error. No muestra un error.
PARTIAL_RESULT_MODE_UNSPECIFIED: Modo no especificado, que es igual a FAIL_PARTIAL_RESULT.

Limitaciones

El límite de tamaño para una respuesta es de 10 MB. Los resultados que superen este tamaño se truncarán si partialResultMode se establece en ALLOW_PARTIAL_RESULT. De lo contrario, se mostrará un error.
Las solicitudes se limitan a 0.5 MB.
Solo puedes ejecutar instrucciones de SQL para las instancias de Cloud SQL para MySQL que se estén ejecutando.
Cloud SQL no admite el uso de la API de datos con instancias configuradas para la replicación de servidores externos.
Las solicitudes que tarden más de 30 segundos se cancelan. No se admite establecer un tiempo de espera de instrucción más alto con SET SESSION MAX_EXECUTION_TIME. En el caso de Cloud SQL para MySQL 5.6 y 5.7, el tiempo de espera de las declaraciones DDL de larga duración puede causar archivos o tablas huérfanos que no se pueden revertir de forma segura. Ten cuidado con las instrucciones como ALTER TABLE en tablas grandes.
Cloud SQL limita la cantidad de solicitudes executeSql simultáneas a 10 por instancia para cada usuario. Si se alcanza este límite, las solicitudes posteriores fallarán con el mensaje "Se pueden ejecutar como máximo 10 consultas simultáneas en esta instancia. Vuelve a intentarlo más tarde" o "Se alcanzó el máximo de lecturas simultáneas: 10".
Cada respuesta puede contener un máximo de 10 mensajes o advertencias de la base de datos.
Si hay un error de sintaxis o de ejecución de la instrucción, no se muestra ningún resultado.
En el caso de Cloud SQL para MySQL, los avisos y las advertencias solo están disponibles para la última instrucción de una ejecución de varias instrucciones.
Las instrucciones que consumen una gran cantidad de memoria pueden causar errores de falta de memoria. Para obtener más información sobre cómo evitar estos errores, consulta Prácticas recomendadas para administrar el uso de memoria. Una instancia de base de datos que se ejecuta con una utilización de memoria alta suele causar problemas de rendimiento, atascos o, incluso, tiempo de inactividad de la base de datos.
La API de datos se puede bloquear temporalmente por motivos de integridad de los datos cuando se realizan ciertas operaciones de mantenimiento en la instancia. Vuelve a intentarlo más tarde si sucede.
La secuencia de comandos de SQL y su respuesta de ejecución pueden transitar por ubicaciones intermedias entre tu cliente y la ubicación de la instancia de destino. Por este motivo, las solicitudes fallarán con el error "no admitido para instancias en ciertas carpetas de paquetes de control de Assured Workloads" para ciertos proyectos de Assured Workloads y para proyectos con constraints/sql.restrictNoncompliantResourceCreation aplicados de forma manual.

Ejecuta instrucciones de SQL con la API de Cloud SQL Data Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Antes de comenzar

Configura el usuario de la base de datos

Roles o permisos requeridos

Habilita o inhabilita la API de datos

Console

gcloud

Ejecuta una instrucción de SQL

gcloud

Terraform

Aplica los cambios

Prepara Cloud Shell

Prepara el directorio

Aplica los cambios

Borra los cambios

REST

Modifica el comportamiento de truncamiento

Limitaciones

Ejecuta instrucciones de SQL con la API de Cloud SQL Data