Method: instances.executeSql

Execute SQL statements.

HTTP request

POST https://sqladmin.googleapis.com/sql/v1beta4/projects/{project}/instances/{instance}/executeSql

The URL uses gRPC Transcoding 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 ExecuteSqlPayload.

Response body

Execute SQL statements response.

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

JSON representation 
{
  "messages": [
    {
      object (Message)
    }
  ],
  "metadata": {
    object (Metadata)
  },
  "results": [
    {
      object (QueryResult)
    }
  ],
  "status": {
    object (Status)
  }
}
Fields
messages[]

object (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 (Metadata)

The additional metadata information regarding the execution of the SQL statements.
results[]

object (QueryResult)

The list of results after executing all the SQL statements.
status

object (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/cloud-platform
  • https://www.googleapis.com/auth/sqlservice.admin

For more information, see the Authentication Overview.

ExecuteSqlPayload

The request payload used to execute SQL statements.

JSON representation 
{
  "user": string,
  "sqlStatement": string,
  "database": string,
  "rowLimit": string,
  "partialResultMode": enum (PartialResultMode),
  "application": string,

  // Union field user_password can be only one of the following:
  "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 (int64 format)

Optional. The maximum number of rows returned per SQL statement.
partialResultMode

enum (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:
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 (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 (Column)
    }
  ],
  "rows": [
    {
      object (Row)
    }
  ],
  "message": string,
  "partialResult": boolean,
  "status": {
    object (Status)
  }
}
Fields
columns[]

object (Column)

instances.list of columns included in the result. This also includes the data type of the column.
rows[]

object (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 (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 (Value)
    }
  ]
}
Fields
values[]

object (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 represented in string format.
nullValue

boolean

If cell value is null, then this flag will be set to true.