Documentation Home
MySQL Connector/NET Developer Guide
Related Documentation Download this Manual

MySQL Connector/NET Developer Guide  /  Connector/NET 8.0 Connection Options Reference

Chapter 7 Connector/NET 8.0 Connection Options Reference

This chapter describes the full set of MySQL Connector/NET 8.0 connection options. The protocol you use to make a connection to the server (classic MySQL protocol or X Protocol) determines which options you should use. Connection options have a default value that you can override by defining the new value in the connection string (classic MySQL protocol and X Protocol) or in the connection URI (X Protocol).

For instructions about how to use connection strings, see Section 5.1.1, “Creating a Connector/NET Connection String”. For alternative connection styles, see Connecting Using a Path.

The following sections list the connection options that apply to both protocols, classic protocol only, and X Protocol only:

Options for Both Classic MySQL Protocol and X Protocol

The following Connector/NET connection options can be used with either protocol. Connector/NET 8.0 exposes the options in this section as properties in both the MySql.Data.MySqlClient.MySqlConnectionStringBuilder and MySqlX.XDevAPI.MySqlXConnectionStringBuilder classes.

CertificateFile , Certificate File

Default: null

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

CertificatePassword , Certificate Password

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 4.10, “Tutorial: Using SSL with Connector/NET”.

CertificateStoreLocation , Certificate Store Location

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 4.10, “Tutorial: Using SSL with Connector/NET”.

CertificateThumbprint , Certificate Thumbprint

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 4.10, “Tutorial: Using SSL with Connector/NET”.

CharacterSet , Character Set , CharSet

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.

ConnectionProtocol , Protocol , Connection Protocol

Default: socket

Specifies the type of connection to make to the server. Values can be: socket or tcp for a socket connection, pipe for a named pipe connection, unix for a Unix socket connection, memory to use MySQL shared memory.

Database , Initial Catalog

Default: mysql

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

Keepalive , Keep Alive

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.

Password , pwd

The password for the MySQL account being used.

Port

Default: 3306

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

Server , Host , Data Source , DataSource , Address , Addr , Network Address

Default: localhost

The name or network address of the instance of MySQL to which to connect. Multiple hosts can be specified separated by commas. This can be useful where multiple MySQL servers are configured for replication and you are not concerned about the precise server you are connecting to. No attempt is made by the provider to synchronize writes to the database, so take care when using this option. In Unix environment 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.

SslMode , SSL Mode , Ssl-Mode

Default: Depends on the version of Connector/NET and the protocol in use.

  • Required for 8.0.8 to 8.0.12 (both protocols); 8.0.13 and higher (X Protocol only).

  • Preferred for 8.0.13 and higher (classic MySQL protocol only).

This option has the following values:

  • None - Do not use SSL. Non-SSL enabled servers require this option be set to None explicitly for Connector/NET 8.0.8 or higher.

  • Preferred - Use SSL if the server supports it, but allow connection in all cases. This option was removed in Connector/NET 8.0.8 and reimplemented in 8.0.13 for classic MySQL protocol only.

    Note

    Do not use this option for X Protocol operations.

  • Required - Always use SSL. Deny connection if server does not support SSL.

  • VerifyCA - Always use SSL. Validate the CA but tolerate name mismatch.

  • VerifyFull - Always use SSL. Fail if the host name is not correct.

UserID , User Id , Username , Uid , User name , User

The MySQL login account being used.

Options for Classic MySQL Protocol Only

Options related to systems using a connection pool appear together at the end of the list of general options (see Connection-Pooling Options). Connector/NET 8.0 exposes the options in this section as properties in the MySql.Data.MySqlClient.MySqlConnectionStringBuilder class.

General Options.  The Connector/NET options that follow are for general use with connection strings and the options apply to all MySQL server configurations:

AllowBatch , Allow Batch

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.

AllowPublicKeyRetrieval

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.

AllowUserVariables , Allow User Variables

Default: false

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

AllowZeroDateTime , Allow Zero Datetime

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.

AutoEnlist , Auto Enlist

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.

BlobAsUTF8ExcludePattern

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.

BlobAsUTF8IncludePattern

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.

CheckParameters , Check Parameters

Default: true

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

CommandInterceptors , Command Interceptors

The list of interceptors that can intercept SQL command operations.

ConnectionTimeout , Connect Timeout , Connection Timeout

Default: 15

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

ConvertZeroDateTime , Convert Zero Datetime

Default: false

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

DefaultCommandTimeout , Default Command Timeout

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.

DefaultTableCacheAge , Default Table Cache Age

Default: 60

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

ExceptionInterceptors , Exception Interceptors

The list of interceptors that can triage thrown MySqlException exceptions.

FunctionsReturnString , Functions Return String

Default: false

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

IgnorePrepare , Ignore Prepare

Default: true

When true, instructs the provider to ignore any calls to MySqlCommand.Prepare(). This option is provided to prevent issues with corruption of the statements when used with server-side prepared statements. If you use server-side prepare statements, set this option to false.

Includesecurityasserts , Include security asserts

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.19, “Working with Partial Trust / Medium Trust” for details.

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

InteractiveSession , Interactive , Interactive Session

Default: false

If set to true, the client is interactive. An interactive client is one where 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 will then time out after this period of inactivity. For more details, see Server System Variables in the MySQL Reference Manual.

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

IntegratedSecurity , Integrated Security

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 5.4, “Using the Windows Native Authentication Plugin”.

Currently not supported for .NET Core implementations.

Logging

Default: false

When true, various pieces of information is output to any configured TraceListeners. See Section 5.14, “Using the Connector/NET Trace Source Object” for further details.

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

OldGuids , Old Guids

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).

PersistSecurityInfo , Persist Security Info

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.

PipeName , Pipe Name , Pipe

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.

ProcedureCacheSize , Procedure Cache Size , procedure cache , procedurecache

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).

Replication

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.

RespectBinaryFlags , Respect Binary Flags

Default: true

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

SharedMemoryName , Shared Memory Name

Default: MYSQL

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

Currently not supported for .NET Core implementations.

sqlservermode , Sql Server Mode

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 with [] to work with Connector/NET. This option incurs a performance hit, so should only be used if necessary.

tablecaching , Table Cache , tablecache

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.6, “Using Connector/NET with Table Caching”.

TreatBlobsAsUTF8 , Treat BLOBs as UTF8

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.

TreatTinyAsBoolean , Treat Tiny As Boolean

Default: true

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

UseAffectedRows , Use Affected Rows

Default: false

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

UseCompression , Compress , Use Compression

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.

UseDefaultCommandTimeoutForEF , Use Default Command Timeout For EF

Default: false

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

UseOldSyntax , Old Syntax , OldSyntax , Use Old Syntax

Default: false

This option was removed in Connector/NET 8.0.8. All code should now be written using the '@' symbol as the parameter marker.

UsePerformanceMonitor , Use Performance Monitor , userperfmon , perfmon

Default: false

Indicates that performance counters should be updated during execution.

Currently not supported for .NET Core implementations.

UseUsageAdvisor , Use Usage Advisor , Usage Advisor

Default: false

Logs inefficient database operations.

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

Connection-Pooling Options.  The following options are related to connection pooling within connection strings. For more information about connection pooling, see Section 5.3, “Using Connector/NET with Connection Pooling”.

CacheServerProperties , Cache Server Properties

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.

ConnectionLifeTime , Connection Lifetime

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 is useful in clustered configurations to force load balancing between a running server and a server just brought online. A value of zero (0) causes pooled connections to have the maximum connection timeout.

ConnectionReset , Connection Reset

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.

MaximumPoolsize , Max Pool Size , Maximum Pool Size , maxpoolsize

Default: 100

The maximum number of connections allowed in the pool.

MinimumPoolSize , Min Pool Size , Minimum Pool Size , minpoolsize

Default: 0

The minimum number of connections allowed in the pool.

Pooling

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.

Options for X Protocol Only

The connection options that follow are valid for connections made with X Protocol. Connector/NET 8.0 exposes the options in this section as properties in the MySqlX.XDevAPI.MySqlXConnectionStringBuilder class.

auth , authentication , authentication mode

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 case-insensitive: 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 connections and returns NotSupportedException if used.

Connect-Timeout , ConnectTimeout

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:

  • Connection URI example

    MySQLX.GetSession("mysqlx://test:test@localhost:33060?connect-timeout=2000");
  • Connection string example

    MySQLX.GetSession("server=localhost;user=test;port=33060;connect-timeout=2000");
  • Anonymous object example

    MySQLX.GetSession(new { server="localhost", user="test", port=33060, connecttimeout=2000 });
  • MySqlXConnectionStringBuilder class example

    var builder = new MySqlXConnectionStringBuilder("server=localhost;user=test;port=33060");
    builder.ConnectTimeout = 2000;
    MySQLX.GetSession(builder.ConnectionString);
SslCa , Ssl-Ca

Default: null

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

SslCrl , Ssl-Crl

Default: null

Path to a local file containing certificate revocation lists.

Important

Although the SslCrl connection-string option is valid for use, applying it raises a NotSupportedException message.

SslEnable , Ssl-Enable

Default: false

Enables or disables the use of SSL for connections made using the X Protocol. A value of true sets the SslMode to Required while false sets it to None.

This option was introduced in Connector/NET 7.0.5 and removed in Connector/NET 8.0.8 because SSL is enabled by default when appropriate. Starting with Connector/NET 8.0.8, to disable SSL when the server does not support it, you must set the value of SslMode to None explicitly.


User Comments
User comments in this section are, as the name implies, provided by MySQL users. The MySQL documentation team is not responsible for, nor do they endorse, any of the information provided here.
Sign Up Login You must be logged in to post a comment.