docs: add instructions to run code samples (#374)

aws · Jan 20, 2025 · 2274a05 · 2274a05
1 parent 80e80f9
commit 2274a05
Show file tree

Hide file tree

Showing 2 changed files with 36 additions and 13 deletions.
diff --git a/docs/Documentation.md b/docs/Documentation.md
@@ -18,17 +18,19 @@
     - [Aurora Connection Tracker Plugin](./using-the-nodejs-wrapper/using-plugins/UsingTheAuroraConnectionTrackerPlugin.md)
   - [Host Availability Strategy](./using-the-nodejs-wrapper/HostAvailabilityStrategy.md)
   - [Reader Selection Strategies](./using-the-nodejs-wrapper/ReaderSelectionStrategies.md)
-  - [Development Guide](../docs/development-guide/DevelopmentGuide.md)
-    - [Setup](../docs/development-guide/DevelopmentGuide.md#setup)
-    - [Setting Up the AWS Advanced NodeJS Wrapper](../docs/development-guide/DevelopmentGuide.md#setting-up-the-aws-advanced-nodejs-wrapper)
-    - [Testing Overview](../docs/development-guide/DevelopmentGuide.md#testing-overview)
-      - [Performance Tests](../docs/development-guide/DevelopmentGuide.md#performance-tests)
-    - [Running the Tests](../docs/development-guide/DevelopmentGuide.md#running-the-tests)
-    - [Architecture](../docs/development-guide/Architecture.md)
-      - [Plugin Manager](../docs/development-guide/PluginManager.md)
-      - [Loadable Plugins](../docs/development-guide/LoadablePlugins.md)
-      - [Plugin Pipeline Performance Results](../docs/development-guide/PluginPipelinePerformanceResults.md)
-      - [Plugin Service](../docs/development-guide/PluginService.md)
-      - [Pipelines](../docs/development-guide/Pipelines.md)
-      - [Read-Write Splitting Plugin Performance Results](../docs/development-guide/ReadWriteSplittingPerformanceResults.md)
+- Examples
+  - [Running the AWS Advanced NodeJS Wrapper Code Samples](./../examples/aws_driver_example/README.md)
   - [Using The NodeJS Wrapper with Prisma ORM](./../examples/prisma_example/README.md)
+- [Development Guide](../docs/development-guide/DevelopmentGuide.md)
+  - [Setup](../docs/development-guide/DevelopmentGuide.md#setup)
+  - [Setting Up the AWS Advanced NodeJS Wrapper](../docs/development-guide/DevelopmentGuide.md#setting-up-the-aws-advanced-nodejs-wrapper)
+  - [Testing Overview](../docs/development-guide/DevelopmentGuide.md#testing-overview)
+    - [Performance Tests](../docs/development-guide/DevelopmentGuide.md#performance-tests)
+  - [Running the Tests](../docs/development-guide/DevelopmentGuide.md#running-the-tests)
+  - [Architecture](../docs/development-guide/Architecture.md)
+    - [Plugin Manager](../docs/development-guide/PluginManager.md)
+    - [Loadable Plugins](../docs/development-guide/LoadablePlugins.md)
+    - [Plugin Pipeline Performance Results](../docs/development-guide/PluginPipelinePerformanceResults.md)
+    - [Plugin Service](../docs/development-guide/PluginService.md)
+    - [Pipelines](../docs/development-guide/Pipelines.md)
+    - [Read-Write Splitting Plugin Performance Results](../docs/development-guide/ReadWriteSplittingPerformanceResults.md)
diff --git a/examples/aws_driver_example/README.md b/examples/aws_driver_example/README.md
@@ -0,0 +1,21 @@
+# Running The AWS Advanced NodeJS Wrapper Code Samples
+
+### Prerequisites
+
+- [npm](https://www.npmjs.com/) 9.2.0+
+
+### Running a Sample
+
+Each code snippet in the `/examples/aws_driver_example` can be run from within the project. Each example requires existing databases or AWS resources, and will need the user to edit any credentials or user specific information for the sample to run correctly.
+
+Prior to running a sample, all prerequisites for the sample must be met. For example, to run the `aws_iam_authentication_mysql_example.ts` file, you must have an IAM user set up and IAM Authentication must be enabled on the database you specify. See the individual [plugin pages](/docs/using-the-nodejs-wrapper/UsingTheNodejsWrapper.md#list-of-available-plugins) for more information.
+
+Note that for any failover examples, failover will not be triggered. For example, the `aws_failover_mysql_example.ts` sample demonstrates enabling the failover plugin and failover handling, but will not initiate cluster failover on its own. For information on how to fail over an Amazon Aurora Database cluster, see [here](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/aurora-failover.html).
+
+To run the sample:
+
+1. Ensure all prerequisites have been met.
+2. Install all required packages with `npm install`.
+3. Navigate to the `/examples/aws_driver_example` directory.
+4. Edit any credentials or user specific information in the desired file. For example, set the client properties in the file to match an existing database for the queries to run against.
+5. Run the command `npx tsx <filename>`. For example, to run the `aws_iam_authentication_mysql_example.ts` file, the command would be `npx tsx aws_iam_authentication_mysql_example.ts`.