feat(client-rds-data): Support to receive SQL query results in the form of a simplified JSON string. This enables developers using the new JSON string format to more easily convert it to an object using popular JSON string parsing libraries.

Author: awstools

clients/client-rds-data/README.md

@@ -12,8 +12,9 @@ AWS SDK for JavaScript RDSData Client for Node.js, Browser and React Native.
 <p>Amazon RDS provides an HTTP endpoint to run SQL statements on an Amazon Aurora
 Serverless DB cluster. To run these statements, you work with the Data Service
 API.</p>
-<p>For more information about the Data Service API, see <a href="https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/data-api.html">Using the Data API for Aurora
-Serverless</a> in the <i>Amazon Aurora User Guide</i>.</p>
+<p>For more information about the Data Service API, see
+<a href="https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/data-api.html">Using the Data API</a>
+in the <i>Amazon Aurora User Guide</i>.</p>
 
 ## Installing
 

clients/client-rds-data/src/RDSData.ts

@@ -33,8 +33,9 @@ import { RDSDataClient } from "./RDSDataClient";
  *         <p>Amazon RDS provides an HTTP endpoint to run SQL statements on an Amazon Aurora
  *             Serverless DB cluster. To run these statements, you work with the Data Service
  *             API.</p>
- *         <p>For more information about the Data Service API, see <a href="https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/data-api.html">Using the Data API for Aurora
- *                 Serverless</a> in the <i>Amazon Aurora User Guide</i>.</p>
+ *         <p>For more information about the Data Service API, see
+ *           <a href="https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/data-api.html">Using the Data API</a>
+ *           in the <i>Amazon Aurora User Guide</i>.</p>
  */
 export class RDSData extends RDSDataClient {
   /**
@@ -192,7 +193,7 @@ export class RDSData extends RDSDataClient {
    *                     <code>transactionID</code> parameter, changes that result from the call are
    *                 committed automatically.</p>
    *         </important>
-   *         <p>The response size limit is 1 MB. If the call returns more than 1 MB of response data, the call is terminated.</p>
+   *         <p>If the binary response data from the database is more than 1 MB, the call is terminated.</p>
    */
   public executeStatement(
     args: ExecuteStatementCommandInput,

clients/client-rds-data/src/RDSDataClient.ts

@@ -239,8 +239,9 @@ export interface RDSDataClientResolvedConfig extends RDSDataClientResolvedConfig
  *         <p>Amazon RDS provides an HTTP endpoint to run SQL statements on an Amazon Aurora
  *             Serverless DB cluster. To run these statements, you work with the Data Service
  *             API.</p>
- *         <p>For more information about the Data Service API, see <a href="https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/data-api.html">Using the Data API for Aurora
- *                 Serverless</a> in the <i>Amazon Aurora User Guide</i>.</p>
+ *         <p>For more information about the Data Service API, see
+ *           <a href="https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/data-api.html">Using the Data API</a>
+ *           in the <i>Amazon Aurora User Guide</i>.</p>
  */
 export class RDSDataClient extends __Client<
   __HttpHandlerOptions,

clients/client-rds-data/src/commands/ExecuteStatementCommand.ts

@@ -28,7 +28,7 @@ export interface ExecuteStatementCommandOutput extends ExecuteStatementResponse,
  *                     <code>transactionID</code> parameter, changes that result from the call are
  *                 committed automatically.</p>
  *         </important>
- *         <p>The response size limit is 1 MB. If the call returns more than 1 MB of response data, the call is terminated.</p>
+ *         <p>If the binary response data from the database is more than 1 MB, the call is terminated.</p>
  * @example
  * Use a bare-bones client and the command you need to make an API call.
  * ```javascript

clients/client-rds-data/src/models/models_0.ts

@@ -3,6 +3,25 @@ import { MetadataBearer as $MetadataBearer } from "@aws-sdk/types";
 
 import { RDSDataServiceException as __BaseException } from "./RDSDataServiceException";
 
+/**
+ * <p>You do not have sufficient access to perform this action.</p>
+ */
+export class AccessDeniedException extends __BaseException {
+  readonly name: "AccessDeniedException" = "AccessDeniedException";
+  readonly $fault: "client" = "client";
+  /**
+   * @internal
+   */
+  constructor(opts: __ExceptionOptionType<AccessDeniedException, __BaseException>) {
+    super({
+      name: "AccessDeniedException",
+      $fault: "client",
+      ...opts,
+    });
+    Object.setPrototypeOf(this, AccessDeniedException.prototype);
+  }
+}
+
 /**
  * <p>There is an error in the call or in a SQL statement.</p>
  */
@@ -392,6 +411,16 @@ export namespace ResultSetMetadata {
   });
 }
 
+export enum RecordsFormatType {
+  JSON = "JSON",
+  NONE = "NONE",
+}
+
+export enum LongReturnType {
+  LONG = "LONG",
+  STRING = "STRING",
+}
+
 /**
  * <p>Options that control how the result set is returned.</p>
  */
@@ -408,6 +437,15 @@ export interface ResultSetOptions {
    *         </important>
    */
   decimalReturnType?: DecimalReturnType | string;
+
+  /**
+   * <p>A value that indicates how a field of <code>LONG</code> type is represented.
+   *         Allowed values are <code>LONG</code> and <code>STRING</code>. The default
+   *         is <code>LONG</code>. Specify <code>STRING</code> if the length or
+   *         precision of numeric values might cause truncation or rounding errors.
+   *         </p>
+   */
+  longReturnType?: LongReturnType | string;
 }
 
 export namespace ResultSetOptions {
@@ -494,7 +532,7 @@ export namespace ArrayValue {
   }
 
   /**
-   * <p>An array of floating point numbers.</p>
+   * <p>An array of integers.</p>
    */
   export interface LongValuesMember {
     booleanValues?: never;
@@ -506,7 +544,7 @@ export namespace ArrayValue {
   }
 
   /**
-   * <p>An array of integers.</p>
+   * <p>An array of floating-point numbers.</p>
    */
   export interface DoubleValuesMember {
     booleanValues?: never;
@@ -830,7 +868,8 @@ export namespace UpdateResult {
  * <p>Contains the value of a column.</p>
  *
  *         <important>
- *             <p>This data type is deprecated.</p>
+ *             <p>This data structure is only used with the deprecated <code>ExecuteSql</code> operation.
+ *               Use the <code>BatchExecuteStatement</code> or <code>ExecuteStatement</code> operation instead.</p>
  *         </important>
  */
 export type Value =
@@ -1148,6 +1187,17 @@ export interface ExecuteStatementRequest {
    * <p>Options that control how the result set is returned.</p>
    */
   resultSetOptions?: ResultSetOptions;
+
+  /**
+   * <p>A value that indicates whether to format the result set as a single JSON string.
+   *         This parameter only applies to <code>SELECT</code> statements and is ignored for
+   *         other types of statements. Allowed values are <code>NONE</code> and <code>JSON</code>.
+   *         The default value is <code>NONE</code>. The result is returned in the <code>formattedRecords</code> field.</p>
+   *         <p>For usage information about the JSON format for result sets, see
+   *           <a href="https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/data-api.html">Using the Data API</a>
+   *           in the <i>Amazon Aurora User Guide</i>.</p>
+   */
+  formatRecordsAs?: RecordsFormatType | string;
 }
 
 export namespace ExecuteStatementRequest {
@@ -1162,6 +1212,10 @@ export namespace ExecuteStatementRequest {
 
 /**
  * <p>A structure value returned by a call.</p>
+ *         <important>
+ *             <p>This data structure is only used with the deprecated <code>ExecuteSql</code> operation.
+ *               Use the <code>BatchExecuteStatement</code> or <code>ExecuteStatement</code> operation instead.</p>
+ *         </important>
  */
 export interface StructValue {
   /**
@@ -1273,6 +1327,10 @@ export namespace BatchExecuteStatementResponse {
 
 /**
  * <p>A record returned by a call.</p>
+ *         <important>
+ *             <p>This data structure is only used with the deprecated <code>ExecuteSql</code> operation.
+ *               Use the <code>BatchExecuteStatement</code> or <code>ExecuteStatement</code> operation instead.</p>
+ *         </important>
  */
 export interface _Record {
   /**
@@ -1297,12 +1355,14 @@ export namespace _Record {
  */
 export interface ExecuteStatementResponse {
   /**
-   * <p>The records returned by the SQL statement.</p>
+   * <p>The records returned by the SQL statement. This field is blank if the
+   *         <code>formatRecordsAs</code> parameter is set to <code>JSON</code>.</p>
    */
   records?: Field[][];
 
   /**
-   * <p>Metadata for the columns included in the results.</p>
+   * <p>Metadata for the columns included in the results. This field is blank if the
+   *         <code>formatRecordsAs</code> parameter is set to <code>JSON</code>.</p>
    */
   columnMetadata?: ColumnMetadata[];
 
@@ -1312,7 +1372,7 @@ export interface ExecuteStatementResponse {
   numberOfRecordsUpdated?: number;
 
   /**
-   * <p>Values for fields generated during the request.</p>
+   * <p>Values for fields generated during a DML request.</p>
    *
    *         <note>
    *             <p>The <code>generatedFields</code> data isn't supported by Aurora PostgreSQL.
@@ -1322,6 +1382,15 @@ export interface ExecuteStatementResponse {
    *         </note>
    */
   generatedFields?: Field[];
+
+  /**
+   * <p>A string value that represents the result set of a <code>SELECT</code> statement
+   *         in JSON format. This value is only present when the <code>formatRecordsAs</code>
+   *         parameter is set to <code>JSON</code>.</p>
+   *         <p>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.</p>
+   */
+  formattedRecords?: string;
 }
 
 export namespace ExecuteStatementResponse {
@@ -1337,6 +1406,10 @@ export namespace ExecuteStatementResponse {
 
 /**
  * <p>The result set returned by a SQL statement.</p>
+ *         <important>
+ *             <p>This data structure is only used with the deprecated <code>ExecuteSql</code> operation.
+ *               Use the <code>BatchExecuteStatement</code> or <code>ExecuteStatement</code> operation instead.</p>
+ *         </important>
  */
 export interface ResultFrame {
   /**
@@ -1364,7 +1437,8 @@ export namespace ResultFrame {
  * <p>The result of a SQL statement.</p>
  *
  *         <important>
- *             <p>This data type is deprecated.</p>
+ *             <p>This data structure is only used with the deprecated <code>ExecuteSql</code> operation.
+ *               Use the <code>BatchExecuteStatement</code> or <code>ExecuteStatement</code> operation instead.</p>
  *         </important>
  */
 export interface SqlStatementResult {

clients/client-rds-data/src/protocols/Aws_restJson1.ts

@@ -32,6 +32,7 @@ import {
 } from "../commands/RollbackTransactionCommand";
 import {
   _Record,
+  AccessDeniedException,
   ArrayValue,
   BadRequestException,
   ColumnMetadata,
@@ -182,6 +183,8 @@ export const serializeAws_restJson1ExecuteStatementCommand = async (
     ...(input.continueAfterTimeout !== undefined &&
       input.continueAfterTimeout !== null && { continueAfterTimeout: input.continueAfterTimeout }),
     ...(input.database !== undefined && input.database !== null && { database: input.database }),
+    ...(input.formatRecordsAs !== undefined &&
+      input.formatRecordsAs !== null && { formatRecordsAs: input.formatRecordsAs }),
     ...(input.includeResultMetadata !== undefined &&
       input.includeResultMetadata !== null && { includeResultMetadata: input.includeResultMetadata }),
     ...(input.parameters !== undefined &&
@@ -263,6 +266,9 @@ const deserializeAws_restJson1BatchExecuteStatementCommandError = async (
   let errorCode = "UnknownError";
   errorCode = loadRestJsonErrorCode(output, parsedOutput.body);
   switch (errorCode) {
+    case "AccessDeniedException":
+    case "com.amazonaws.rdsdata#AccessDeniedException":
+      throw await deserializeAws_restJson1AccessDeniedExceptionResponse(parsedOutput, context);
     case "BadRequestException":
     case "com.amazonaws.rdsdata#BadRequestException":
       throw await deserializeAws_restJson1BadRequestExceptionResponse(parsedOutput, context);
@@ -319,6 +325,9 @@ const deserializeAws_restJson1BeginTransactionCommandError = async (
   let errorCode = "UnknownError";
   errorCode = loadRestJsonErrorCode(output, parsedOutput.body);
   switch (errorCode) {
+    case "AccessDeniedException":
+    case "com.amazonaws.rdsdata#AccessDeniedException":
+      throw await deserializeAws_restJson1AccessDeniedExceptionResponse(parsedOutput, context);
     case "BadRequestException":
     case "com.amazonaws.rdsdata#BadRequestException":
       throw await deserializeAws_restJson1BadRequestExceptionResponse(parsedOutput, context);
@@ -375,6 +384,9 @@ const deserializeAws_restJson1CommitTransactionCommandError = async (
   let errorCode = "UnknownError";
   errorCode = loadRestJsonErrorCode(output, parsedOutput.body);
   switch (errorCode) {
+    case "AccessDeniedException":
+    case "com.amazonaws.rdsdata#AccessDeniedException":
+      throw await deserializeAws_restJson1AccessDeniedExceptionResponse(parsedOutput, context);
     case "BadRequestException":
     case "com.amazonaws.rdsdata#BadRequestException":
       throw await deserializeAws_restJson1BadRequestExceptionResponse(parsedOutput, context);
@@ -434,6 +446,9 @@ const deserializeAws_restJson1ExecuteSqlCommandError = async (
   let errorCode = "UnknownError";
   errorCode = loadRestJsonErrorCode(output, parsedOutput.body);
   switch (errorCode) {
+    case "AccessDeniedException":
+    case "com.amazonaws.rdsdata#AccessDeniedException":
+      throw await deserializeAws_restJson1AccessDeniedExceptionResponse(parsedOutput, context);
     case "BadRequestException":
     case "com.amazonaws.rdsdata#BadRequestException":
       throw await deserializeAws_restJson1BadRequestExceptionResponse(parsedOutput, context);
@@ -467,6 +482,7 @@ export const deserializeAws_restJson1ExecuteStatementCommand = async (
   const contents: ExecuteStatementCommandOutput = {
     $metadata: deserializeMetadata(output),
     columnMetadata: undefined,
+    formattedRecords: undefined,
     generatedFields: undefined,
     numberOfRecordsUpdated: undefined,
     records: undefined,
@@ -475,6 +491,9 @@ export const deserializeAws_restJson1ExecuteStatementCommand = async (
   if (data.columnMetadata !== undefined && data.columnMetadata !== null) {
     contents.columnMetadata = deserializeAws_restJson1Metadata(data.columnMetadata, context);
   }
+  if (data.formattedRecords !== undefined && data.formattedRecords !== null) {
+    contents.formattedRecords = __expectString(data.formattedRecords);
+  }
   if (data.generatedFields !== undefined && data.generatedFields !== null) {
     contents.generatedFields = deserializeAws_restJson1FieldList(data.generatedFields, context);
   }
@@ -499,6 +518,9 @@ const deserializeAws_restJson1ExecuteStatementCommandError = async (
   let errorCode = "UnknownError";
   errorCode = loadRestJsonErrorCode(output, parsedOutput.body);
   switch (errorCode) {
+    case "AccessDeniedException":
+    case "com.amazonaws.rdsdata#AccessDeniedException":
+      throw await deserializeAws_restJson1AccessDeniedExceptionResponse(parsedOutput, context);
     case "BadRequestException":
     case "com.amazonaws.rdsdata#BadRequestException":
       throw await deserializeAws_restJson1BadRequestExceptionResponse(parsedOutput, context);
@@ -555,6 +577,9 @@ const deserializeAws_restJson1RollbackTransactionCommandError = async (
   let errorCode = "UnknownError";
   errorCode = loadRestJsonErrorCode(output, parsedOutput.body);
   switch (errorCode) {
+    case "AccessDeniedException":
+    case "com.amazonaws.rdsdata#AccessDeniedException":
+      throw await deserializeAws_restJson1AccessDeniedExceptionResponse(parsedOutput, context);
     case "BadRequestException":
     case "com.amazonaws.rdsdata#BadRequestException":
       throw await deserializeAws_restJson1BadRequestExceptionResponse(parsedOutput, context);
@@ -584,6 +609,22 @@ const deserializeAws_restJson1RollbackTransactionCommandError = async (
   }
 };
 
+const deserializeAws_restJson1AccessDeniedExceptionResponse = async (
+  parsedOutput: any,
+  context: __SerdeContext
+): Promise<AccessDeniedException> => {
+  const contents: any = {};
+  const data: any = parsedOutput.body;
+  if (data.message !== undefined && data.message !== null) {
+    contents.message = __expectString(data.message);
+  }
+  const exception = new AccessDeniedException({
+    $metadata: deserializeMetadata(parsedOutput),
+    ...contents,
+  });
+  return __decorateServiceException(exception, parsedOutput.body);
+};
+
 const deserializeAws_restJson1BadRequestExceptionResponse = async (
   parsedOutput: any,
   context: __SerdeContext
@@ -749,6 +790,8 @@ const serializeAws_restJson1ResultSetOptions = (input: ResultSetOptions, context
   return {
     ...(input.decimalReturnType !== undefined &&
       input.decimalReturnType !== null && { decimalReturnType: input.decimalReturnType }),
+    ...(input.longReturnType !== undefined &&
+      input.longReturnType !== null && { longReturnType: input.longReturnType }),
   };
 };