Default: null

This option specifies the path to a certificate file in PKCS #12 format (.pfx). For an example of usage, see Section 6.7.2, “Using PFX Certificates in Connector/NET”.

Default: null

Specifies a password that is used in conjunction with a certificate specified using the option CertificateFile. For an example of usage, see Section 6.7.2, “Using PFX Certificates in Connector/NET”.

Default: null

Enables you to access a certificate held in a personal store, rather than use a certificate file and password combination. For an example of usage, see Section 6.7.2, “Using PFX Certificates in Connector/NET”.

Default: null

Specifies a certificate thumbprint to ensure correct identification of a certificate contained within a personal store. For an example of usage, see Section 6.7.2, “Using PFX Certificates in Connector/NET”.

Specifies the character set that should be used to encode all queries sent to the server. Results are still returned in the character set of the result data.

Default: socket (or tcp)

Specifies the type of connection to make to the server. Values can be:

Default: mysql

The case-sensitive name of the database to use initially.

Default: false

Enables the connection to resolve service (SRV) addresses in a DNS SRV record, which defines the location (host name and port number) of servers for the specified services when it is used with the default transport protocol (tcp). A single DNS domain can map to multiple targets (servers) using SRV address records. Each SRV record includes the host name, port, priority, and weight. DNS SRV support was introduced in Connector/NET 8.0.19 to remove the need for clients to identify each possible host in the connection string, with or without connection pooling.

Specifying multiple host names, a port number, or a Unix socket, named pipe, or shared memory connection (see the ConnectionProtocol option) in the connection string is not permitted when DNS SRV is enabled.

Using classic MySQL protocol.  The dns-srv option applies to connection strings; the DnsSrv property is declared in the MySqlConnectionStringBuilder class.

// Connection string example
 
 var conn = new MySqlConnection("server=_mysql._tcp.example.abc.com.;
                                 dns-srv=true;
                                 user id=user;
                                 password=****;
                                 database=test");


// MySqlConnectionStringBuilder class example
 
 var sb = new MySqlConnectionStringBuilder();
{
  Server = "_mysql._tcp.example.abc.com.",
  UserID = "user",
  Password = "****",
  DnsSrv = true,
  Database = "test"
};

var conn = new MySqlConnection(sb.ConnectionString);

Using X Protocol.  The dns-srv option applies to connection strings and anonymous objects. The DnsSrv property is declared in the MySqlXConnectionStringBuilder class. An error is raised if both dns-srv=false and the URI scheme of mysqlx+srv:// are combined to create a conflicting connection configuration. For details about using the mysqlx+srv:// scheme element in URI-like connection strings, see Connections Using DNS SRV Records.

// Connection string example

var session = MySQLX.GetSession("server=_mysqlx._tcp.example.abc.com.;
                                 dns-srv=true;
                                 user id=user;
                                 password=****;
                                 database=test");


// Anonymous object example

var connstring = new
{
  server = "_mysqlx._tcp.example.abc.com.",
  user = "user",
  password = "****",
  dnssrv = true
};

var session = MySQLX.GetSession(connString);


// MySqlXConnectionStringBuilder class example

var sb = new MySqlXConnectionStringBuilder();
{
  Server = "_mysqlx._tcp.example.abc.com.",
  UserID = "user",
  Password = "****",
  DnsSrv = true,
  Database = "test"
};

var session = MySQLX.GetSession(sb.ConnectionString);

Default: 0

For TCP connections, idle connection time measured in seconds, before the first keepalive packet is sent. A value of 0 indicates that keepalive is not used. Before Connector/NET 6.6.7/6.7.5/6.8.4, this value was measured in milliseconds.

Default: an empty string

The password for the MySQL account being used for one-factor/single-factor authentication (1FA/SFA), which uses only one authentication method such as a password.

Starting with Connector/NET 8.0.28, this option also provides the first secret password for an account that has multiple authentication factors. The server can require one (1FA), two (2FA), or three (3FA) passwords to authenticate the MySQL account. For example, if an account with 2FA is created as follows:

CREATE USER 'abe'@'localhost'
  IDENTIFIED WITH caching_sha2_password
    BY 'sha2_password'
  AND IDENTIFIED WITH authentication_ldap_sasl
    AS 'uid=u1_ldap,ou=People,dc=example,dc=com';

Then your application can specify a connection string with this option (password or its synonyms) and a value, sha2_password in this case, to satisfy the first authentication factor.

var connString =  "server=localhost;
                   user=abe;
                   password=sha2_password;
                   password2=ldap_password;
                   port=3306";

Alternatively, for a connection made using the MySqlConnectionStringBuilder object:

MySqlConnectionStringBuilder settings = new MySqlConnectionStringBuilder()
     {
       Server = "localhost", 
       UserID = "abe",
       Pwd1 = "sha2_password",
       Pwd2 = "ldap_password",
       Port = 3306
     };

If the server does not require a secret password be used with an authentication method, then the value specified for the password, password2, or password3 option is ignored.

Default: an empty string

The second secret password for an account that has multiple authentication factors (see the Password connection option).

Default: an empty string

The third secret password for an account that has multiple authentication factors (see the Password connection option).

Default: 3306

The port MySQL is using to listen for connections. This value is ignored if Unix socket is used.

Default: localhost

The name or network address of one or more host computers. Multiple hosts are separated by commas and a priority (0 to 100), if provided, determines the host selection order. As of Connector/NET 8.0.19, host selection is random when priorities are omitted or are the same for each host.

// Selects the host with the highest priority (100) first
server=(address=192.10.1.52:3305,priority=60),(address=localhost:3306,priority=100);

No attempt is made by the provider to synchronize writes to the database, so take care when using this option. In UNIX environments with Mono, this can be a fully qualified path to a MySQL socket file. With this configuration, the UNIX socket is used instead of the TCP/IP socket. Currently, only a single socket name can be given, so accessing MySQL in a replicated environment using UNIX sockets is not currently supported.

Default: null

Based on the type of certificates being used, this option either specifies the path to a certificate file in PKCS #12 format (.pfx) or the path to a file in PEM format (.pem) that contains a list of trusted SSL certificate authorities (CA).

With PFX certificates in use, this option engages when the SslMode connection option is set to a value of Required, VerifyCA, or VerifyFull; otherwise, it is ignored.

With PEM certificates in use, this option engages when the SslMode connection option is set to a value of VerifyCA or VerifyFull; otherwise, it is ignored.

For examples of usage, see Section 6.7.1, “Using PEM Certificates in Connector/NET”.

Default: null

The name of the SSL certificate file in PEM format to use for establishing an encrypted connection. This option engages only when VerifyFull is set for the SslMode connection option and the SslCa connection option uses a PEM certificate; otherwise, it is ignored. For an example of usage, see Section 6.7.1, “Using PEM Certificates in Connector/NET”.

Default: null

The name of the SSL key file in PEM format to use for establishing an encrypted connection. This option engages only when VerifyFull is set for the SslMode connection option and the SslCa connection option uses a PEM certificate; otherwise, it is ignored. For an example of usage, see Section 6.7.1, “Using PEM Certificates in Connector/NET”.

Default: Depends on the version of Connector/NET and the protocol in use. Named-pipe and shared-memory connections are not supported with X Protocol.

This option has the following values:

Default: A fallback solution decides which version of TLS to use.

Restricts the set of TLS protocol versions to use during the TLS handshake when both the client and server support the TLS versions indicated and the value of the SslMode connection-string option is not set to Disabled or None (deprecated in Connector/NET 8.0.29). This option accepts a single version or a list of versions separated by a comma, for example, tls-version=TLSv1.2, TLSv1.3;.

Connector/NET supports the following values:

An error is reported when a value other than those listed is assigned. Likewise, an error is reported when an empty list is provided as the value, or if all of the versions in the list are unsupported and no connection attempt is made.

Default: null

The MySQL login account being used.

Default: true

When true, multiple SQL statements can be sent with one command execution. Batch statements should be separated by the server-defined separator character.

Default: false

Disables (by default) or enables the server functionality to load the data local infile. If this option is set to true, uploading files from any location is enabled, regardless of the path specified with the AllowLoadLocalInfileInPath option.

Default: null

Specifies a safe path from where files can be read and uploaded to the server. When the related AllowLoadLocalInfile option is set to false, which is the default value, only those files from the safe path or any valid subfolder specified with the AllowLoadLocalInfileInPath option can be loaded. For example, if /tmp is set as the restricted folder, then file requests for /tmp/myfile and /tmp/myfolder/myfile can succeed. No relative paths or symlinks that fall outside of this path are permitted.

The following table shows the behavior that results when the AllowLoadLocalInfile and AllowLoadLocalInfileInPath connection string options are combined.

Default: false

Setting this option to true informs Connector/NET that RSA public keys should be retrieved from the server and that connections using the classic MySQL protocol, when SSL is disabled, will fail by default. Exceptions to the default behavior can occur when previous successful connection attempts were made or when pooling is enabled and a pooled connection can be reused. This option was introduced with the 8.0.10 connector.

Default: false

Setting this to true indicates that the provider expects user variables in the SQL.

Default: false

If set to True, MySqlDataReader.GetValue() returns a MySqlDateTime object for date or datetime columns that have disallowed values, such as zero datetime values, and a System.DateTime object for valid values. If set to False (the default setting) it causes a System.DateTime object to be returned for all valid values and an exception to be thrown for disallowed values, such as zero datetime values.

Default: true

If AutoEnlist is set to true, which is the default, a connection opened using TransactionScope participates in this scope, it commits when the scope commits and rolls back if TransactionScope does not commit. However, this feature is considered security sensitive and therefore cannot be used in a medium trust environment.

As of 8.0.10, this option is supported in .NET Core 2.0 implementations.

Default: null

A POSIX-style regular expression that matches the names of BLOB columns that do not contain UTF-8 character data. See Section 5.16, “Character Set Considerations for Connector/NET” for usage details.

Default: null

A POSIX-style regular expression that matches the names of BLOB columns containing UTF-8 character data. See Section 5.16, “Character Set Considerations for Connector/NET” for usage details.

Default: true

Indicates if stored routine parameters should be checked against the server.

The list of interceptors that can intercept SQL command operations.

Default: 15

The length of time (in seconds) to wait for a connection to the server before terminating the attempt and generating an error.

Default: false

Use true to have MySqlDataReader.GetValue() and MySqlDataReader.GetDateTime() return DateTime.MinValue for date or datetime columns that have disallowed values.

Takes precedence over the server-side default authentication plugin when a valid authentication plugin is specified (see Section 4.4, “Connector/NET Authentication”). The Defaultauthenticationplugin option is mandatory for supporting userless and passwordless Kerberos authentications in which the credentials are retrieved from a cache or the Key Distribution Center (KDC). For example:

MySqlConnectionStringBuilder settings = new MySqlConnectionStringBuilder()
     {
       Server = "localhost", 
       UserID = "",
       Password = "",
       Database = "mydb",
       Port = 3306,
       DefaultAuthenticationPlugin = "authentication_kerberos_client"
     }; 

If no value is set, the server-side default authentication plugin is used.

This option was introduced with the 8.0.26 connector.

Default: 30

Sets the default value of the command timeout to be used. This does not supersede the individual command timeout property on an individual command object. If you set the command timeout property, that will be used.

Default: 60

Specifies how long a TableDirect result should be cached, in seconds. For usage information about table caching, see Section 5.3, “Using Connector/NET with Table Caching”.

The list of interceptors that can triage thrown MySqlException exceptions.

Default: false

Causes the connector to return binary or varbinary values as strings, if they do not have a table name in the metadata.

Default: false

Must be set to true when using the MySQLClientPermissions class in a partial trust environment, with the library installed in the GAC of the hosting environment. See Section 5.7, “Working with Partial Trust / Medium Trust” for details.

As of 8.0.10, this option is supported in .NET Core 2.0 implementations.

Default: false

If set to true, the client is interactive. An interactive client is one in which the server variable CLIENT_INTERACTIVE is set. If an interactive client is set, the wait_timeout variable is set to the value of interactive_timeout. The client session then times out after this period of inactivity. For more information, see Server System Variables in the MySQL Reference Manual.

As of 8.0.10, this option is supported in .NET Core 2.0 implementations.

Default: no

Use Windows authentication when connecting to server. By default, it is turned off. To enable, specify a value of yes. (You can also use the value sspi as an alternative to yes.) For details, see Section 4.4, “Connector/NET Authentication”.

Currently not supported for .NET Core implementations.

Default: AUTO

On Windows, provides authentication support using Security Support Provider Interface (SSPI), which is capable of acquiring credentials from the Windows in-memory cache, and Generic Security Service Application Program Interface (GSSAPI) through the MIT Kerberos library. GSSAPI is capable of acquiring cached credentials previously generated using the kinit command. The default value for this option (AUTO) attempts to authenticate with GSSAPI if the authentication using SSPI fails.

Possible values for this connection option are:

Default: false

When the value is set to true, various pieces of information are sent to all configured trace listeners. For a more detailed description, see Section 5.12, “Connector/NET Tracing”.

As of 8.0.10, this option is supported in .NET Core 2.0 implementations.

Defaults to one of the following path names:

If set, this option specifies an alternative location to the Oracle Cloud Infrastructure configuration file. Connector/NET 8.0.27 (and later) uses the Oracle Cloud Infrastructure SDK to obtain a fingerprint of the API key to use for authentication (fingerprint entry) and location of a PEM file with the private part of the API key (key_file entry). The entries should be specified in the [DEFAULT] profile. If the [DEFAULT] profile is missing from the configuration file, Connector/NET locates the next profile to use instead.

Not supported for .NET Framework 4.5.x implementations.

If set in Connector/NET 8.0.33 (or later), this option specifies which profile in an Oracle Cloud Infrastructure configuration file to use. The profile value defaults to the DEFAULT profile when no value is provided.

Not supported for .NET Framework 4.5.x implementations.

Default: false

The back-end representation of a GUID type was changed from BINARY(16) to CHAR(36). This was done to allow developers to use the server function UUID() to populate a GUID table - UUID() generates a 36-character string. Developers of older applications can add 'Old Guids=true' to the connection string to use a GUID of data type BINARY(16).

Default: false

As of Connector/NET 8.3.0, calling the MySqlDataReader.GetString() method throws an InvalidCastException exception if the column is not a string type. All text types including char and varchar are allowed; and blob is not considered a text type.

Setting this OldGetStringBehavior connection option to true restores previous behavior by logging a deprecation warning instead of throwing the exception.

This option was added in 8.3.0 and removed in 9.0.0.

Default: ""

A Base64URL encoded string containing the OpenID Identity Token used to authenticate with the authentication_openid_connect_client authentication plugin.

This option was added in 9.1.0.

Default: false

When set to false or no (strongly recommended), security-sensitive information, such as the password, is not returned as part of the connection if the connection is open or has ever been in an open state. Resetting the connection string resets all connection string values, including the password. Recognized values are true, false, yes, and no.

Default: mysql

When set to the name of a named pipe, the MySqlConnection attempts to connect to MySQL on that named pipe. This setting only applies to the Windows platform.

Currently not supported for .NET Core implementations.

Default: 25

Sets the size of the stored procedure cache. By default, Connector/NET stores the metadata (input/output data types) about the last 25 stored procedures used. To disable the stored procedure cache, set the value to zero (0).

Default: false

Indicates if this connection is to use replicated servers.

As of 8.0.10, this option is supported in .NET Core 2.0 implementations.

Enable this option to make the connector rewrite batched statements and execute them all at once in a single block rather than one at a time, which is default behavior. Option added in Connector/NET 9.2.0.

Default: true

Setting this option to false means that Connector/NET ignores a column's binary flags as set by the server.

Default: mysql

The name of the shared memory object to use for communication if the transport protocol is set to memory. This setting only applies to the Windows platform.

Currently not supported for .NET Core implementations.

Default: false

Allow SQL Server syntax. When set to true, enables Connector/NET to support square brackets around symbols instead of backticks. This enables Visual Studio wizards that bracket symbols between the [ and ] characters to work with Connector/NET. This option incurs a performance hit, so should only be used if necessary.

Default: false

Enables or disables caching of TableDirect commands. A value of true enables the cache while false disables it. For usage information about table caching, see Section 5.3, “Using Connector/NET with Table Caching”.

Default: false

Setting this value to true causes BLOB columns to have a character set of utf8 with the default collation for that character set. To convert only some of your BLOB columns, you can make use of the 'BlobAsUTF8IncludePattern' and 'BlobAsUTF8ExcludePattern' keywords. Set these to a regular expression pattern that matches the column names to include or exclude respectively.

Default: true

Setting this value to false causes TINYINT(1) to be treated as an INT. See Numeric Data Type Syntax for a further explanation of the TINYINT and BOOL data types.

Default: false

When true, the connection reports changed rows instead of found rows.

Default: false

Setting this option to true enables compression of packets exchanged between the client and the server. This exchange is defined by the MySQL client/server protocol.

Compression is used if both client and server support ZLIB compression, and the client has requested compression using this option.

A compressed packet header is: packet length (3 bytes), packet number (1 byte), and Uncompressed Packet Length (3 bytes). The Uncompressed Packet Length is the number of bytes in the original, uncompressed packet. If this is zero, the data in this packet has not been compressed. When the compression protocol is in use, either the client or the server may compress packets. However, compression will not occur if the compressed length is greater than the original length. Thus, some packets will contain compressed data while other packets will not.

Default: false

Enforces the command timeout of EFMySqlCommand, which is set to the value provided by the DefaultCommandTimeout property.

Default: false

Indicates that performance counters should be updated during execution.

Currently not supported for .NET Core implementations.

Default: false

Logs inefficient database operations.

As of 8.0.10, this option is supported in .NET Core 2.0 implementations.

Default: false

Specifies whether server variable settings are updated by a SHOW VARIABLES command each time a pooled connection is returned. Enabling this setting speeds up connections in a connection pool environment. Your application is not informed of any changes to configuration variables made by other connections.

Default: 0

When a connection is returned to the pool, its creation time is compared with the current time and the connection is destroyed if that time span (in seconds) exceeds the value specified by Connection Lifetime. This option is useful in clustered configurations to force load balancing between a running server and a server just brought online. A value of zero (0) sets pooled connections to the maximum connection timeout.

Default: false

If true, the connection state is reset when it is retrieved from the pool. The default value of false avoids making an additional server round trip when obtaining a connection, but the connection state is not reset.

Default: 100

The maximum number of connections allowed in the pool.

Default: 0

The minimum number of connections allowed in the pool.

Default: true

When true, the MySqlConnection object is drawn from the appropriate pool, or if necessary, is created and added to the appropriate pool. Recognized values are true, false, yes, and no.

Authentication mechanism to use with the X Protocol. This option was introduced with the 8.0.9 connector and has the following values, which are not case-sensitive: MYSQL41, PLAIN, and EXTERNAL. If the Auth option is not set, the mechanism is chosen depending on the connection type. PLAIN is used for secure connections (TLS or Unix sockets) and MYSQL41 is used for unencrypted connections. EXTERNAL is used for external authentication methods such as PAM, Windows login IDs, LDAP, or Kerberos. (EXTERNAL is not currently supported.)

The Auth option is not supported for classic MySQL protocol connections and returns NotSupportedException if used.

Default: preferred

Compression is used to send and receive data when both the client and server support it for X Protocol connections and the client requests compression using this option. After a successful algorithm negotiation is made, Connector/NET can start compressing data immediately. To prevent the compression of small data packets, or of data already compressed, Connector/NET defines a size threshold of 1000 bytes.

When multiple compression algorithms are supported by the server, Connector/NET applies the following priority by default: zstd_stream (first), lz4_message (second), and deflate_stream (third). The deflate_stream algorithm is supported for use with .NET Core, but not for .NET Framework.

Data compression for X Protocol connections was added in the Connector/NET 8.0.20 release. The Compression option accepts the following values:

As of Connector/NET 8.0.22, a client application can specify the order in which supported compression algorithms are negotiated with the server. The value of the Compression connection option must be set to preferred or to required for this option to apply. Unsupported algorithms are ignored.

This option accepts the following algorithm names and synonyms:

Algorithm names and synonyms can be combined in a comma-separated list or provided as a standalone value (with or without brackets). Examples:

// Compression option set to preferred (default)
MySQLX.GetSession("mysqlx://test:test@localhost:3306?compression-algorithms=[lz4_message,deflate]
MySQLX.GetSession("mysqlx://test:test@localhost:3306?compressionalgorithms=lz4
MySQLX.GetSession("mysqlx://test:test@localhost:3306?compression=preferred&compression-algorithms=[zstd]

// Compression option set to required
MySQLX.GetSession("mysqlx://test:test@localhost:3306?compression=required&compression-algorithms=[zstd_stream,lz4_message]
MySQLX.GetSession("mysqlx://test:test@localhost:3306?compression=required&compression-algorithms=[lz4]
MySQLX.GetSession("mysqlx://test:test@localhost:3306?compression=required&compression-algorithms=zstd_stream

// Connection string
MySQLX.GetSession("server=localhost;port=3306;uid=test;password=test;compression=required;compression-algorithms=lz4_message;")

// Anonymous object
MySQLX.GetSession(new { 
   server = "localhost", 
   port = "3306", 
   uid = "test", 
   password = "test", 
   compression="required", 
   compressionalgorithms = "deflate_stream" })

For additional information, see Connection Compression with X Plugin.

Default: true

This option was introduced in Connector/NET 8.0.16 for submitting a set of attributes to be passed together with default connection attributes to the server. The aggregate size of connection attribute data sent by a client is limited by the value of the performance_schema_session_connect_attrs_size server variable. The total size of the data package should be less than the value of the server variable. For general information about connection attributes, see Performance Schema Connection Attribute Tables.

The connection-attributes parameter value can be empty (the same as specifying true), a Boolean value (true or false to enable or disable the default attribute set), or a list or zero or more key=value specifiers separated by commas (to be sent in addition to the default attribute set). Within a list, a missing key value evaluates as the NULL value. Examples:

// Sessions
MySQLX.GetSession($"mysqlx://user@host/schema")
MySQLX.GetSession($"mysqlx://user@host/schema?connection-attributes")
MySQLX.GetSession($"mysqlx://user@host/schema?connection-attributes=true")
MySQLX.GetSession($"mysqlx://user@host/schema?connection-attributes=false")
MySQLX.GetSession($"mysqlx://user@host/schema?connection-attributes=[attr1=val1,attr2,attr3=]")
MySQLX.GetSession($"mysqlx://user@host/schema?connection-attributes=[]")

// Pooling
MySQLX.GetClient($"mysqlx://user@host/schema")
MySQLX.GetClient($"mysqlx://user@host/schema?connection-attributes")
MySQLX.GetClient($"mysqlx://user@host/schema?connection-attributes=true")
MySQLX.GetClient($"mysqlx://user@host/schema?connection-attributes=false")
MySQLX.GetClient($"mysqlx://user@host/schema?connection-attributes=[attr1=val1,attr2,attr3=]")
MySQLX.GetClient($"mysqlx://user@host/schema?connection-attributes=[]")

Application-defined attribute names cannot begin with _ because such names are reserved for internal attributes.

If connection attributes are not specified in a valid way, an error occurs and the connection attempt fails.

Default: 10000

The length of time (in milliseconds) to wait for an X Protocol connection to the server before terminating the attempt and generating an error. You can disable the connection timeout by setting the value to zero. This option can be specified as follows:

Default: null

Path to a local file containing certificate revocation lists.