- [HTTP request](https://docs.cloud.google.com/sql/docs/mysql/admin-api/rest/v1/instances/executeSql#body.HTTP_TEMPLATE)
- [Path parameters](https://docs.cloud.google.com/sql/docs/mysql/admin-api/rest/v1/instances/executeSql#body.PATH_PARAMETERS)
- [Request body](https://docs.cloud.google.com/sql/docs/mysql/admin-api/rest/v1/instances/executeSql#body.request_body)
- [Response body](https://docs.cloud.google.com/sql/docs/mysql/admin-api/rest/v1/instances/executeSql#body.response_body)
  - [JSON representation](https://docs.cloud.google.com/sql/docs/mysql/admin-api/rest/v1/instances/executeSql#body.SqlInstancesExecuteSqlResponse.SCHEMA_REPRESENTATION)
- [Authorization scopes](https://docs.cloud.google.com/sql/docs/mysql/admin-api/rest/v1/instances/executeSql#body.aspect)
- [ExecuteSqlPayload](https://docs.cloud.google.com/sql/docs/mysql/admin-api/rest/v1/instances/executeSql#ExecuteSqlPayload)
  - [JSON representation](https://docs.cloud.google.com/sql/docs/mysql/admin-api/rest/v1/instances/executeSql#ExecuteSqlPayload.SCHEMA_REPRESENTATION)
- [PartialResultMode](https://docs.cloud.google.com/sql/docs/mysql/admin-api/rest/v1/instances/executeSql#PartialResultMode)
- [Message](https://docs.cloud.google.com/sql/docs/mysql/admin-api/rest/v1/instances/executeSql#Message)
  - [JSON representation](https://docs.cloud.google.com/sql/docs/mysql/admin-api/rest/v1/instances/executeSql#Message.SCHEMA_REPRESENTATION)
- [Metadata](https://docs.cloud.google.com/sql/docs/mysql/admin-api/rest/v1/instances/executeSql#Metadata)
  - [JSON representation](https://docs.cloud.google.com/sql/docs/mysql/admin-api/rest/v1/instances/executeSql#Metadata.SCHEMA_REPRESENTATION)
- [QueryResult](https://docs.cloud.google.com/sql/docs/mysql/admin-api/rest/v1/instances/executeSql#QueryResult)
  - [JSON representation](https://docs.cloud.google.com/sql/docs/mysql/admin-api/rest/v1/instances/executeSql#QueryResult.SCHEMA_REPRESENTATION)
- [Column](https://docs.cloud.google.com/sql/docs/mysql/admin-api/rest/v1/instances/executeSql#Column)
  - [JSON representation](https://docs.cloud.google.com/sql/docs/mysql/admin-api/rest/v1/instances/executeSql#Column.SCHEMA_REPRESENTATION)
- [Row](https://docs.cloud.google.com/sql/docs/mysql/admin-api/rest/v1/instances/executeSql#Row)
  - [JSON representation](https://docs.cloud.google.com/sql/docs/mysql/admin-api/rest/v1/instances/executeSql#Row.SCHEMA_REPRESENTATION)
- [Value](https://docs.cloud.google.com/sql/docs/mysql/admin-api/rest/v1/instances/executeSql#Value)
  - [JSON representation](https://docs.cloud.google.com/sql/docs/mysql/admin-api/rest/v1/instances/executeSql#Value.SCHEMA_REPRESENTATION)
- [Examples](https://docs.cloud.google.com/sql/docs/mysql/admin-api/rest/v1/instances/executeSql#examples)
- [Try it!](https://docs.cloud.google.com/sql/docs/mysql/admin-api/rest/v1/instances/executeSql#try-it)

Execute SQL statements.

### HTTP request

`POST https://sqladmin.googleapis.com/v1/projects/{project}/instances/{instance}/executeSql`

The URL uses [gRPC Transcoding](https://google.aip.dev/127) syntax.

### Path parameters

| Parameters ||
|---|---|
| `project` | `string` Required. Project ID of the project that contains the instance. |
| `instance` | `string` Required. Database instance ID. This does not include the project ID. |

### Request body

The request body contains an instance of `https://docs.cloud.google.com/sql/docs/mysql/admin-api/rest/v1/instances/executeSql#ExecuteSqlPayload`.

### Response body

Execute SQL statements response.

If successful, the response body contains data with the following structure:

| JSON representation |
|---|
| ``` { "messages": [ { object (`https://docs.cloud.google.com/sql/docs/mysql/admin-api/rest/v1/instances/executeSql#Message`) } ], "metadata": { object (`https://docs.cloud.google.com/sql/docs/mysql/admin-api/rest/v1/instances/executeSql#Metadata`) }, "results": [ { object (`https://docs.cloud.google.com/sql/docs/mysql/admin-api/rest/v1/instances/executeSql#QueryResult`) } ], "status": { object (`https://docs.cloud.google.com/sql/docs/mysql/admin-api/rest/Shared.Types/Status`) } } ``` |

| Fields ||
|---|---|
| `messages[]` | ``object (`https://docs.cloud.google.com/sql/docs/mysql/admin-api/rest/v1/instances/executeSql#Message`)`` A list of notices and warnings generated during query execution. For PostgreSQL, this includes all notices and warnings. For MySQL, this includes warnings generated by the last executed statement. To retrieve all warnings for a multi-statement query, `SHOW WARNINGS` must be executed after each statement. |
| `metadata` | ``object (`https://docs.cloud.google.com/sql/docs/mysql/admin-api/rest/v1/instances/executeSql#Metadata`)`` The additional metadata information regarding the execution of the SQL statements. |
| `results[]` | ``object (`https://docs.cloud.google.com/sql/docs/mysql/admin-api/rest/v1/instances/executeSql#QueryResult`)`` The list of results after executing all the SQL statements. |
| `status` | ``object (`https://docs.cloud.google.com/sql/docs/mysql/admin-api/rest/Shared.Types/Status`)`` Contains the error from the database if the SQL execution failed. |

### Authorization scopes

Requires one of the following OAuth scopes:

- `https://www.googleapis.com/auth/cloudsql`
- `
  https://www.googleapis.com/auth/cloud-platform`
- `
  https://www.googleapis.com/auth/sqlservice.admin`

For more information, see the [Authentication Overview](https://docs.cloud.google.com/docs/authentication#authorization-gcp).

## ExecuteSqlPayload

The request payload used to execute SQL statements.

| JSON representation |
|---|
| ``` { "user": string, "sqlStatement": string, "database": string, "rowLimit": string, "partialResultMode": enum (`https://docs.cloud.google.com/sql/docs/mysql/admin-api/rest/v1/instances/executeSql#PartialResultMode`), "application": string, // Union field `user_password` can be only one of the following: "passwordSecretVersion": string, "autoIamAuthn": boolean // End of list of possible types for union field `user_password`. } ``` |

| Fields ||
|---|---|
| `user` | `string` Optional. The name of an existing database user to connect to the database. When `autoIamAuthn` is set to true, this field is ignored and the API caller's IAM user is used. |
| `sqlStatement` | `string` Required. SQL statements to run on the database. It can be a single statement or a sequence of statements separated by semicolons. |
| `database` | `string` Optional. Name of the database on which the statement will be executed. |
| `rowLimit` | `string (https://developers.google.com/discovery/v1/type-format format)` Optional. The maximum number of rows returned per SQL statement. |
| `partialResultMode` | ``enum (`https://docs.cloud.google.com/sql/docs/mysql/admin-api/rest/v1/instances/executeSql#PartialResultMode`)`` Optional. Controls how the API should respond when the SQL execution result is incomplete due to the size limit or another error. The default mode is to throw an error. |
| `application` | `string` Optional. Specifies the name of the application that is making the request. This field is used for telemetry. Only alphanumeric characters, dashes, and underscores are allowed. The maximum length is 32 characters. |
| Union field `user_password`. Credentials for the database connection. `user_password` can be only one of the following: ||
| `passwordSecretVersion` | `string` Optional. The resource name of the Secret Manager secret holding the password for the user to log into the database. The secret should be created using the regional endpoint (for API) or from the Regional Secrets page (for UI), and stored in the same region as the Cloud SQL instance. The expected resource name format is `projects/{project}/locations/{location}/secrets/{secret}/versions/{secret_version}`. Used together with the `user` field. The secret resource name will not be stored. |
| `autoIamAuthn` | `boolean` Optional. When set to `true`, the API caller identity associated with the request is used for database authentication. The API caller must be an IAM user in the database. |

## PartialResultMode

Controls how the API should respond when the SQL execution result exceeds 10 MB.

| Enums ||
|---|---|
| `PARTIAL_RESULT_MODE_UNSPECIFIED` | Unspecified mode, effectively the same as `FAIL_PARTIAL_RESULT`. |
| `FAIL_PARTIAL_RESULT` | Throw an error if the result exceeds 10 MB or if only a partial result can be retrieved. Don't return the result. |
| `ALLOW_PARTIAL_RESULT` | Return a truncated result and set `partialResult` to true if the result exceeds 10 MB or if only a partial result can be retrieved due to error. Don't throw an error. |

## Message

Represents a notice or warning message from the database.

| JSON representation |
|---|
| ``` { "message": string, "severity": string } ``` |

| Fields ||
|---|---|
| `message` | `string` The full message string. For PostgreSQL, this is a formatted string that may include severity, code, and the notice/warning message. For MySQL, this contains the warning message. |
| `severity` | `string` The severity of the message (e.g., "NOTICE" for PostgreSQL, "WARNING" for MySQL). |

## Metadata

The additional metadata information regarding the execution of the SQL statements.

| JSON representation |
|---|
| ``` { "sqlStatementExecutionTime": string } ``` |

| Fields ||
|---|---|
| `sqlStatementExecutionTime` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#duration` format)`` The time taken to execute the SQL statements. A duration in seconds with up to nine fractional digits, ending with '`s`'. Example: `"3.5s"`. |

## QueryResult

QueryResult contains the result of executing a single SQL statement.

| JSON representation |
|---|
| ``` { "columns": [ { object (`https://docs.cloud.google.com/sql/docs/mysql/admin-api/rest/v1/instances/executeSql#Column`) } ], "rows": [ { object (`https://docs.cloud.google.com/sql/docs/mysql/admin-api/rest/v1/instances/executeSql#Row`) } ], "message": string, "partialResult": boolean, "status": { object (`https://docs.cloud.google.com/sql/docs/mysql/admin-api/rest/Shared.Types/Status`) } } ``` |

| Fields ||
|---|---|
| `columns[]` | ``object (`https://docs.cloud.google.com/sql/docs/mysql/admin-api/rest/v1/instances/executeSql#Column`)`` instances.list of columns included in the result. This also includes the data type of the column. |
| `rows[]` | ``object (`https://docs.cloud.google.com/sql/docs/mysql/admin-api/rest/v1/instances/executeSql#Row`)`` Rows returned by the SQL statement. |
| `message` | `string` Message related to the SQL execution result. |
| `partialResult` | `boolean` Set to true if the SQL execution's result is truncated due to size limits or an error retrieving results. |
| `status` | ``object (`https://docs.cloud.google.com/sql/docs/mysql/admin-api/rest/Shared.Types/Status`)`` If results were truncated due to an error, details of that error. |

## Column

Contains the name and datatype of a column.

| JSON representation |
|---|
| ``` { "name": string, "type": string } ``` |

| Fields ||
|---|---|
| `name` | `string` Name of the column. |
| `type` | `string` Datatype of the column. |

## Row

Contains the values for a row.

| JSON representation |
|---|
| ``` { "values": [ { object (`https://docs.cloud.google.com/sql/docs/mysql/admin-api/rest/v1/instances/executeSql#Value`) } ] } ``` |

| Fields ||
|---|---|
| `values[]` | ``object (`https://docs.cloud.google.com/sql/docs/mysql/admin-api/rest/v1/instances/executeSql#Value`)`` The values for the row. |

## Value

The cell value of the table.

| JSON representation |
|---|
| ``` { "value": string, "nullValue": boolean } ``` |

| Fields ||
|---|---|
| `value` | `string` The cell value in string format. |
| `nullValue` | `boolean` If cell value is null, then this flag will be set to true. |