Google utiliza tecnología de IA para traducir contenido a tu idioma preferido. Las traducciones realizadas con IA pueden contener errores.

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 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.

Antes de comenzar

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

Configura el usuario de la base de datos

La API de Data debe autenticarse como usuario de la base de datos para ejecutar instrucciones SQL.

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

Crea una cuenta de usuario con una contraseña no vacía. También puedes usar el usuario predeterminado sqlserver.
Otorga a la cuenta los roles o privilegios necesarios para ejecutar instrucciones SQL. Si el usuario no es sqlserver, otórgale el rol db_owner.
Usa Secret Manager para crear un secreto regional y almacenar la contraseña. Por motivos de seguridad, la API de Data 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 instancia de Cloud SQL. No se admiten los secretos creados con el extremo global de Secret Manager, incluso si se almacenan en la misma región.
Otorga acceso de roles/secretmanager.secretAccessor a la API de Data. Como práctica recomendada, define condiciones de IAM para permitir que un usuario acceda a un secreto específico, pero no a otros secretos del proyecto.

Roles o permisos obligatorios

Las cuentas de servicio o de usuario que se usan para llamar a la API de Data deben tener permiso para ejecutar instrucciones SQL, cloudsql.instances.executesql. El permiso se incluye en una de las siguientes funciones predefinidas:

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.

Cuando se usa un secreto de Secret Manager para la autenticación, el usuario o la cuenta de servicio también deben tener permiso para acceder al secreto, secretmanager.versions.access. El permiso se incluye en uno de los siguientes roles predefinidos:

Secret Manager Secret Accessor (roles/secretmanager.secretAccessor)
Secret Manager Admin (roles/secretmanager.admin)

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.

Console

En la consola de Google Cloud , 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 Redes.
Selecciona la casilla de verificación Permitir Data API.
Haz clic en Guardar.

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=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 Data.

REST

Para habilitar el acceso a la API de datos en una instancia, envía una solicitud PATCH al extremo instances.patch:

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

El cuerpo de la solicitud debe contener el campo dataApiAccess establecido en ALLOW_DATA_API:

{
  "dataApiAccess": "ALLOW_DATA_API"
}

Para inhabilitar el acceso a la API de Data, establece dataApiAccess en DISALLOW_DATA_API.

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.

Autenticación con contraseña

Puedes ejecutar instrucciones SQL con la autenticación por contraseña integrada cuando la contraseña se almacena como un secreto regional con Secret Manager en la misma región que la instancia de Cloud SQL.

gcloud

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

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:

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.
USER: Es el usuario de la base de datos con el que se realizará la autenticación.
PASSWORD_SECRET_VERSION: Es 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}.
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.

Terraform

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

resource "google_sql_user" "built_in_user" {
  name     = "tf-user"
  host     = "%"  # Don't set this field for PostgreSQL and SQL Server.
  instance = google_sql_database_instance.instance.name
  password = "changeme"
  type     = "BUILT_IN"
}

# Create a regional secret. Global secrets are not supported even if
# located in one region only.
resource "google_secret_manager_regional_secret" "secret" {
  secret_id = "db-password"

  # Use the same region as the Cloud SQL instance.
  location = "us-central1"
}

resource "google_secret_manager_regional_secret_version" "secret_version" {
  secret = google_secret_manager_regional_secret.secret.id
  secret_data = "changeme"
}

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 TABLE IF NOT EXISTS table1 ( col VARCHAR(16) NOT NULL );"

  instance = google_sql_database_instance.instance.name
  database = google_sql_database.database.name
  description = "sql script to create tables"
  user = google_sql_user.built_in_user.name

  # The location should be the same as the Cloud SQL instance's location.
  password_secret_version = "projects/my-project/locations/us-central1/secrets/db-password/versions/latest"

  # The built-in database user and password secret version must be created
  # first. Cloud SQL will retrieve password from Secret Manager
  # and connect to this user account to execute your script.
  depends_on = [
    google_sql_user.built_in_user,
    google_secret_manager_regional_secret_version.secret_version
  ]
}

Aplique los cambios

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

Prepara Cloud Shell

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

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 proyecto Google Cloud para ver los resultados. En la consola de Google Cloud , 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 borrarlas, puedes agregar explícitamente instrucciones 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 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",
  "user": "USER",
  "passwordSecretVersion": "PASSWORD_SECRET_VERSION",
  "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á.
USER: Es el usuario de la base de datos con el que se realizará la autenticación.
PASSWORD_SECRET_VERSION: Es 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}.
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 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. Para ello, incluye el campo "partialResultMode" en la solicitud. Este campo acepta los siguientes valores:

FAIL_PARTIAL_RESULT: Predeterminado. 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.
PARTIAL_RESULT_MODE_UNSPECIFIED: Modo no especificado, que es igual a FAIL_PARTIAL_RESULT.

Audita las búsquedas

Puedes hacer un seguimiento del nombre de la aplicación configurando el campo applicationName en la solicitud. La base de datos hará un seguimiento del nombre de la aplicación en las estadísticas de sesión, por ejemplo, en la tabla sys.dm_exec_sessions.

Puedes usar Estadísticas de consultas para hacer un seguimiento de más información sobre tus consultas y analizar los problemas de rendimiento.

También puedes usar la auditoría de bases de datos de SQL Server para registrar consultas con fines de seguridad o cumplimiento.

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 SQL Server 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 LOCK_TIMEOUT.
Cloud SQL limita la cantidad de solicitudes executeSql simultáneas por instancia para evitar la sobrecarga. Si se alcanza el límite, las solicitudes posteriores fallarán y mostrarán uno de los siguientes errores:
- At most 'x' concurrent queries may be run on this instance. Try again later.
- Maximum concurrent reads 'x' reached.
El límite (x) es de 5 consultas para las instancias con menos de 10 GB de memoria total y de 10 consultas para las instancias con al menos 10 GB de memoria total.
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.
La API de Data no puede autenticarse como usuarios integrados con contraseñas vacías.
La API de Data se puede bloquear temporalmente por motivos de integridad de los datos cuando se realizan ciertas operaciones de mantenimiento en la instancia. Si esto sucede, vuelve a intentarlo más tarde.

No se admite el comando GO. Este comando se usa en las utilidades de Microsoft SQL Server para indicar que un lote de declaraciones finalizó y se puede enviar a SQL Server.
Si una consulta incluye una columna binaria, la API de Data no puede mostrarla. Convierte los valores binarios en una cadena.

Por ejemplo, reemplaza:
```
SELECT my_binary_column from my_table2;
```
con:
```
SELECT CONVERT(NVARCHAR(4000), my_binary_column, 1) from my_table2;
```
Cuando se ejecutan varias consultas y una de ellas falla, se muestra el primer error encontrado. Es posible que algunas de las declaraciones del lote antes del error se hayan ejecutado de forma correcta. Puedes unir varias consultas en una declaración transaction para evitar este problema:
```
BEGIN TRANSACTION
    YOUR_SQL_STATEMENTS
COMMIT;
```
Reemplaza lo siguiente:
- YOUR_SQL_STATEMENTS: son las declaraciones que deseas ejecutar como parte de esta consulta.

Es posible que la secuencia de comandos SQL y su respuesta de ejecución transiten 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 aplicado manualmente.

Solucionar problemas

En esta sección, se incluye información sobre los problemas asociados con el uso de la API de Data, junto con los pasos para solucionarlos.

Problema	Soluciona problemas
`The instance doesn't allow using ExecuteSql to access this instance. You can allow it by patching the instance with {settings: { dataApiAccess: "ALLOW_DATA_API" }}`	La API de Data está inhabilitada de forma predeterminada. Habilita la API de Data en la instancia para resolver el problema.
`Secret cannot be provided when auto_iam_authn is true.`	Cuando configuras `auto_iam_authn` como `true`, te autenticas en la base de datos con IAM. Este método de autenticación no requiere una contraseña ni un secreto. Consulta Autenticación con IAM.
`ExecuteSql API is not supported for instances in certain Assured Workloads control packages folders yet.`	Es posible que la secuencia de comandos SQL y su respuesta de ejecución transiten por ubicaciones intermedias entre tu cliente y la ubicación de la instancia de destino. Por este motivo, las solicitudes fallarán para las instancias en ciertos proyectos de Assured Workloads. Si tu proyecto no está inscrito en Assured Workloads, pero `constraints/sql.restrictNoncompliantResourceCreation` se aplica manualmente, pídele al administrador de tu organización que quite la restricción y el problema se resolverá en las instancias creadas recientemente.
`The server principal USERNAME is not able to access the database DATABASE_NAME under the current security context.`	El usuario no es miembro de la base de datos. Conéctate a la base de datos como el usuario `sqlserver` y agrega el usuario nuevo. Luego, otórgale al usuario nuevo el rol `db_owner` para la base de datos. Por ejemplo: EXEC sp_adduser 'user'; EXEC sp_addrolemember 'db_owner', 'user'
`The database is currently unavailable.`	Es posible que la instancia se esté reiniciando, esté en mantenimiento o se encuentre en un estado no saludable. Verifica el estado de la instancia y vuelve a intentarlo más tarde.

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 obligatorios

Habilita o inhabilita la API de Data

Console

gcloud

REST

Ejecuta una instrucción de SQL

Autenticación con contraseña

gcloud

Terraform

Aplique los cambios

Prepara Cloud Shell

Prepara el directorio

Aplica los cambios

Borra los cambios

REST

Cómo modificar el comportamiento del truncamiento

Audita las búsquedas

Limitaciones

Solucionar problemas

Ejecuta instrucciones de SQL con la API de Cloud SQL Data