LinkMenuExpand(external link)DocumentSearchCopyCopied
MySqlConnector

MySqlConnector vs MySql.Data

Compared to MySql.Data (i.e., Oracle’s MySQL Connector/NET), MySqlConnector has the following benefits:

Migrating from Connector/NET

Namespace

MySqlConnector supports the same core API as MySQL Connector/NET, but the classes are in a different namespace. Change using MySql.Data.MySqlClient; to using MySqlConnector;.

DbProviderFactories

The MySqlClientFactory type is named MySqlConnectorFactory in MySqlConnector.

In a .NET Framework application, make the following app.config change to register MySqlConnector instead of MySql.Data.

<system.data>
  <DbProviderFactories>
    <!-- REMOVE THIS -->
    <!-- add name="MySQL Data Provider"
      invariant="MySql.Data.MySqlClient"
      description=".Net Framework Data Provider for MySQL"
      type="MySql.Data.MySqlClient.MySqlClientFactory, MySql.Data, Version=9.1.0.0, Culture=neutral, PublicKeyToken=c5687fc88969c44d" / -->

    <!-- ADD THIS -->
    <add name="MySqlConnector"
      invariant="MySqlConnector"
      description="MySQL Connector for .NET"
      type="MySqlConnector.MySqlConnectorFactory, MySqlConnector, Culture=neutral, PublicKeyToken=d33d3e53aa5f8c92" />
  </DbProviderFactories>
</system.data>

Connection String Differences

MySqlConnector has some different default connection string options:

OptionMySqlConnectorOracle’s Connector/NETNotes
CharacterSet, CharSetIgnored; utf8mb4 is always used(server-defined)MySqlConnector always uses utf8mb4 to send and receive strings from MySQL Server. This option may be specified (for backwards compatibility) but it will be ignored.
ConnectionResetDefault is trueDefault is falseMySqlConnector always resets pooled connections by default so that the connection is in a known state. This fixes MySQL Bug 77421.
IgnoreCommandTransactionDefault is false(not configurable, effective default is true)See remarks under MySqlCommand below.
IgnorePrepareDefault is falsetrue for ≤ 8.0.22; false for ≥ 8.0.23This is a change if migrating from an older version of Connector/NET.
LoadBalanceDefault is RoundRobin(not configurable, effective default is FailOver)Connector/NET versions prior to v8.0.19 have a bug that prevents multiple host names being used.
ServerRSAPublicKeyFile(no default)(not configurable)Specify a file containing the server’s RSA public key to allow sha256_password authentication over an insecure connection.

Connector/NET uses CertificateFile to specify the client’s private key, unless SslCert and SslKey are specified, in which case it is used to specify the server’s CA certificate file; SslCa is just an alias for this option. MySqlConnector always uses CertificateFile for the client’s private key (in PFX format); SslCa (aka CACertificateFile) is a separate option to specify the server’s CA certificate.

Some connection string options that are supported in Connector/NET are not supported in MySqlConnector. For a full list of options that are supported in MySqlConnector, see the Connection Options.

Async

Connector/NET implements the standard ADO.NET async methods, and adds some new ones (e.g., MySqlConnection.BeginTransactionAsync, MySqlDataAdapter.FillAsync) that don’t exist in ADO.NET. None of these methods have an asynchronous implementation, but all execute synchronously then return a completed Task. This longstanding known bug was fixed in in Connector/NET v8.0.33.

Because the Connector/NET methods aren’t actually asynchronous, porting client code to MySqlConnector (which is asynchronous) can expose bugs that only occur when an async method completes asynchronously and resumes the await-ing code on a background thread. To avoid deadlocks, make sure to never block on async code (e.g., with .Result), use async all the way, use ConfigureAwait correctly, and follow the best practices in async programming.

Implicit Conversions

Prior to v8.3.0, Connector/NET allows MySqlDataReader.GetString() to be called on many non-textual columns, and will implicitly convert the value to a string (using the current locale). This is a frequent source of locale-dependent bugs, so MySqlConnector follows typical ADO.NET practice (e.g., SqlClient, npgsql) and disallows this (by throwing an InvalidCastException).

To fix this, use the accessor method (e.g., GetInt32, GetDouble) that matches the column type, or perform an explicit conversion to string by calling GetValue(x).ToString() (optionally supplying the right CultureInfo to use for formatting).

TransactionScope

MySqlConnector adds full distributed transaction support (for client code using System.Transactions.Transaction), while Connector/NET uses regular database transactions. As a result, code that uses TransactionScope or MySqlConnection.EnlistTransaction may execute differently with MySqlConnector. To get Connector/NET-compatible behavior, set UseXaTransactions=false in your connection string.

MySqlConnection

Connector/NET allows a MySqlConnection object to be reused after it has been disposed. MySqlConnector requires a new MySqlConnection object to be created. See #331 for more details.

The return value of MySqlConnection.BeginTransactionAsync has changed from Task<MySqlTransaction> to ValueTask<MySqlTransaction> to match the standard API in .NET Core 3.0. (This method does always perform I/O, so ValueTask is not an optimization for MySqlConnector.)

MySqlConnectionStringBuilder

All string properties on MySqlConnectionStringBuilder will return the empty string (instead of null) if the property isn’t set.

MySqlCommand

Connector/NET allows a command to be executed even when MySqlCommand.Transaction references a commited, rolled back, or disposed MySqlTransaction. MySqlConnector will throw an InvalidOperationException if the MySqlCommand.Transaction property doesn’t reference the active transaction. This fixes MySQL Bug 88611. To disable this strict validation, set IgnoreCommandTransaction=true in the connection string. See Transaction Usage for more details.

If MySqlCommand.CommandType is CommandType.StoredProcedure, the stored procedure name assigned to MySqlCommand.CommandText must have any special characters escaped or quoted. Connector/NET will automatically quote some characters (such as spaces); MySqlConnector leaves this up to the developer.

MySqlDataAdapter

Connector/NET provides MySqlDataAdapter.FillAsync, FillSchemaAsync, and UpdateAsync methods, but these methods have a synchronous implementation. MySqlConnector only adds “Async” methods when they can be implemented asynchronously. This functionality depends on dotnet/runtime#22109 being implemented first. To migrate code, change it to call the synchronous methods instead.

MySqlGeometry

The Connector/NET MySqlGeometry type assumes that the geometry can only be a simple point. MySqlConnector removes most of the API that is based on those assumptions.

To avoid ambiguity, there are two different factory methods for constructing a MySqlGeometry. Use the static factory method MySqlGeometry.FromMySql (if you have a byte array containing MySQL’s internal format), or FromWkb if you have Well-known Binary bytes.

MySqlInfoMessageEventArgs

The MySqlError[] MySqlInfoMessageEventArgs.errors property has changed to IReadOnlyList<MySqlError> MySqlInfoMessageEventArgs.Errors.

MySqlParameter

Connector/NET will automatically convert unknown MySqlParameter.Value values to a string by calling ToString(), then convert that to bytes by calling Encoding.GetBytes() using the packet’s encoding. This is error-prone and can introduce culture-sensitive conversions.

MySqlConnector requires all parameter values to be of a known, supported type. See MySqlParameter Types for details.

MySqlParameterCollection

Connector/NET will assign the names @Parameter1, @Parameter2, etc. to unnamed MySqlParameter objects that are added to the MySqlCommand.Parameters parameter collection. These generated names may be used in the SQL assigned to MySqlCommand.CommandText. MySqlConnector requires all MySqlParameter objects to be explicitly given a name, or used only as positional parameters if they’re unnamed.

Exceptions

For consistency with other ADO.NET providers, MySqlConnector will throw InvalidOperationException (instead of MySqlException) for various precondition checks that indicate misuse of the API (and not a problem related to MySQL Server).

Fixed Bugs

The following bugs in Connector/NET are fixed by switching to MySqlConnector.

Open Bugs

Fixed First by MySqlConnector

These bugs are fixed in the latest version of MySQL Connector/NET, but were fixed first in MySqlConnector.