ExecuteStatementCommand

Runs a SQL statement against a database.

If a call isn't part of a transaction because it doesn't include the transactionID parameter, changes that result from the call are committed automatically.

If the binary response data from the database is more than 1 MB, the call is terminated.

Example Syntax

Use a bare-bones client and the command you need to make an API call.

import { RDSDataClient, ExecuteStatementCommand } from "@aws-sdk/client-rds-data"; // ES Modules import
// const { RDSDataClient, ExecuteStatementCommand } = require("@aws-sdk/client-rds-data"); // CommonJS import
const client = new RDSDataClient(config);
const input = { // ExecuteStatementRequest
  resourceArn: "STRING_VALUE", // required
  secretArn: "STRING_VALUE", // required
  sql: "STRING_VALUE", // required
  database: "STRING_VALUE",
  schema: "STRING_VALUE",
  parameters: [ // SqlParametersList
    { // SqlParameter
      name: "STRING_VALUE",
      value: { // Field Union: only one key present
        isNull: true || false,
        booleanValue: true || false,
        longValue: Number("long"),
        doubleValue: Number("double"),
        stringValue: "STRING_VALUE",
        blobValue: new Uint8Array(), // e.g. Buffer.from("") or new TextEncoder().encode("")
        arrayValue: { // ArrayValue Union: only one key present
          booleanValues: [ // BooleanArray
            true || false,
          ],
          longValues: [ // LongArray
            Number("long"),
          ],
          doubleValues: [ // DoubleArray
            Number("double"),
          ],
          stringValues: [ // StringArray
            "STRING_VALUE",
          ],
          arrayValues: [ // ArrayOfArray
            {//  Union: only one key present
              booleanValues: [
                true || false,
              ],
              longValues: [
                Number("long"),
              ],
              doubleValues: [
                Number("double"),
              ],
              stringValues: [
                "STRING_VALUE",
              ],
              arrayValues: [
                "<ArrayValue>",
              ],
            },
          ],
        },
      },
      typeHint: "STRING_VALUE",
    },
  ],
  transactionId: "STRING_VALUE",
  includeResultMetadata: true || false,
  continueAfterTimeout: true || false,
  resultSetOptions: { // ResultSetOptions
    decimalReturnType: "STRING_VALUE",
    longReturnType: "STRING_VALUE",
  },
  formatRecordsAs: "STRING_VALUE",
};
const command = new ExecuteStatementCommand(input);
const response = await client.send(command);
// { // ExecuteStatementResponse
//   records: [ // SqlRecords
//     [ // FieldList
//       { // Field Union: only one key present
//         isNull: true || false,
//         booleanValue: true || false,
//         longValue: Number("long"),
//         doubleValue: Number("double"),
//         stringValue: "STRING_VALUE",
//         blobValue: new Uint8Array(),
//         arrayValue: { // ArrayValue Union: only one key present
//           booleanValues: [ // BooleanArray
//             true || false,
//           ],
//           longValues: [ // LongArray
//             Number("long"),
//           ],
//           doubleValues: [ // DoubleArray
//             Number("double"),
//           ],
//           stringValues: [ // StringArray
//             "STRING_VALUE",
//           ],
//           arrayValues: [ // ArrayOfArray
//             {//  Union: only one key present
//               booleanValues: [
//                 true || false,
//               ],
//               longValues: [
//                 Number("long"),
//               ],
//               doubleValues: [
//                 Number("double"),
//               ],
//               stringValues: [
//                 "STRING_VALUE",
//               ],
//               arrayValues: [
//                 "<ArrayValue>",
//               ],
//             },
//           ],
//         },
//       },
//     ],
//   ],
//   columnMetadata: [ // Metadata
//     { // ColumnMetadata
//       name: "STRING_VALUE",
//       type: Number("int"),
//       typeName: "STRING_VALUE",
//       label: "STRING_VALUE",
//       schemaName: "STRING_VALUE",
//       tableName: "STRING_VALUE",
//       isAutoIncrement: true || false,
//       isSigned: true || false,
//       isCurrency: true || false,
//       isCaseSensitive: true || false,
//       nullable: Number("int"),
//       precision: Number("int"),
//       scale: Number("int"),
//       arrayBaseColumnType: Number("int"),
//     },
//   ],
//   numberOfRecordsUpdated: Number("long"),
//   generatedFields: [
//     {//  Union: only one key present
//       isNull: true || false,
//       booleanValue: true || false,
//       longValue: Number("long"),
//       doubleValue: Number("double"),
//       stringValue: "STRING_VALUE",
//       blobValue: new Uint8Array(),
//       arrayValue: "<ArrayValue>",
//     },
//   ],
//   formattedRecords: "STRING_VALUE",
// };

ExecuteStatementCommand Input

See ExecuteStatementCommandInput for more details

Parameter
Type
Description
resourceArn
Required
string | undefined

The Amazon Resource Name (ARN) of the Aurora Serverless DB cluster.

secretArn
Required
string | undefined

The ARN of the secret that enables access to the DB cluster. Enter the database user name and password for the credentials in the secret.

For information about creating the secret, see Create a database secret .

sql
Required
string | undefined

The SQL statement to run.

continueAfterTimeout
boolean | undefined

A value that indicates whether to continue running the statement after the call times out. By default, the statement stops running when the call times out.

For DDL statements, we recommend continuing to run the statement after the call times out. When a DDL statement terminates before it is finished running, it can result in errors and possibly corrupted data structures.

database
string | undefined

The name of the database.

formatRecordsAs
RecordsFormatType | undefined

A value that indicates whether to format the result set as a single JSON string. This parameter only applies to SELECT statements and is ignored for other types of statements. Allowed values are NONE and JSON. The default value is NONE. The result is returned in the formattedRecords field.

For usage information about the JSON format for result sets, see Using the Data API  in the Amazon Aurora User Guide.

includeResultMetadata
boolean | undefined

A value that indicates whether to include metadata in the results.

parameters
SqlParameter[] | undefined

The parameters for the SQL statement.

Array parameters are not supported.

resultSetOptions
ResultSetOptions | undefined

Options that control how the result set is returned.

schema
string | undefined

The name of the database schema.

Currently, the schema parameter isn't supported.

transactionId
string | undefined

The identifier of a transaction that was started by using the BeginTransaction operation. Specify the transaction ID of the transaction that you want to include the SQL statement in.

If the SQL statement is not part of a transaction, don't set this parameter.

ExecuteStatementCommand Output

Parameter
Type
Description
$metadata
Required
ResponseMetadata
Metadata pertaining to this request.
columnMetadata
ColumnMetadata[] | undefined

Metadata for the columns included in the results. This field is blank if the formatRecordsAs parameter is set to JSON.

formattedRecords
string | undefined

A string value that represents the result set of a SELECT statement in JSON format. This value is only present when the formatRecordsAs parameter is set to JSON.

The size limit for this field is currently 10 MB. If the JSON-formatted string representing the result set requires more than 10 MB, the call returns an error.

generatedFields
Field[] | undefined

Values for fields generated during a DML request.

The generatedFields data isn't supported by Aurora PostgreSQL. To get the values of generated fields, use the RETURNING clause. For more information, see Returning Data From Modified Rows  in the PostgreSQL documentation.

numberOfRecordsUpdated
number | undefined

The number of records updated by the request.

records
Field[][] | undefined

The records returned by the SQL statement. This field is blank if the formatRecordsAs parameter is set to JSON.

Throws

Name
Fault
Details
AccessDeniedException
client

You don't have sufficient access to perform this action.

BadRequestException
client

There is an error in the call or in a SQL statement. (This error only appears in calls from Aurora Serverless v1 databases.)

DatabaseErrorException
client

There was an error in processing the SQL statement.

DatabaseNotFoundException
client

The DB cluster doesn't have a DB instance.

DatabaseResumingException
client

A request was cancelled because the Aurora Serverless v2 DB instance was paused. The Data API request automatically resumes the DB instance. Wait a few seconds and try again.

DatabaseUnavailableException
server

The writer instance in the DB cluster isn't available.

ForbiddenException
client

There are insufficient privileges to make the call.

HttpEndpointNotEnabledException
client

The HTTP endpoint for using RDS Data API isn't enabled for the DB cluster.

InternalServerErrorException
server

An internal error occurred.

InvalidResourceStateException
client

The resource is in an invalid state.

InvalidSecretException
client

The Secrets Manager secret used with the request isn't valid.

SecretsErrorException
client

There was a problem with the Secrets Manager secret used with the request, caused by one of the following conditions:

  • RDS Data API timed out retrieving the secret.

  • The secret provided wasn't found.

  • The secret couldn't be decrypted.

ServiceUnavailableError
server

The service specified by the resourceArn parameter isn't available.

StatementTimeoutException
client

The execution of the SQL statement timed out.

TransactionNotFoundException
client

The transaction ID wasn't found.

UnsupportedResultException
client

There was a problem with the result because of one of the following conditions:

  • It contained an unsupported data type.

  • It contained a multidimensional array.

  • The size was too large.

RDSDataServiceException
Base exception class for all service exceptions from RDSData service.