Ejecuta instrucciones de SQL con la API de Cloud SQL Data

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

Puedes usar la API de Data con instancias que usan direcciones IP públicas, acceso privado a servicios o Private Service Connect. La API de Data admite todos los tipos de sentencias 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 Data es útil para ejecutar sentencias administrativas pequeñas y rápidas, como crear roles o usuarios de bases de datos y realizar pequeñas actualizaciones de esquemas. También puedes usar la API de Data para habilitar extensiones de PostgreSQL.

Antes de comenzar

Antes de ejecutar instrucciones de SQL en una instancia, haz lo siguiente:

Roles o permisos obligatorios

De forma predeterminada, las cuentas de servicio o usuario con uno de los siguientes roles tienen permiso para ejecutar instrucciones 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 permiso cloudsql.instances.executesql. Este permiso es compatible con los roles personalizados de IAM.

Habilita o inhabilita la API de Data

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

gcloud

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

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=DENY_DATA_API:

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

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

Ejecuta una instrucción de SQL

Puedes ejecutar instrucciones SQL en las bases de datos de 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 de una instancia con gcloud CLI, usa el comando gcloud beta sql instances execute-sql:

gcloud beta 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: Es el nombre de la base de datos dentro de la instancia.
  • SQL_STATEMENT: Es 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 Cómo modificar el comportamiento de truncamiento.

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

REST

Para ejecutar una instrucción de SQL en una base de datos de 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"
}

Realiza los siguientes reemplazos:

  • PROJECT_ID: el ID de tu proyecto
  • INSTANCE_NAME: El nombre de la instancia.
  • DATABASE_NAME: Es el nombre de la base de datos dentro de la instancia.
  • SQL_STATEMENT: Es 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 o ALLOW_PARTIAL_RESULT. Consulta Cómo modificar el comportamiento de truncamiento.

Cómo modificar el comportamiento del truncamiento

Puedes controlar cómo se manejan los resultados grandes cuando se ejecuta SQL.

  • Incluye el campo "partialResultMode" en la solicitud. Este campo acepta los siguientes valores:
    • FAIL_PARTIAL_RESULT: Genera un error si el resultado supera los 10 MB o si solo se puede recuperar un resultado parcial. No devuelve el resultado.
    • ALLOW_PARTIAL_RESULT: Devuelve 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 arroja un error.

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 generará un error.
  • Las solicitudes tienen un límite de 0.5 MB.
  • Solo puedes ejecutar sentencias SQL para las instancias de Cloud SQL para PostgreSQL que se estén ejecutando.
  • Cloud SQL no admite el uso de la API de Data con instancias configuradas para la replicación de servidores externos.
  • Las solicitudes que tarden más de 30 segundos se cancelarán. No se admite establecer un tiempo de espera de la instrucción más alto con SET STATEMENT_TIMEOUT.
  • 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 alcanzó el límite máximo de 10 lecturas simultáneas".
  • 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 devuelve ningún resultado.
  • Las instrucciones que consumen una gran cantidad de memoria pueden provocar errores de memoria insuficiente. 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.