docs: update versioning (#183)

karenc-bq · web-flow · commit 537933146928 · 2024-06-18T14:45:32.000-07:00
diff --git a/docs/Documentation.md b/docs/Documentation.md
@@ -23,11 +23,11 @@
         - [Sample Code](./using-the-aws-driver/UsingTheAwsDriver.md#sample-code)
         - [08007 - Connection Failure During Transaction](./using-the-aws-driver/UsingTheAwsDriver.md#08007---connection-failure-during-transaction)
         - [Sample Code](./using-the-aws-driver/UsingTheAwsDriver.md#sample-code-1)
-    - [AWS Authentication](./using-the-aws-driver/UsingTheAwsDriver.md#aws-authentication)
-        - [IAM Authentication](./using-the-aws-driver/UsingTheAwsDriver.md#iam-authentication)
-            - [How to use IAM](./using-the-aws-driver/UsingTheAwsDriver.md#how-to-use-iam)
-        - [Secrets Manager Authentication](./using-the-aws-driver/UsingTheAwsDriver.md#secrets-manager-authentication)
-            - [How to use Secrets Manager](./using-the-aws-driver/UsingTheAwsDriver.md#how-to-use-secrets-manager)
+    - [AWS Authentication](./using-the-aws-driver/AwsAuthentication.md)
+        - [IAM Authentication](./using-the-aws-driver/AwsAuthentication.md#iam-authentication)
+            - [How to use IAM](./using-the-aws-driver/AwsAuthentication.md#how-to-use-iam)
+        - [Secrets Manager Authentication](./using-the-aws-driver/AwsAuthentication.md#secrets-manager-authentication)
+            - [How to use Secrets Manager](./using-the-aws-driver/AwsAuthentication.md#how-to-use-secrets-manager)
     - [Logging](./using-the-aws-driver/UsingTheAwsDriver.md#logging)
         - [Enabling Logs On Windows](./using-the-aws-driver/UsingTheAwsDriver.md#enabling-logs-on-windows)
             - [Example](./using-the-aws-driver/UsingTheAwsDriver.md#example)
diff --git a/docs/building-the-aws-driver/BuildingAwsSdkCpp.md b/docs/building-the-aws-driver/BuildingAwsSdkCpp.md
@@ -1,23 +1,21 @@
 # Building the AWS SDK for C++
 The driver supports AWS IAM and AWS Secrets Manager authentication by using [AWS SDK for C++](https://docs.aws.amazon.com/sdk-for-cpp/). The driver requires `aws-cpp-sdk-core`, `aws-cpp-sdk-rds`, and `aws-cpp-sdk-secretsmanager`. You can either build the SDK yourself directly from the source using the script under `scripts` folder or [download the libraries using a package manager](https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/sdk-from-pm.html). The script will install the SDK under `aws_sdk/install` folder. The driver will look for SDK dependencies through `aws_sdk/install` folder and `CMAKE_PREFIX_PATH` environment variable.
-> **_NOTE:_** On Windows, depending on the use case, you may build the SDK as a static library or dynamic library. On Linux and macOS, you should always build the SDK as a dynamic library.
+> [!NOTE]\
+> On Windows, depending on the use case, you may build the SDK as a static library or dynamic library. On Linux and macOS, you should always build the SDK as a dynamic library.
 
 ## Windows
 ### For release version unit tests or driver
 ```
-.\scripts\build_aws_sdk_win.ps1 x64 Release ON "Visual Studio 16 2019"
+.\scripts\build_aws_sdk_win.ps1 x64 Release ON "Visual Studio 17 2022"
 ```
 ### For debug version unit tests
 ```
-.\scripts\build_aws_sdk_win.ps1 x64 Debug ON "Visual Studio 16 2019"
+.\scripts\build_aws_sdk_win.ps1 x64 Debug ON "Visual Studio 17 2022"
 ```
-Note:
-- Use ```Visual Studio 17 2022`` for Visual Studio 2022. 
-
 ## Linux/macOS
 ```
 ./scripts/build_aws_sdk_unix.sh Release
 ```
 
 ## Troubleshoot
-See https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/troubleshooting-cmake.html
+See https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/troubleshooting-cmake.html
diff --git a/docs/building-the-aws-driver/BuildingTheAwsDriver.md b/docs/building-the-aws-driver/BuildingTheAwsDriver.md
@@ -5,21 +5,20 @@
 1. Install the following programs to build the driver:
     - [CMake](https://cmake.org/download/)
     - [Visual Studio](https://visualstudio.microsoft.com/downloads/)
-      > The driver has been built successfully using `Visual Studio 2019`, and it may not build correctly with other versions. When installing Visual Studio, ensure the `Visual C++ 2019` and `Visual Studio Tools for CMake` packages are also installed.
     - [MySQL Server](https://dev.mysql.com/downloads/installer/)
 
 2. Refer to [Building the AWS SDK for C++](./BuildingAwsSdkCpp.md) to install required AWS dependencies.
    
 3. Build the driver in the `build` directory with the following commands:
     ```
-    cmake -S . -B build -G "Visual Studio 16 2019" -DMYSQL_DIR="C:\Program Files\MySQL\MySQL Server 8.0" -DMYSQLCLIENT_STATIC_LINKING=TRUE
+    cmake -S . -B build -G "Visual Studio 17 2022" -DMYSQL_DIR="C:\Program Files\MySQL\MySQL Server 8.3" -DMYSQLCLIENT_STATIC_LINKING=TRUE
     cmake --build build --config Release
     ```
 4. To build the installer, MySQL 8.0.36 is required. Other MySQL versions may not work. Download the [MySQL 8.0.36](https://downloads.mysql.com/archives/community/) ZIP archive or msi installer. If the zip archive is used, unzip it to a folder before using it.
 
     Run `build_installer.ps1` with specified MySQL 8.0.36 installation or unzipped folder path in a developer powershell. For example
     ```
-    .\build_installer.ps1 x64 Release "Visual Studio 16 2019"  "C:\Users\MyUser\Downloads\mysql-8.0.36-winx64\mysql-8.0.36-winx64"
+    .\build_installer.ps1 x64 Release "Visual Studio 17 2022"  "C:\Users\MyUser\Downloads\mysql-8.0.36-winx64\mysql-8.0.36-winx64"
     ```
 
 ### Troubleshooting:
diff --git a/docs/testing-the-aws-driver/TestingTheAwsDriver.md b/docs/testing-the-aws-driver/TestingTheAwsDriver.md
@@ -7,24 +7,24 @@
      
      - For release version unit tests, run the following command from repository root
         ```
-        cmake -S . -B build -G "Visual Studio 16 2019" -DMYSQL_DIR="C:\Program Files\MySQL\MySQL Server 8.0" -DMYSQLCLIENT_STATIC_LINKING=TRUE -DENABLE_UNIT_TESTS=TRUE
+        cmake -S . -B build -G "Visual Studio 17 2022" -DMYSQL_DIR="C:\Program Files\MySQL\MySQL Server 8.3" -DMYSQLCLIENT_STATIC_LINKING=TRUE -DENABLE_UNIT_TESTS=TRUE
         cmake --build build --config Release
         ```
      - For debug version unit tests
 
        - Download MySQL debug binaries from [MySQL::Download MySQL Community Server](https://dev.mysql.com/downloads/mysql/).
 
-       - Extract the `mysqlclient.lib` from debug binaries. Make sure to backup your release version of mysqlclient.lib in `MYSQL_DIR\lib`, e.g. `C:\Program Files\MySQL\MySQL Server 8.0\lib`. Replace release version `mysqlclient.lib` with debug version of `mysqlclient.lib`.
+       - Extract the `mysqlclient.lib` from debug binaries. Make sure to backup your release version of mysqlclient.lib in `MYSQL_DIR\lib`, e.g. `C:\Program Files\MySQL\MySQL Server 8.3\lib`. Replace release version `mysqlclient.lib` with debug version of `mysqlclient.lib`.
        - Run the following command from repository root
 
         ```
-        cmake -S . -B build -G "Visual Studio 16 2019" -DMYSQL_DIR="C:\Program Files\MySQL\MySQL Server 8.0" -DMYSQLCLIENT_STATIC_LINKING=TRUE -DENABLE_UNIT_TESTS=TRUE -DCMAKE_BUILD_TYPE=Debug
+        cmake -S . -B build -G "Visual Studio 17 2022" -DMYSQL_DIR="C:\Program Files\MySQL\MySQL Server 8.3" -DMYSQLCLIENT_STATIC_LINKING=TRUE -DENABLE_UNIT_TESTS=TRUE -DCMAKE_BUILD_TYPE=Debug
         cmake --build build --config Debug
         ```
    - **MacOS**
       - Run the following command from repository root 
         ```
-        cmake -S . -B build -G "Unix Makefiles" -DMYSQLCLIENT_STATIC_LINKING=true -DODBC_INCLUDES=/usr/local/Cellar/libiodbc/3.52.15/include -DENABLE_UNIT_TESTS=TRUE
+        cmake -S . -B build -G "Unix Makefiles" -DMYSQLCLIENT_STATIC_LINKING=true -DODBC_INCLUDES=/usr/local/Cellar/libiodbc/3.52.16/include -DENABLE_UNIT_TESTS=TRUE
         cmake --build build --config Release
         ```
    - **Linux**
diff --git a/docs/using-the-aws-driver/AwsAuthentication.md b/docs/using-the-aws-driver/AwsAuthentication.md
@@ -0,0 +1,50 @@
+## AWS Authentication
+
+### IAM Authentication
+
+AWS Identity and Access Management (IAM) grants users access control across all Amazon Web Services. IAM supports granular permissions, giving you the ability to grant different permissions to different users. For more information on IAM and it's use cases, please refer to the [IAM documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html).
+
+The AWS ODBC Driver for MySQL supports Amazon AWS Identity and Access Management (IAM) authentication. When using AWS IAM database authentication, the host URL must be a valid Amazon endpoint, and not a custom domain or an IP address.
+<br>ie. `db-identifier.cluster-XYZ.us-east-2.rds.amazonaws.com`
+
+IAM database authentication use is limited to certain database engines. For more information on limitations and recommendations, please [review the IAM documentation](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.html).
+
+#### How to use IAM?
+1. Enable AWS IAM database authentication on an existing database or create a new database with AWS IAM database authentication on the AWS RDS Console:
+    1. If needed, review the documentation about [creating a new database](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_CreateDBInstance.html).
+    2. If needed, review the documentation about [modifying an existing database](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Overview.DBInstance.Modifying.html).
+2. Set up an [AWS IAM policy](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.IAMPolicy.html) for AWS IAM database authentication.
+3. [Create a database account](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.IAMDBAuth.DBAccounts.html) using AWS IAM database authentication:
+   Use the following commands to create a new IAM user:<br>
+   `CREATE USER example_user_name IDENTIFIED WITH AWSAuthenticationPlugin AS 'RDS';`
+   `GRANT ALL PRIVILEGES ON example_database.* TO 'example_user_name'@'%';`
+4. Connect to a MySQL database with the following connection parameters configured in a DSN or connection string. (Note these are in addition to the parameters that you can configure for the [MySQL Connector/ODBC driver](https://dev.mysql.com/doc/connector-odbc/en/connector-odbc-configuration-connection-parameters.html))
+
+| Option                | Description                                                                                                                                      | Type  | Required | Default     |
+|-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------|-------|----------|-------------|
+| `AUTHENTICATION_MODE` | Set to `IAM` to enable IAM Authentication.                                                                                                       | char* | Yes      | Off         |
+| `AWS_REGION`          | Region used to generate IAM tokens.                                                                                                              | char* | No       | `us-east-1` |
+| `IAM_HOST`            | Host URL for IAM authentication. URL must be a valid Amazon endpoint, and not a custom domain or an IP address.                                  | char* | Yes      | Empty       |
+| `IAM_PORT`            | Port used for IAM authentication.                                                                                                                | int   | No       | `3306`      |
+| `IAM_EXPIRATION_TIME` | Amount of time in seconds before the generated IAM token expires. After expiration, future connections will require a new token to be generated. | int   | No       | `900`       |
+
+If you are working with the Windows DSN UI, click `Details >>` and navigate to the `AWS Authentication` tab to configure the parameters.
+
+![sample_iam_dsn](../images/sample_iam_dsn.png)
+
+### Secrets Manager Authentication
+
+The AWS ODBC Driver for MySQL supports usage of database credentials stored as secrets in the [AWS Secrets Manager](https://aws.amazon.com/secrets-manager/). When you connect using Secrets Manager authentication, the driver will retrieve the secret and the connection will be created with the credentials inside that secret.
+
+#### How to use Secrets Manager
+The following parameters are required for the AWS Secrets Manager Connection Plugin to retrieve database credentials from the AWS Secrets Manager.
+
+| Option                | Description                                                        | Type  | Required                       | Default     |
+|-----------------------|--------------------------------------------------------------------|-------|--------------------------------|-------------|
+| `AUTHENTICATION_MODE` | Set to `SECRETS MANAGER` to enable Secrets Manager Authentication. | char* | Yes                            | Off         |
+| `AWS_REGION`          | Region of the secret.                                              | char* | Optional when secret id is ARN | `us-east-1` |
+| `SECRET_ID`           | Secret name or secret ARN.                                         | char* | Yes                            | Empty       |
+
+If you are working with the Windows DSN UI, click `Details >>` and navigate to the `AWS Authentication` tab to configure the parameters.
+
+![sample_sm_dsn](../images/sample_sm_dsn.png)
diff --git a/docs/using-the-aws-driver/UsingTheAwsDriver.md b/docs/using-the-aws-driver/UsingTheAwsDriver.md
