Add ConnectionIdlePingTime setting.

This allows clients to opt-out of pinging the server when a connection is retrieved from the pool, if it's been idle less than a certain amount of time.

Author: bgrainger

docs/content/connection-options.md

@@ -117,6 +117,19 @@ Connection pooling is enabled by default. These options are used to configure it
     <td><code>true</code></td>
     <td>If <code>true</code>, the connection state is reset when it is retrieved from the pool. The default value of <code>true</code> ensures that the connection is in the same state whether it's newly created or retrieved from the pool. A value of <code>false</code> avoids making an additional server round trip when obtaining a connection, but the connection state is not reset, meaning that session variables and other session state changes from any previous use of the connection are carried over.</td>
   </tr>
+  <tr>
+    <td>Connection Idle Ping Time, Connection Idle Ping Time <em>(Experimental)</em></td>
+    <td>0</td>
+    <td>When a connection is retrieved from the pool, and <code>ConnectionReset</code> is <code>false</code>, the server
+      will be pinged if the connection has been idle in the pool for longer than <code>ConnectionIdlePingTime</code> seconds.
+      If pinging the server fails, a new connection will be opened automatically by the connection pool. This ensures that the
+      <code>MySqlConnection</code> is in a valid, open state after the call to <code>Open</code>/<code>OpenAsync</code>,
+      at the cost of an extra server roundtrip. For high-performance scenarios, you may wish to set <code>ConnectionIdlePingTime</code>
+      to a non-zero value to make the connection pool assume that recently-returned connections are still open. If the
+      connection is broken, it will throw from the first call to <code>ExecuteNonQuery</code>, <code>ExecuteReader</code>,
+      etc.; your code should handle that failure and retry the connection. This option has no effect if <code>ConnectionReset</code>
+      is <code>true</code>, as that will cause a connection reset packet to be sent to the server, making ping redundant.
+  </tr>
   <tr>
     <td>Connection Idle Timeout, ConnectionIdleTimeout</td>
     <td>180</td>

src/MySqlConnector/Core/ConnectionPool.cs

@@ -68,10 +68,14 @@ public async ValueTask<ServerSession> GetSessionAsync(MySqlConnection connection
 						{
 							reuseSession = await session.TryResetConnectionAsync(ConnectionSettings, ioBehavior, cancellationToken).ConfigureAwait(false);
 						}
-						else
+						else if ((unchecked((uint) Environment.TickCount) - session.LastReturnedTicks) > ConnectionSettings.ConnectionIdlePingTime)
 						{
 							reuseSession = await session.TryPingAsync(ioBehavior, cancellationToken).ConfigureAwait(false);
 						}
+						else
+						{
+							reuseSession = true;
+						}
 					}
 
 					if (!reuseSession)

src/MySqlConnector/Core/ConnectionSettings.cs

@@ -42,6 +42,7 @@ public ConnectionSettings(MySqlConnectionStringBuilder csb)
 			Pooling = csb.Pooling;
 			ConnectionLifeTime = Math.Min(csb.ConnectionLifeTime, uint.MaxValue / 1000) * 1000;
 			ConnectionReset = csb.ConnectionReset;
+			ConnectionIdlePingTime = Math.Min(csb.ConnectionIdlePingTime, uint.MaxValue / 1000) * 1000;
 			ConnectionIdleTimeout = (int)csb.ConnectionIdleTimeout;
 			if (csb.MinimumPoolSize > csb.MaximumPoolSize)
 				throw new MySqlException("MaximumPoolSize must be greater than or equal to MinimumPoolSize");
@@ -92,6 +93,7 @@ public ConnectionSettings(MySqlConnectionStringBuilder csb)
 		public bool Pooling { get; }
 		public uint ConnectionLifeTime { get; }
 		public bool ConnectionReset { get; }
+		public uint ConnectionIdlePingTime { get; }
 		public int ConnectionIdleTimeout { get; }
 		public int MinimumPoolSize { get; }
 		public int MaximumPoolSize { get; }

src/MySqlConnector/MySql.Data.MySqlClient/MySqlConnectionStringBuilder.cs

@@ -98,6 +98,12 @@ public bool ConnectionReset
 			set => MySqlConnectionStringOption.ConnectionReset.SetValue(this, value);
 		}
 
+		public uint ConnectionIdlePingTime
+		{
+			get => MySqlConnectionStringOption.ConnectionIdlePingTime.GetValue(this);
+			set => MySqlConnectionStringOption.ConnectionIdlePingTime.SetValue(this, value);
+		}
+
 		public uint ConnectionIdleTimeout
 		{
 			get => MySqlConnectionStringOption.ConnectionIdleTimeout.GetValue(this);
@@ -270,6 +276,7 @@ internal abstract class MySqlConnectionStringOption
 		public static readonly MySqlConnectionStringOption<bool> Pooling;
 		public static readonly MySqlConnectionStringOption<uint> ConnectionLifeTime;
 		public static readonly MySqlConnectionStringOption<bool> ConnectionReset;
+		public static readonly MySqlConnectionStringOption<uint> ConnectionIdlePingTime;
 		public static readonly MySqlConnectionStringOption<uint> ConnectionIdleTimeout;
 		public static readonly MySqlConnectionStringOption<uint> MinimumPoolSize;
 		public static readonly MySqlConnectionStringOption<uint> MaximumPoolSize;
@@ -372,6 +379,10 @@ static MySqlConnectionStringOption()
 				keys: new[] { "Connection Reset", "ConnectionReset" },
 				defaultValue: true));
 
+			AddOption(ConnectionIdlePingTime = new MySqlConnectionStringOption<uint>(
+				keys: new[] { "Connection Idle Ping Time", "ConnectionIdlePingTime" },
+				defaultValue: 0));
+
 			AddOption(ConnectionIdleTimeout = new MySqlConnectionStringOption<uint>(
 				keys: new[] { "Connection Idle Timeout", "ConnectionIdleTimeout" },
 				defaultValue: 180));

tests/MySqlConnector.Tests/MySqlConnectionStringBuilderTests.cs

@@ -29,6 +29,7 @@ public void Defaults()
 			Assert.Equal("", csb.Database);
 			Assert.Equal(30u, csb.DefaultCommandTimeout);
 #if !BASELINE
+			Assert.Equal(0u, csb.ConnectionIdlePingTime);
 			Assert.Equal(180u, csb.ConnectionIdleTimeout);
 			Assert.False(csb.ForceSynchronous);
 			Assert.Null(csb.CACertificateFile);
@@ -76,6 +77,7 @@ public void ParseConnectionString()
 					"Convert Zero Datetime=true;" +
 					"default command timeout=123;" +
 #if !BASELINE
+					"connection idle ping time=60;" +
 					"connectionidletimeout=30;" +
 					"forcesynchronous=true;" +
 					"ca certificate file=ca.pem;" +
@@ -108,6 +110,7 @@ public void ParseConnectionString()
 			Assert.Equal("schema_name", csb.Database);
 			Assert.Equal(123u, csb.DefaultCommandTimeout);
 #if !BASELINE
+			Assert.Equal(60u, csb.ConnectionIdlePingTime);
 			Assert.Equal(30u, csb.ConnectionIdleTimeout);
 			Assert.True(csb.ForceSynchronous);
 			Assert.Equal("ca.pem", csb.CACertificateFile);