\n```\n\nAbstraction of the AWS SDK RDSDataService [`executeStatement`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/RDSDataService.html#executeStatement-property) operation.\n\nFrom the [SDK Docs](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/RDSDataService.html#executeStatement-property):\n\n> Runs a SQL statement against a database.
\n> 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.
\n> The response size limit is 1 MB or 1,000 records. If the call returns more than 1 MB of response data or over 1,000 records, the call is terminated.
\n\n#### Arguments\n\n| Name | Description | Required |\n| ---- | ----------- | -------- |\n| `options` | See options below. | Yes |\n\n#### Options\n\n| Name | Description | Default |\n| ---- | ----------- | ------- |\n| `sql` (Required) | The SQL statement to run. | `undefined` |\n| `includeResultMetadata` | Includes the column metadata. | `undefined` |\n| `continueAfterTimeout` | 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. | Defined in [constructor](#auroradataapiconstructor). |\n| `database` | The name of the database. | Defined in [constructor](#auroradataapiconstructor). |\n| `resourceArn` | The Amazon Resource Name (ARN) of the Aurora Serverless DB cluster. | Defined in [constructor](#auroradataapiconstructor). |\n| `resultSetOptions` | Options that control how the result set is returned. | Defined in [constructor](#auroradataapiconstructor). |\n| `schema` | The name of the database schema. | Defined in [constructor](#auroradataapiconstructor). |\n| `secretArn` | The name or ARN of the secret that enables access to the DB cluster. | Defined in [constructor](#auroradataapiconstructor). |\n| `transactionId` | 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. | `undefined` |\n\n#### Further reading\n\n- https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/RDSDataService.html#executeStatement-property\n- https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_ExecuteStatement.html\n\n### `AuroraDataAPI#batchExecuteStatement`\n\n```ts\nbatchExecuteStatement(\n options: AuroraDataAPI.BatchExecuteStatementOptions\n) => Promise\n```\n\nAbstraction of the AWS SDK RDSDataService [`batchExecuteStatement`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/RDSDataService.html#batchExecuteStatement-property) operation.\n\nFrom the [SDK docs](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/RDSDataService.html#batchExecuteStatement-property):\n> Runs a batch SQL statement over an array of data.
\n> You can run bulk update and insert operations for multiple records using a DML statement with different parameter sets. Bulk operations can provide a significant performance improvement over individual insert and update operations.
\n> 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.
\n\n#### Arguments\n\n| Name | Description | Required |\n| ---- | ----------- | -------- |\n| `options` | See options below. | Yes |\n\n#### Options\n\n| Name | Description | Default |\n| ---- | ----------- | ------- |\n| `sql` (Required) | The SQL statement to run. | `undefined` |\n| `parameterSets` | The parameter set for the batch operation. The maximum number of parameters in a parameter set is 1,000. | `undefined` |\n| `database` | The name of the database. | Defined in [constructor](#auroradataapiconstructor). |\n| `resourceArn` | The Amazon Resource Name (ARN) of the Aurora Serverless DB cluster. | Defined in [constructor](#auroradataapiconstructor). |\n| `schema` | The name of the database schema. | Defined in [constructor](#auroradataapiconstructor). |\n| `secretArn` | The name or ARN of the secret that enables access to the DB cluster. | Defined in [constructor](#auroradataapiconstructor). |\n| `transactionId` | The identifier of a transaction that was started by using the `beginTransaction` method. Specify the transaction ID of the transaction that you want to include the SQL statement in. | `undefined` |\n\n#### Further reading\n\n- https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/RDSDataService.html#batchExecuteStatement-property\n- https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_BatchExecuteStatement.html\n\n## `AuroraDataAPI.Transaction` methods\n\n[`AuroraDataAPI#beginTransaction`](#auroradataapibegintransaction) resolves an instance of `AuroraDataAPI.Transaction` that exposes the following methods:\n\n| Name | Description |\n| ---- | ----------- |\n| [`query`](#auroradataapitransactionquery) | Performs an SQL query in the transaction. |\n| [`batchQuery`](#auroradataapitransactionbatchquery) | Performs an SQL query over an array of data in the transaction. |\n| [`commit`](#auroradataapitransactioncommit) | Commits and ends the transaction. |\n| [`rollback`](#auroradataapitransactionrollback) | Rolls-back and ends the transaction. |\n| [`executeStatement`](#auroradataapitransactionexecutestatement) | Abstraction of the [`RDSDataService#executeStatement`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/RDSDataService.html#executeStatement-property) method in context of the transaction. |\n| [`batchExecuteStatement`](#auroradataapitransactionbatchexecutestatement) | Abstraction of the RDSDataService [`RDSDataService#batchExecuteStatement`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/RDSDataService.html#batchExecuteStatement-property) method in context of the transaction. |\n\n### `AuroraDataAPI.Transaction#query`\n\n```ts\nquery(\n sql: string,\n params?: AuroraDataAPI.QueryParams,\n options?: AuroraDataAPI.Transaction.TransactionQueryOptions\n) => Promise>\n```\n\nPerforms an SQL statement in the transaction.\n\nThe response size limit is 1 MB or 1,000 records. If the call returns more than 1 MB of response data or over 1,000 records, the call is terminated.\n\n#### Arguments\n\n| Name | Description | Required |\n| ---- | ----------- | -------- |\n| `sql` | The SQL statement string to perform. | Yes |\n| `params` | See [Query Params](#query-params). | No |\n| `options` | See options below. | No |\n\n#### Options\n\n| Name | Description | Default |\n| ---- | ----------- | ------- |\n| `includeResultMetadata` | A value that indicates whether to include metadata in the results. **Note**: must be `true` for the results to be transformed. | Defined in [`#beginTransaction`](#auroradataapibegintransaction). |\n| `continueAfterTimeout` | 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. | Defined in [`#beginTransaction`](#auroradataapibegintransaction). |\n| `resultSetOptions` | Options that control how the result set is returned. | Defined in [`#beginTransaction`](#auroradataapibegintransaction). |\n| `valueTransformer` | See [Value Transformer](#value-transformer). | Defined in [`#beginTransaction`](#auroradataapibegintransaction) |\n\n#### Further reading\n\n- https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/RDSDataService.html#executeStatement-property\n- https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_ExecuteStatement.html\n\n### `AuroraDataAPI.Transaction#batchQuery`\n\n```ts\nbatchQuery(\n sql: string,\n params?: AuroraDataAPI.QueryParams[]\n) => Promise>\n```\n\nPerforms a batch SQL statement over an array of data in the transaction.\n\n#### Arguments\n\n| Name | Description | Required |\n| -------- | ------------------------------------------------------------ | -------- |\n| `sql` | The SQL query string to perform. | Yes |\n| `params` | An array of [Query Params](#query-params). Maximum of 1,000. | No |\n\n#### Further reading\n\n- https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/RDSDataService.html#batchExecuteStatement-property\n- https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_BatchExecuteStatement.html\n\n### `AuroraDataAPI.Transaction#commit`\n\nCommits and ends the transaction.\n\n```ts\ncommit() => Promise\n```\n\n#### Further reading\n\n- https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/RDSDataService.html#commitTransaction-property\n- https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_CommitTransaction.html\n\n### `AuroraDataAPI.Transaction#rollback`\n\n```ts\nrollback() => Promise\n```\n\nRolls-back and ends the transaction.\n\n#### Further reading\n\n- https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/RDSDataService.html#rollbackTransaction-property\n- https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_RollbackTransaction.html\n\n### `AuroraDataAPI.Transaction#executeStatement`\n\n```ts\nexecuteStatement(\n options: AuroraDataAPI.Transaction.ExecuteStatementOptions\n) => Promise\n```\n\nAbstraction of the [`RDSDataService#executeStatement`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/RDSDataService.html#executeStatement-property) method in context of the transaction.\n\n#### Arguments\n\n| Name | Description | Required |\n| --------- | ------------------ | -------- |\n| `options` | See options below. | Yes |\n\n#### Options\n\n| Name | Description | Default |\n| ----------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |\n| `sql` (Required) | The SQL statement to run. | `undefined` |\n| `includeResultMetadata` | A value that indicates whether to include metadata in the results. | Defined in [`#beginTransaction`](#auroradataapibegintransaction). |\n| `continueAfterTimeout` | 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. | Defined in [`#beginTransaction`](#auroradataapibegintransaction). |\n| `resultSetOptions` | Options that control how the result set is returned. | Defined in [`#beginTransaction`](#auroradataapibegintransaction). |\n\n#### Further reading\n\n- https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/RDSDataService.html#executeStatement-property\n- https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_ExecuteStatement.html\n\n### `AuroraDataAPI.Transaction#batchExecuteStatement`\n\n```ts\nbatchExecuteStatement(\n options: AuroraDataAPI.Transaction.BatchExecuteStatementOptions\n) => Promise\n```\n\nAbstraction of the RDSDataService [`RDSDataService#batchExecuteStatement`](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/RDSDataService.html#batchExecuteStatement-property) method in context of the transaction.\n\n#### Arguments\n\n| Name | Description | Required |\n| --------- | ------------------ | -------- |\n| `options` | See options below. | Yes |\n\n#### Options\n\n| Name | Description | Default |\n| ---------------- | ------------------------------------------------------------ | ----------- |\n| `sql` (Required) | The SQL statement to run. | `undefined` |\n| `parameterSets` | The parameter set for the batch operation. The maximum number of parameters in a parameter set is 1,000. | `undefined` |\n\n#### Further reading\n\n- https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/RDSDataService.html#batchExecuteStatement-property\n- https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_BatchExecuteStatement.html\n\n## Query Params\n\nQuery params are, to put simply, just a JS object of *names* and *values*. The *name* is attributed to the placeholder in your SQL statement, for instance:\n\n```ts\nquery('SELECT * FROM users WHERE id = :id', { id: 99 })\n```\n\nThe SQL statement with the placeholder `:id` will be interpreted as `SELECT * FROM users WHERE id = 99`.\n\nThe Data API for Aurora Serverless however, expects `parameters` to be defined like so:\n\n```ts\n[\n {\n name: 'id',\n value: {\n longValue: 99\n }\n }\n]\n```\n\n`AuroraDataAPI` transforms your query params by inspecting the type of the value. If you need more control, for instance, when inserting JSON, you can define your params using AWS's structure, for example:\n\n```ts\nquery('UPDATE users SET json_data = :jsonData WHERE id = :id', {\n id: 99,\n jsonData: {\n typehint: 'json',\n value: {\n stringValue: JSON.stringify({ foo: 'bar' })\n }\n }\n})\n```\n\nNote that `name` is omitted from the object because it is defined by the key.\n\nSee [The docs on RDSDataService#executeStatement](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/RDSDataService.html#executeStatement-property) and the [SqlParameter documentation](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_SqlParameter.html) for more information on how to structure your parameter in the \"RDSDataService way\".\n\n### How values are transformed\n\n| Value Type | Transformed Field |\n| ---- | ----- |\n| `string` | `{ stringValue: value }` |\n| `boolean` | `{ booleanValue: value }` |\n| `number` (integer) | `{ longValue: value }` |\n| `number` (float) | `{ doubleValue: value }` |\n| `string[]` | `{ arrayValue: { stringValues: values } }` |\n| `boolean[]` | `{ arrayValue: { booleanValues: values } }` |\n| `number[]` (integer) | `{ arrayValue: { longValues: values } }` |\n| `number[]` (float) | `{ arrayValue: { doubleValues: values } }` |\n| `instanceof Buffer` | `{ blobValue: value }` |\n| `instanceof Uint8Array` | `{ blobValue: value }` |\n\nMultidimensional arrays are also transformed recursively:\n\n```ts\n// these AuroraDataAPI Query parms...\n{\n threeDimensions: [\n [\n ['1.1.1', '1.1.2'],\n ['1.2.1', '1.2.2']\n ],\n ['2.1.1', '2.1.2'],\n ['2.2.1', '2.2.2']\n ]\n}\n\n// are transformed into these RDSDataService parameters...\n[\n {\n name: 'threeDimensions',\n value: {\n arrayValue: {\n arrayValues: [\n {\n arrayValues: [\n {\n arrayValues: {\n stringValues: ['1.1.1', '1.1.2']\n }\n },\n {\n arrayValues: {\n stringValues: ['1.2.1', '1.2.2']\n }\n }\n ],\n arrayValues: [\n {\n arrayValues: {\n stringValues: ['2.1.1', '2.1.2']\n }\n },\n {\n arrayValues: {\n stringValues: ['2.2.1', '2.2.2']\n }\n }\n ]\n }\n ]\n }\n }\n }\n]\n\n```\n\n### Custom value classes\n\nSupport for `CustomValue` classes make it easy to \"DRY\" your code. They offer a way to encapsulate your values so they can be transformed into an `SqlParameter`. Here is an example of a `uuid` value:\n\n```ts\nclass UUIDValue implements AuroraDataAPI.CustomValue {\n private value: string\n\n constructor (value: string) {\n this.value = value\n }\n\n toSqlParameter (): AuroraDataAPI.SqlParameter {\n return {\n typeHint: 'uuid',\n value: {\n stringValue: this.value\n }\n }\n }\n}\n\nawait query(\n 'SELECT * FROM users WHERE uuid = :uuid',\n { uuid: new UUIDValue(req.params.uuid) }\n)\n\n// it works with arrays too:\nawait query(\n 'SELECT * FROM users WHERE uuid = ANY(:uuids)',\n { uuids: req.params.uuids.map((uuid) => new UUIDValue(uuid)) }\n)\n\n```\n\nA few predefined custom values are available: `AuroraDataAPI.JSONValue` and `AuroraDataAPI.BlobValue`, for more information please take a look at [`src/customValues.ts`](https://github.com/caspiandb/data-api-suite/tree/master/packages/aurora-data-api/src/customValues.ts).\n\n## Value Transformer\n\nWhen `includeResultMetadata` is `true`, the Data API response payload includes metadata for each of the columns in the result set. In cases such as `timezone`, `json` or `jsonb` columns, the column value will be returned as a `stringValue` (or `stringValues` in the case of an array).\n\nBy default `AuroraDataAPI` some types (such as those described above) into the expected objects. e.g. a `timezone` column will be parsed with `new Date`, a `jsonb` column will parsed using `JSON.parse`.\n\nYou can override and/or extend the default behavior by providing your own `valueTransformer` like so:\n\n```ts\nconst valueTransformer = (\n value: any,\n metadata: RDSDataService.ColumnMetadata,\n next: Function\n) => {\n if (\n metadata.typeName === 'varchar' &&\n typeof value === 'string'\n ) {\n return value.toUpperCase()\n }\n return next() // remove this line to disable the default value transformer\n}\n\n// construct AuroraDataAPI with your new value transformer\nconst client = new AuroraDataAPI({\n ...config,\n valueTransformer\n})\n\n// or add it to the options argument on #query or transaction#query\nconst result = await client.query(\n 'SELECT email FROM users',\n undefined,\n { valueTransformer }\n) // => { rows: [{ email: 'EXAMPLE@EXAMPLE.COM' }] }\n```\n\n## Example\n\nTake a look at the [example folder](https://github.com/caspiandb/data-api-suite/tree/master/example) for a complete example app that uses all the **Data API for Aurora Serverless Suite** packages.\n\n## MIT License\n\nCopyright (c) 2020 Marc Greenstock\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n","readmeFilename":"README.md"}