Implement ENABLE_STRICT_READER_FAILOVER user parameter (#136)

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

@@ -33,6 +33,7 @@ In addition to the parameters that you can configure for the [MySQL Connector/OD
 | ---------------------------------- |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------|----------|------------------------------------------|
 | `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`                                      |
 | `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

@@ -73,6 +73,7 @@ class FAILOVER_READER_HANDLER {
         std::shared_ptr<TOPOLOGY_SERVICE> topology_service,
         std::shared_ptr<CONNECTION_HANDLER> connection_handler,
         int failover_timeout_ms, int failover_reader_connect_timeout,
+        bool enable_strict_reader_failover,
         unsigned long dbc_id, bool enable_logging = false);
 
         ~FAILOVER_READER_HANDLER();
@@ -100,6 +101,7 @@ class FAILOVER_READER_HANDLER {
         std::shared_ptr<TOPOLOGY_SERVICE> topology_service;
         std::shared_ptr<CONNECTION_HANDLER> connection_handler; 
         const int READER_CONNECT_INTERVAL_SEC = 1;  // 1 sec
+        bool enable_strict_reader_failover = false;
         std::shared_ptr<FILE> logger = nullptr;
         unsigned long dbc_id = 0;
 };

driver/failover_handler.cc

@@ -81,7 +81,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, ds->failover_timeout,
-        ds->failover_reader_connect_timeout, dbc->id, ds->save_queries);
+        ds->failover_reader_connect_timeout, ds->enable_strict_reader_failover,
+        dbc->id, ds->save_queries);
     this->failover_writer_handler = std::make_shared<FAILOVER_WRITER_HANDLER>(
         this->topology_service, this->failover_reader_handler,
         this->connection_handler, ds->failover_timeout,

driver/failover_reader_handler.cc

@@ -40,11 +40,13 @@ FAILOVER_READER_HANDLER::FAILOVER_READER_HANDLER(
     std::shared_ptr<TOPOLOGY_SERVICE> topology_service,
     std::shared_ptr<CONNECTION_HANDLER> connection_handler,
     int failover_timeout_ms, int failover_reader_connect_timeout,
+    bool enable_strict_reader_failover,
     unsigned long dbc_id, bool enable_logging)
     : topology_service{topology_service},
       connection_handler{connection_handler},
       max_failover_timeout_ms{failover_timeout_ms},
       reader_connect_timeout_ms{failover_reader_connect_timeout},
+      enable_strict_reader_failover{enable_strict_reader_failover},
       dbc_id{dbc_id} {
 
     if (enable_logging)
@@ -69,7 +71,7 @@ READER_FAILOVER_RESULT FAILOVER_READER_HANDLER::failover(
     auto reader_result_future = std::async(std::launch::async, [=, &global_sync, &reader_result]() {
         std::vector<std::shared_ptr<HOST_INFO>> hosts_list;
         while (!global_sync.is_completed()) {
-            hosts_list = build_hosts_list(current_topology, true);
+            hosts_list = build_hosts_list(current_topology, !enable_strict_reader_failover);
             reader_result = get_connection_from_hosts(hosts_list, global_sync);
             if (reader_result.connected) {
                 global_sync.mark_as_complete(true);

installer/myodbc-installer.cc

@@ -579,6 +579,7 @@ int list_datasource_details(DataSource *ds)
   /* 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->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

@@ -43,15 +43,16 @@ class ConnectionString {
 
     ConnectionString() : m_dsn(""), m_server(""), m_port(-1),
                          m_uid(""), m_pwd(""), m_db(""), m_log_query(true), m_allow_reader_connections(false),
-                         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_strict_reader_failover(false), 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_multi_statements(false), is_set_enable_cluster_failover(false),
+                         is_set_allow_reader_connections(false), is_set_enable_strict_reader_failover(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),
                          is_set_failure_detection_interval(false), is_set_failure_detection_count(false), is_set_monitor_disposal_time(false),
@@ -78,6 +79,9 @@ class ConnectionString {
       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_multi_statements) {
         length += sprintf(conn_in + length, "MULTI_STATEMENTS=%d;", m_multi_statements ? 1 : 0);
       }
@@ -151,7 +155,7 @@ class ConnectionString {
 
     // Optional fields
     std::string m_uid, m_pwd, m_db;
-    bool m_log_query, m_allow_reader_connections, m_multi_statements, m_enable_cluster_failover;
+    bool m_log_query, m_allow_reader_connections, m_enable_strict_reader_failover, m_multi_statements, m_enable_cluster_failover;
     int m_failover_timeout, m_connect_timeout, m_network_timeout;
     std::string m_host_pattern;
     bool m_enable_failure_detection;
@@ -160,7 +164,7 @@ class ConnectionString {
     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_multi_statements;
+    bool is_set_log_query, is_set_allow_reader_connections, is_set_enable_strict_reader_failover, 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;
@@ -207,6 +211,11 @@ class ConnectionString {
       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_multi_statements(const bool& multi_statements) {
       m_multi_statements = multi_statements;
       is_set_multi_statements = true;
@@ -354,6 +363,11 @@ class ConnectionStringBuilder {
       return *this;
     }
 
+    ConnectionStringBuilder& withEnableStrictReaderFailover(const bool& enable_strict_reader_failover) {
+      connection_string->set_enable_strict_reader_failover(enable_strict_reader_failover);
+      return *this;
+    }
+
     ConnectionStringBuilder& withMultiStatements(const bool& multi_statements) {
       connection_string->set_multi_statements(multi_statements);
       return *this;

integration/connection_string_builder_test.cc

@@ -72,6 +72,7 @@ TEST_F(ConnectionStringBuilderTest, test_complete_string) {
                                    .withPWD("testPwd")
                                    .withLogQuery(false)
                                    .withAllowReaderConnections(true)
+                                   .withEnableStrictReaderFailover(true)
                                    .withMultiStatements(false)
                                    .withDSN("testDSN")
                                    .withFailoverTimeout(120000)
@@ -88,7 +89,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;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;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;";
   EXPECT_EQ(0, expected.compare(connection_string));
 }
 

integration/network_failover_integration_test.cc

@@ -165,6 +165,20 @@ TEST_F(NetworkFailoverIntegrationTest, lost_connection_to_all_readers) {
   EXPECT_EQ(SQL_SUCCESS, SQLDisconnect(dbc));
 }
 
+TEST_F(NetworkFailoverIntegrationTest, lost_connection_to_all_readers_strict_reader_failover) {
+  connection_string = builder.withServer(reader_endpoint).withAllowReaderConnections(true).withEnableStrictReaderFailover(true).build();
+  EXPECT_EQ(SQL_SUCCESS, SQLDriverConnect(dbc, nullptr, AS_SQLCHAR(connection_string.c_str()), SQL_NTS, conn_out, MAX_NAME_LEN, &len, SQL_DRIVER_NOPROMPT));
+
+  for (const auto& x : proxy_map) {
+    if (x.first != writer_id) {
+        disable_connectivity(x.second);
+    }
+  }
+
+  assert_query_failed(dbc, SERVER_ID_QUERY, ERROR_COMM_LINK_FAILURE);
+  EXPECT_EQ(SQL_SUCCESS, SQLDisconnect(dbc));
+}
+
 TEST_F(NetworkFailoverIntegrationTest, lost_connection_to_reader_instance) {
   connection_string = builder.withServer(reader_endpoint).build();
   EXPECT_EQ(SQL_SUCCESS, SQLDriverConnect(dbc, nullptr, AS_SQLCHAR(connection_string.c_str()), SQL_NTS, conn_out, MAX_NAME_LEN, &len, SQL_DRIVER_NOPROMPT));

setupgui/callbacks.cc

@@ -315,6 +315,10 @@ void syncTabsData(HWND hwnd, DataSource *params)
   /* 4 - Failover */
   GET_BOOL_TAB(FAILOVER_TAB, enable_cluster_failover);
   GET_BOOL_TAB(FAILOVER_TAB, allow_reader_connections);
+  if (READ_BOOL_TAB(FAILOVER_TAB, allow_reader_connections))
+  {
+      GET_BOOL_TAB(FAILOVER_TAB, enable_strict_reader_failover);
+  }
   GET_BOOL_TAB(FAILOVER_TAB, gather_perf_metrics);
   if (READ_BOOL_TAB(FAILOVER_TAB, gather_perf_metrics))
   {
@@ -453,6 +457,15 @@ void syncTabs(HWND hwnd, DataSource *params)
   /* 4 - Failover */
   SET_BOOL_TAB(FAILOVER_TAB, enable_cluster_failover);
   SET_BOOL_TAB(FAILOVER_TAB, allow_reader_connections);
+  if (READ_BOOL_TAB(FAILOVER_TAB, allow_reader_connections))
+  {
+#ifdef _WIN32
+      SET_ENABLED(FAILOVER_TAB, IDC_CHECK_enable_strict_reader_failover, TRUE);
+#endif
+      SET_CHECKED_TAB(FAILOVER_TAB, allow_reader_connections, TRUE);
+      SET_BOOL_TAB(FAILOVER_TAB, enable_strict_reader_failover);
+  }
+  SET_BOOL_TAB(FAILOVER_TAB, enable_strict_reader_failover);
   SET_BOOL_TAB(FAILOVER_TAB, gather_perf_metrics);
   if(READ_BOOL_TAB(FAILOVER_TAB, gather_perf_metrics))
   {

setupgui/windows/odbcdialogparams.cpp

@@ -704,6 +704,18 @@ void FormMain_OnCommand(HWND hwnd, int id, HWND hwndCtl, UINT codeNotify)
         EnableWindow(secret_id, usingSecretsManager);
       }
       break;
+    case IDC_CHECK_allow_reader_connections:
+    {
+        HWND failoverTab = TabCtrl_1.hTabPages[FAILOVER_TAB - 1];
+        assert(failoverTab);
+        HWND prefetch = GetDlgItem(failoverTab, IDC_CHECK_enable_strict_reader_failover);
+        assert(prefetch);
+
+        EnableWindow(prefetch, !!Button_GetCheck(GetDlgItem(failoverTab,
+            IDC_CHECK_allow_reader_connections)));
+        setBoolFieldData(failoverTab, IDC_CHECK_enable_strict_reader_failover, Button_GetCheck(prefetch));
+    }
+    break;
     case IDC_CHECK_gather_perf_metrics:
       {
         HWND failoverTab = TabCtrl_1.hTabPages[FAILOVER_TAB-1];