Throw better exception if DELIMITER is used. Fixes #1010

Author: bgrainger

docs/content/troubleshooting/datetime-storage.md

@@ -1,7 +1,7 @@
 ---
 date: 2020-02-08
 title: DateTime Storage
-weight: 20
+weight: 24
 menu:
   main:
     parent: troubleshooting

docs/content/troubleshooting/delimiter.md

@@ -0,0 +1,51 @@
+---
+date: 2021-07-27
+title: Delimiter
+customtitle: "Fix: Using DELIMITER in SQL"
+weight: 28
+menu:
+  main:
+    parent: troubleshooting
+---
+
+# Fix: Using DELIMITER in SQL
+
+In MySQL Workbench, it's common to use `DELIMITER $$` (or similar) when defining stored procedures or using other compound statements that include an embedded semicolon (`;`).
+
+This is not required by MySQL Server, but is a workaround for [limitations in the mysql client](https://dev.mysql.com/doc/refman/8.0/en/stored-programs-defining.html):
+
+> By default, mysql itself recognizes the semicolon as a statement delimiter, so you must redefine the delimiter temporarily to cause mysql to pass the entire stored program definition to the server.
+
+This limitation does not exist in MySqlConnector, so using `DELIMITER` is unnecessary and it must be removed (to avoid sending invalid SQL to the server).
+
+## Incorrect Code
+
+```csharp
+using var command = connection.CreateCommand();
+command.CommandText = @"
+DELIMITER $$
+CREATE FUNCTION echo(
+  name VARCHAR(63)
+) RETURNS VARCHAR(63)
+BEGIN
+    RETURN name;
+END
+$$";
+command.ExecuteNonQuery();
+```
+
+## Fixed Code
+
+To fix the problem, remove the `DELIMITER` declaration and any trailing instances of the delimiter:
+
+```csharp
+using var command = connection.CreateCommand();
+command.CommandText = @"
+CREATE FUNCTION echo(
+  name VARCHAR(63)
+) RETURNS VARCHAR(63)
+BEGIN
+    RETURN name;
+END;";
+command.ExecuteNonQuery();
+```

src/MySqlConnector/Core/ServerSession.cs

@@ -216,7 +216,17 @@ public async Task PrepareAsync(IMySqlCommand command, IOBehavior ioBehavior, Can
 			foreach (var statement in parsedStatements.Statements)
 			{
 				await SendAsync(new PayloadData(statement.StatementBytes), ioBehavior, cancellationToken).ConfigureAwait(false);
-				var payload = await ReceiveReplyAsync(ioBehavior, cancellationToken).ConfigureAwait(false);
+				PayloadData payload;
+				try
+				{
+					payload = await ReceiveReplyAsync(ioBehavior, cancellationToken).ConfigureAwait(false);
+				}
+				catch (MySqlException exception)
+				{
+					ThrowIfStatementContainsDelimiter(exception, command);
+					throw;
+				}
+
 				var response = StatementPrepareResponsePayload.Create(payload.Span);
 
 				ColumnDefinitionPayload[]? parameters = null;
@@ -918,6 +928,18 @@ private async ValueTask<int> SendReplyAsyncAwaited(ValueTask<int> task)
 			}
 		}
 
+		public static void ThrowIfStatementContainsDelimiter(MySqlException exception, IMySqlCommand command)
+		{
+			// check if the command used "DELIMITER"
+			if (exception.ErrorCode == MySqlErrorCode.ParseError && command.CommandText?.IndexOf("delimiter", StringComparison.OrdinalIgnoreCase) >= 0)
+			{
+				var parser = new DelimiterSqlParser(command);
+				parser.Parse(command.CommandText);
+				if (parser.HasDelimiter)
+					throw new MySqlException(MySqlErrorCode.DelimiterNotSupported, "'DELIMITER' should not be used with MySqlConnector. See https://fl.vu/mysql-delimiter", exception);
+			}
+		}
+
 		internal void HandleTimeout()
 		{
 			if (OwningConnection is not null && OwningConnection.TryGetTarget(out var connection))
@@ -1738,6 +1760,25 @@ private enum State
 			Failed,
 		}
 
+		private sealed class DelimiterSqlParser : SqlParser
+		{
+			public DelimiterSqlParser(IMySqlCommand command)
+				: base(new StatementPreparer(command.CommandText!, null, command.CreateStatementPreparerOptions()))
+			{
+				m_sql = command.CommandText!;
+			}
+
+			public bool HasDelimiter { get; private set; }
+
+			protected override void OnStatementBegin(int index)
+			{
+				if (index + 10 < m_sql.Length && string.Equals("delimiter ", m_sql.Substring(index, 10), StringComparison.OrdinalIgnoreCase))
+					HasDelimiter = true;
+			}
+
+			readonly string m_sql;
+		}
+
 		static ReadOnlySpan<byte> BeginCertificateBytes => new byte[] { 45, 45, 45, 45, 45, 66, 69, 71, 73, 78, 32, 67, 69, 82, 84, 73, 70, 73, 67, 65, 84, 69, 45, 45, 45, 45, 45 }; // -----BEGIN CERTIFICATE-----
 		static int s_lastId;
 		static readonly IMySqlConnectorLogger Log = MySqlConnectorLogManager.CreateLogger(nameof(ServerSession));

src/MySqlConnector/MySqlDataReader.cs

@@ -132,7 +132,11 @@ private void ActivateResultSet(CancellationToken cancellationToken)
 					throw MySqlException.CreateForTimeout(mySqlException);
 
 				if (mySqlException is not null)
+				{
+					ServerSession.ThrowIfStatementContainsDelimiter(mySqlException, Command!);
+
 					m_resultSet.ReadResultSetHeaderException.Throw();
+				}
 
 				throw new MySqlException("Failed to read the result set.", m_resultSet.ReadResultSetHeaderException.SourceException);
 			}

src/MySqlConnector/MySqlErrorCode.g.cs

@@ -6,6 +6,8 @@ namespace MySqlConnector
 	[System.CodeDom.Compiler.GeneratedCode("https://gist.github.com/bgrainger/791cecb647d514a9dd2f3d83b2387e49", "2")]
 	public enum MySqlErrorCode
 	{
+		DelimiterNotSupported = -3,
+
 		/// <summary>
 		/// Not all rows from the source supplied to <see cref="MySqlBulkCopy"/> were copied to <see cref="MySqlBulkCopy.DestinationTableName"/>.
 		/// </summary>

tests/SideBySide/QueryTests.cs

@@ -1253,6 +1253,41 @@ public void GetIntForTinyInt1(bool treatTinyAsBoolean, bool prepare)
 			Assert.False(reader.Read());
 		}
 
+		[Theory]
+		[InlineData(false, false)]
+		[InlineData(true, false)]
+		[InlineData(false, true)]
+		[InlineData(true, true)]
+		public async Task Delimiter(bool prepareCommand, bool isAsync)
+		{
+			using var command = m_database.Connection.CreateCommand();
+			command.CommandText = @"DELIMITER $$
+CREATE FUNCTION echo(
+  name VARCHAR(63)
+) RETURNS VARCHAR(63)
+BEGIN
+    RETURN name;
+END
+$$";
+			MySqlException exception;
+			if (prepareCommand)
+			{
+				exception = isAsync ? (await Assert.ThrowsAsync<MySqlException>(async () => await command.PrepareAsync())) :
+					Assert.Throws<MySqlException>(() => command.Prepare());
+			}
+			else
+			{
+				exception = isAsync ? (await Assert.ThrowsAsync<MySqlException>(async () => await command.ExecuteNonQueryAsync())) :
+					Assert.Throws<MySqlException>(() => command.ExecuteNonQuery());
+			}
+
+#if !BASELINE
+			Assert.Equal(MySqlErrorCode.DelimiterNotSupported, exception.ErrorCode);
+#else
+			Assert.Equal((int) MySqlErrorCode.ParseError, exception.Number);
+#endif
+		}
+
 #if !NETCOREAPP1_1_2
 		[Fact]
 		public void QueryDateTimeLiteral()