Add failover mode

docs/using-the-aws-driver/UsingTheAwsDriver.md

@@ -32,8 +32,7 @@ In addition to the parameters that you can configure for the [MySQL Connector/OD
 | Option                             | Description                                                                                                                                                                                                                                                                                                                                                                        | Type   | Required | Default                                  |
 | ---------------------------------- |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------|----------|------------------------------------------|
 | `ENABLE_CLUSTER_FAILOVER`            | Set to `1` to enable the fast failover behaviour offered by the AWS ODBC Driver for MySQL.                                                                                                                                                                                                                                                                                         | bool   | No       | `1`                                      |
-| `ALLOW_READER_CONNECTIONS`           | Set to `1` to allow connections to reader instances during the failover process.                                                                                                                                                                                                                                                                                                   | bool   | No       | `0`                                      |
-| `ENABLE_STRICT_READER_FAILOVER`           | Set to `1` to only allow failover to reader nodes during the reader failover process. If enabled, reader failover to a writer node will only be allowed for single-node clusters. This parameter is only applicable when `ALLOW_READER_CONNECTIONS` is set to `1`.                                                                                                                                                                                                                                                                                                  | bool   | No       | `0`                                      |
+| `FAILOVER_MODE`           | Defines a mode for failover process. Failover process may prioritize nodes with different roles and connect to them. Possible values: <br><br>- `strict writer` - Failover process follows writer node and connects to a new writer when it changes.<br>- `reader or writer` - During failover, the driver tries to connect to any available/accessible reader node. If no reader is available, the driver will connect to a writer node. This logic mimics the logic of the Aurora read-only cluster endpoint.<br>- `strict reader` - During failover, the driver tries to connect to any available reader node. If no reader is available, the driver raises an error. Reader failover to a writer node will only be allowed for single-node clusters. This logic mimics the logic of the Aurora read-only cluster endpoint.                                                                                                                                                                                                                                                                                                  | char*   | No       | Default value depends on connection url. For Aurora read-only cluster endpoint, it's set to `reader or writer`. Otherwise, it's `strict writer`.                                      |                                      |
 | `GATHER_PERF_METRICS`                | Set to `1` to record failover-associated metrics.                                                                                                                                                                                                                                                                                                                                  | bool   | No       | `0`                                      |
 | `GATHER_PERF_METRICS_PER_INSTANCE`   | Set to `1` to gather additional performance metrics per instance as well as cluster.                                                                                                                                                                                                                                                                                               | bool   | No       | `0`                                      |
 | `HOST_PATTERN`                       | This parameter is not required unless connecting to an AWS RDS cluster via an IP address or custom domain URL. In those cases, this parameter specifies the cluster instance DNS pattern that will be used to build a complete instance endpoint. A "?" character in this pattern should be used as a placeholder for the DB instance identifiers of the instances in the cluster.  <br/><br/>Example: `?.my-domain.com`, `any-subdomain.?.my-domain.com:9999`<br/><br/>Usecase Example: If your cluster instance endpoint follows this pattern:`instanceIdentifier1.customHost`, `instanceIdentifier2.customHost`, etc. and you want your initial connection to be to `customHost:1234`, then your connection string should look like this: `SERVER=customHost;PORT=1234;DATABASE=test;HOST_PATTERN=?.customHost` <br><br/> If the provided connection string is not an IP address or custom domain, the driver will automatically acquire the cluster instance host pattern from the customer-provided connection string. | char\* | If connecting using an IP address or custom domain URL: Yes <br><br> Otherwise: No <br><br> See [Host Pattern](#host-pattern) for more details. | `NONE`                                   |

driver/failover.h

@@ -203,9 +203,11 @@ class FAILOVER_HANDLER {
     static bool is_rds_cluster_dns(std::string host);
     static bool is_rds_proxy_dns(std::string host);
     static bool is_rds_writer_cluster_dns(std::string host);
+    static bool is_rds_reader_cluster_dns(std::string host);
     static bool is_rds_custom_cluster_dns(std::string host);
     static std::string get_rds_cluster_host_url(std::string host);
     static std::string get_rds_instance_host_pattern(std::string host);
+    static bool is_failover_mode(const char* expected_mode, DataSource* ds);
     bool is_ipv4(std::string host);
     bool is_ipv6(std::string host);
     bool failover_to_reader(const char*& new_error_code, const char*& error_msg);

driver/failover_handler.cc

@@ -59,6 +59,9 @@ const std::regex AURORA_CLUSTER_PATTERN(
 const std::regex AURORA_WRITER_CLUSTER_PATTERN(
     R"#((.+)\.(cluster-)+([a-zA-Z0-9]+\.[a-zA-Z0-9\-]+\.rds\.amazonaws\.com))#",
     std::regex_constants::icase);
+const std::regex AURORA_READER_CLUSTER_PATTERN(
+    R"#((.+)\.(cluster-ro-)+([a-zA-Z0-9]+\.[a-zA-Z0-9\-]+\.rds\.amazonaws\.com))#",
+    std::regex_constants::icase);
 const std::regex AURORA_CUSTOM_CLUSTER_PATTERN(
     R"#((.+)\.(cluster-custom-)+([a-zA-Z0-9]+\.[a-zA-Z0-9\-]+\.rds\.amazonaws\.com))#",
     std::regex_constants::icase);
@@ -74,6 +77,9 @@ const std::regex AURORA_CHINA_CLUSTER_PATTERN(
 const std::regex AURORA_CHINA_WRITER_CLUSTER_PATTERN(
     R"#((.+)\.(cluster-)+([a-zA-Z0-9]+\.rds\.[a-zA-Z0-9\-]+\.amazonaws\.com\.cn))#",
     std::regex_constants::icase);
+const std::regex AURORA_CHINA_READER_CLUSTER_PATTERN(
+    R"#((.+)\.(cluster-ro-)+([a-zA-Z0-9]+\.rds\.[a-zA-Z0-9\-]+\.amazonaws\.com\.cn))#",
+    std::regex_constants::icase);
 const std::regex AURORA_CHINA_CUSTOM_CLUSTER_PATTERN(
     R"#((.+)\.(cluster-custom-)+([a-zA-Z0-9]+\.rds\.[a-zA-Z0-9\-]+\.amazonaws\.com\.cn))#",
     std::regex_constants::icase);
@@ -113,7 +119,8 @@ FAILOVER_HANDLER::FAILOVER_HANDLER(DBC* dbc, DataSource* ds,
 
     this->failover_reader_handler = std::make_shared<FAILOVER_READER_HANDLER>(
         this->topology_service, this->connection_handler, dbc->env->failover_thread_pool, ds->failover_timeout,
-        ds->failover_reader_connect_timeout, ds->enable_strict_reader_failover,
+        ds->failover_reader_connect_timeout,
+        is_failover_mode(FAILOVER_MODE_STRICT_READER, ds),
         dbc->id, ds->save_queries);
     this->failover_writer_handler = std::make_shared<FAILOVER_WRITER_HANDLER>(
         this->topology_service, this->failover_reader_handler,
@@ -150,6 +157,14 @@ SQLRETURN FAILOVER_HANDLER::init_connection() {
                                                network_timeout != ds->read_timeout ||
                                                network_timeout != ds->write_timeout);
         }
+
+        if (!ds->failover_mode) {
+            if (is_rds_reader_cluster_dns(this->current_host->get_host())) {
+                ds_set_wstrnattr(&ds->failover_mode, (SQLWCHAR*)to_sqlwchar_string(FAILOVER_MODE_READER_OR_WRITER).c_str(), SQL_NTS);
+            } else {
+                ds_set_wstrnattr(&ds->failover_mode, (SQLWCHAR*)to_sqlwchar_string(FAILOVER_MODE_STRICT_WRITER).c_str(), SQL_NTS);
+            }
+        }
     }
 
     if (should_connect_to_new_writer() || reconnect_with_updated_timeouts) {
@@ -416,6 +431,10 @@ bool FAILOVER_HANDLER::is_rds_writer_cluster_dns(std::string host) {
     return std::regex_match(host, AURORA_WRITER_CLUSTER_PATTERN) || std::regex_match(host, AURORA_CHINA_WRITER_CLUSTER_PATTERN);
 }
 
+bool FAILOVER_HANDLER::is_rds_reader_cluster_dns(std::string host) {
+    return std::regex_match(host, AURORA_READER_CLUSTER_PATTERN) || std::regex_match(host, AURORA_CHINA_READER_CLUSTER_PATTERN);
+}
+
 bool FAILOVER_HANDLER::is_rds_custom_cluster_dns(std::string host) {
     return std::regex_match(host, AURORA_CUSTOM_CLUSTER_PATTERN) || std::regex_match(host, AURORA_CHINA_CUSTOM_CLUSTER_PATTERN);
 }
@@ -593,7 +612,8 @@ bool FAILOVER_HANDLER::trigger_failover_if_needed(const char* error_code,
         failover_start_time_ms = std::chrono::steady_clock::now();
 
         if (current_topology && current_topology->total_hosts() > 1 &&
-            ds->allow_reader_connections) {  // there are readers in topology
+            // Trigger reader failover if failover mode is not strict writer
+            !is_failover_mode(FAILOVER_MODE_STRICT_WRITER, ds)) {
             failover_success = failover_to_reader(new_error_code, error_msg);
             elasped_time_ms =
                 std::chrono::duration_cast<std::chrono::milliseconds>(std::chrono::steady_clock::now() - failover_start_time_ms).count();
@@ -674,3 +694,7 @@ bool FAILOVER_HANDLER::failover_to_writer(const char*& new_error_code, const cha
 void FAILOVER_HANDLER::invoke_start_time() {
     invoke_start_time_ms = std::chrono::steady_clock::now();
 }
+
+bool FAILOVER_HANDLER::is_failover_mode(const char* expected_mode, DataSource* ds) {
+    return myodbc_strcasecmp(expected_mode, ds_get_utf8attr(ds->failover_mode, &ds->failover_mode8)) == 0;
+}

installer/myodbc-installer.cc

@@ -525,6 +525,7 @@ int list_datasource_details(DataSource *ds)
   /* Failover */
   if (ds->host_pattern) printf("Failover Instance Host pattern:   %s\n", ds_get_utf8attr(ds->host_pattern, &ds->host_pattern8));
   if (ds->cluster_id) printf("Failover Cluster ID:   %s\n", ds_get_utf8attr(ds->cluster_id, &ds->cluster_id8));
+  if (ds->failover_mode) printf("Failover Mode:   %s\n", ds_get_utf8attr(ds->failover_mode, &ds->failover_mode8));
 
   printf("Options:\n");
   if (ds->return_matching_rows) printf("\tFOUND_ROWS\n");
@@ -578,8 +579,7 @@ int list_datasource_details(DataSource *ds)
   if (ds->auth_secret_id) printf("\tSECRET_ID");
   /* Failover */
   if (ds->enable_cluster_failover) printf("\tENABLE_CLUSTER_FAILOVER\n");
-  if (ds->allow_reader_connections) printf("\tALLOW_READER_CONNECTIONS\n");
-  if (ds->enable_strict_reader_failover) printf("\tENABLE_STRICT_READER_FAILOVER\n");
+  if (ds->failover_mode) printf("\tFAILOVER_MODE\n");
   if (ds->gather_perf_metrics) printf("\tGATHER_PERF_METRICS\n");
   if (ds->gather_metrics_per_instance) printf("\tGATHER_METRICS_PER_INSTANCE\n");
   if (ds->topology_refresh_rate) printf("\tTOPOLOGY_REFRESH_RATE=%d\n", ds->topology_refresh_rate);

integration/connection_string_builder.h

@@ -42,16 +42,16 @@ class ConnectionString {
     friend class ConnectionStringBuilder;
 
     ConnectionString() : m_dsn(""), m_server(""), m_port(-1),
-                         m_uid(""), m_pwd(""), m_db(""), m_log_query(true), m_allow_reader_connections(false),
-                         m_enable_strict_reader_failover(false), m_multi_statements(false), m_enable_cluster_failover(true),
+                         m_uid(""), m_pwd(""), m_db(""), m_log_query(true),
+                         m_failover_mode(""), m_multi_statements(false), m_enable_cluster_failover(true),
                          m_failover_timeout(-1), m_connect_timeout(-1), m_network_timeout(-1), m_host_pattern(""),
                          m_enable_failure_detection(true), m_failure_detection_time(-1), m_failure_detection_timeout(-1),
                          m_failure_detection_interval(-1), m_failure_detection_count(-1), m_monitor_disposal_time(-1),
                          m_read_timeout(-1), m_write_timeout(-1), m_auth_mode(""), m_auth_region(""), m_auth_host(""),
                          m_auth_port(-1), m_auth_expiration(-1), m_secret_id(""),
 
                          is_set_uid(false), is_set_pwd(false), is_set_db(false), is_set_log_query(false),
-                         is_set_allow_reader_connections(false), is_set_enable_strict_reader_failover(false),
+                         is_set_failover_mode(false),
                          is_set_multi_statements(false), is_set_enable_cluster_failover(false),
                          is_set_failover_timeout(false), is_set_connect_timeout(false), is_set_network_timeout(false), is_set_host_pattern(false),
                          is_set_enable_failure_detection(false), is_set_failure_detection_time(false), is_set_failure_detection_timeout(false),
@@ -76,11 +76,8 @@ class ConnectionString {
       if (is_set_log_query) {
         length += sprintf(conn_in + length, "LOG_QUERY=%d;", m_log_query ? 1 : 0); 
       }
-      if (is_set_allow_reader_connections) {
-        length += sprintf(conn_in + length, "ALLOW_READER_CONNECTIONS=%d;", m_allow_reader_connections ? 1 : 0); 
-      }
-      if (is_set_enable_strict_reader_failover) {
-        length += sprintf(conn_in + length, "ENABLE_STRICT_READER_FAILOVER=%d;", m_enable_strict_reader_failover ? 1 : 0);
+      if (is_set_failover_mode) {
+        length += sprintf(conn_in + length, "failover_mode=%s;", m_failover_mode.c_str());
       }
       if (is_set_multi_statements) {
         length += sprintf(conn_in + length, "MULTI_STATEMENTS=%d;", m_multi_statements ? 1 : 0);
@@ -155,16 +152,16 @@ class ConnectionString {
 
     // Optional fields
     std::string m_uid, m_pwd, m_db;
-    bool m_log_query, m_allow_reader_connections, m_enable_strict_reader_failover, m_multi_statements, m_enable_cluster_failover;
+    bool m_log_query, m_multi_statements, m_enable_cluster_failover;
     int m_failover_timeout, m_connect_timeout, m_network_timeout;
-    std::string m_host_pattern;
+    std::string m_host_pattern, m_failover_mode;
     bool m_enable_failure_detection;
     int m_failure_detection_time, m_failure_detection_timeout, m_failure_detection_interval, m_failure_detection_count, m_monitor_disposal_time, m_read_timeout, m_write_timeout;
     std::string m_auth_mode, m_auth_region, m_auth_host, m_secret_id;
     int m_auth_port, m_auth_expiration;
 
     bool is_set_uid, is_set_pwd, is_set_db;
-    bool is_set_log_query, is_set_allow_reader_connections, is_set_enable_strict_reader_failover, is_set_multi_statements;
+    bool is_set_log_query, is_set_failover_mode, is_set_multi_statements;
     bool is_set_enable_cluster_failover;
     bool is_set_failover_timeout, is_set_connect_timeout, is_set_network_timeout;
     bool is_set_host_pattern;
@@ -206,14 +203,9 @@ class ConnectionString {
       is_set_log_query = true;
     }
 
-    void set_allow_reader_connections(const bool& allow_reader_connections) {
-      m_allow_reader_connections = allow_reader_connections;
-      is_set_allow_reader_connections = true;
-    }
-
-    void set_enable_strict_reader_failover(const bool& enable_strict_reader_failover) {
-      m_enable_strict_reader_failover = enable_strict_reader_failover;
-      is_set_enable_strict_reader_failover = true;
+    void set_failover_mode(const std::string& failover_mode) {
+      m_failover_mode = failover_mode;
+      is_set_failover_mode = true;
     }
 
     void set_multi_statements(const bool& multi_statements) {
@@ -358,13 +350,8 @@ class ConnectionStringBuilder {
       return *this;
     }
 
-    ConnectionStringBuilder& withAllowReaderConnections(const bool& allow_reader_connections) {
-      connection_string->set_allow_reader_connections(allow_reader_connections);
-      return *this;
-    }
-
-    ConnectionStringBuilder& withEnableStrictReaderFailover(const bool& enable_strict_reader_failover) {
-      connection_string->set_enable_strict_reader_failover(enable_strict_reader_failover);
+    ConnectionStringBuilder& withFailoverMode(const std::string& failover_mode) {
+      connection_string->set_failover_mode(failover_mode);
       return *this;
     }
 

integration/connection_string_builder_test.cc

@@ -71,8 +71,6 @@ TEST_F(ConnectionStringBuilderTest, test_complete_string) {
                                    .withUID("testUser")
                                    .withPWD("testPwd")
                                    .withLogQuery(false)
-                                   .withAllowReaderConnections(true)
-                                   .withEnableStrictReaderFailover(true)
                                    .withMultiStatements(false)
                                    .withDSN("testDSN")
                                    .withFailoverTimeout(120000)
@@ -89,7 +87,7 @@ TEST_F(ConnectionStringBuilderTest, test_complete_string) {
                                    .withEnableClusterFailover(true)
                                    .build();
 
-  const std::string expected = "DSN=testDSN;SERVER=testServer;PORT=3306;UID=testUser;PWD=testPwd;DATABASE=testDb;LOG_QUERY=0;ALLOW_READER_CONNECTIONS=1;ENABLE_STRICT_READER_FAILOVER=1;MULTI_STATEMENTS=0;ENABLE_CLUSTER_FAILOVER=1;FAILOVER_TIMEOUT=120000;CONNECT_TIMEOUT=20;NETWORK_TIMEOUT=20;HOST_PATTERN=?.testDomain;ENABLE_FAILURE_DETECTION=1;FAILURE_DETECTION_TIME=10000;FAILURE_DETECTION_INTERVAL=100;FAILURE_DETECTION_COUNT=4;MONITOR_DISPOSAL_TIME=300;";
+  const std::string expected = "DSN=testDSN;SERVER=testServer;PORT=3306;UID=testUser;PWD=testPwd;DATABASE=testDb;LOG_QUERY=0;MULTI_STATEMENTS=0;ENABLE_CLUSTER_FAILOVER=1;FAILOVER_TIMEOUT=120000;CONNECT_TIMEOUT=20;NETWORK_TIMEOUT=20;HOST_PATTERN=?.testDomain;ENABLE_FAILURE_DETECTION=1;FAILURE_DETECTION_TIME=10000;FAILURE_DETECTION_INTERVAL=100;FAILURE_DETECTION_COUNT=4;MONITOR_DISPOSAL_TIME=300;";
   EXPECT_EQ(0, expected.compare(connection_string));
 }
 
@@ -129,13 +127,12 @@ TEST_F(ConnectionStringBuilderTest, test_setting_boolean_fields) {
                                    .withUID("testUser")
                                    .withPWD("testPwd")
                                    .withLogQuery(false)
-                                   .withAllowReaderConnections(true)
                                    .withMultiStatements(true)
                                    .withEnableClusterFailover(false)
                                    .withEnableFailureDetection(true)
                                    .build();
 
-  const std::string expected("DSN=testDSN;SERVER=testServer;PORT=3306;UID=testUser;PWD=testPwd;LOG_QUERY=0;ALLOW_READER_CONNECTIONS=1;MULTI_STATEMENTS=1;ENABLE_CLUSTER_FAILOVER=0;ENABLE_FAILURE_DETECTION=1;");
+  const std::string expected("DSN=testDSN;SERVER=testServer;PORT=3306;UID=testUser;PWD=testPwd;LOG_QUERY=0;MULTI_STATEMENTS=1;ENABLE_CLUSTER_FAILOVER=0;ENABLE_FAILURE_DETECTION=1;");
   EXPECT_EQ(0, expected.compare(connection_string));
 }