Merge laster master into branch

Author: scottclk

README.md

@@ -22,15 +22,16 @@ Or install it yourself as:
     $ gem install mysql2-aurora
 
 ## Usage
-This gem extends Mysql2::Client. You can use `aurora_max_retry` option.
+This gem extends Mysql2::Client. You can use `aurora_max_retry` and `aurora_disconnect_on_readonly` options.
 
 ```ruby
 Mysql2::Client.new(
   host:             'localhost',
   username:         'root',
   password:         'change_me',
   reconnect:        true,
-  aurora_max_retry: 5
+  aurora_max_retry: 5,
+  aurora_disconnect_on_readonly: true
 )
 ```
 
@@ -44,8 +45,39 @@ development:
   password:         change_me
   reconnect:        true
   aurora_max_retry: 5
+  aurora_disconnect_on_readonly: true
+
 ```
 
+There are essentially two methods for handling and RDS Aurora failover. When there is an Aurora RDS failover event the primary writable server can change it's role to become a read_only replica. This can happen without active database connections droppping.
+This leaves the connection in a state where writes will fail, but the application belives it's connected to a writeable server. Writes will now perpetually fail until the database connection is closed and re-established connecting back to the new primary.
+
+To provide automatic recovery from this method you can use either a graceful retry, or an immediate disconnection option.
+
+### Retry
+
+Setting aurora_max_retry, mysql2 will not disconnect and automatically attempt re-connection to the database when a read_only error message is encountered.
+This has the benefit that to the application the error is transparent and the query will be re-run against the new primary when the connection succeeds.
+
+It is however not safe to use with transactions
+
+Consider:
+
+* Transaction is started on the primary server A
+* Failover event occurs, A is now readonly
+* Application issues a write statement, read_only exception is thrown
+* mysql2-aurora gem handles this by reconnecting transparently to the new primary B
+* Aplication continues issuing writes however on a new connection in auto-commit mode, no new transaction was started
+
+The application remains un-aware it is now operating outside of a transaction, this can leave data in an inconcistent state, and issuing a ROLLBACK, or COMMIT will not have the expected outcome.
+
+### Immediate disconnect
+
+Setting aurora_disconnect_on_readonly to true, will cause mysql2 to close the connection to the database on read_only exception. The original exception will be thrown up the stack to the application.
+With the database connection disconnected, the next statement will hit the disconnected error and the application can handle this as it would normally when been disconnected from the database.
+
+This is safe with transactions.
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/alfa-jpn/mysql2-aurora.