MySQL .NET Connection String Options
The simplest MySQL connection string for C# is:
new MySqlConnection("Server=YOURSERVER;User ID=YOURUSERID;Password=YOURPASSWORD")
For all the other options, see the tables below. MySqlConnector supports most of Oracle’s Connector/NET connection options.
There are also several unique options that are supported only by MySqlConnector, a replacement for
MySql.Data that fixes bugs,
adds new features, and improves database access performance. Install it now.
These options specify how to connect and authenticate to a MySQL database.
|Server, Host, Data Source, DataSource, Address, Addr, Network Address||localhost|
The host name or network address of the MySQL Server to which to connect. Multiple hosts can be specified in a comma-delimited list.
On Unix-like systems, this can be a fully qualified path to a MySQL socket file, which will cause a Unix socket to be used instead of a TCP/IP socket. Only a single socket name can be specified.
|Port||3306||The TCP port on which MySQL Server is listening for connections.|
|User ID, UserID, Username, Uid, User name, User||The MySQL user ID.|
The password for the MySQL user.
For systems that use frequently-updated authentication tokens (such as Amazon Aurora RDS with IAM Authentication), leave this value empty, and set
|Database, Initial Catalog||(Optional) The case-sensitive name of the initial database to use. This may be required if the MySQL user account only has access rights to particular databases on the server.|
|Load Balance, LoadBalance||RoundRobin|
The load-balancing strategy to use when
|Connection Protocol, ConnectionProtocol, Protocol||Socket||How to connect to the MySQL Server. This option has the following values:|
|Pipe Name, Pipe, PipeName||MYSQL||The name of the Windows named pipe to use to connect to the server. You must also set |
Connecting to Multiple Servers
Server option supports multiple comma-delimited host names.
LoadBalance option controls how load is distributed across backend servers.
Some of these options (
LeastConnections) only take effect if
FailOver can be used with
Random: A total of
MaximumPoolSizeconnections will be opened, but they may be unevenly distributed across back ends.
LeastConnections: A total of
MaximumPoolSizeconnections will be opened, and they will be evenly distributed across back ends. The active connections will be selected from the pool in least-recently-used order, which does not ensure even load across the back ends. You should set
MaximumPoolSizeto the number of servers multiplied by the desired maximum number of open connections per backend server.
Failover: All connections will initially be made to the first server in the list. You should set
MaximumPoolSizeto the maximum number of open connections you want per server.
These are the options that need to be used in order to configure a connection to use SSL/TLS.
|SSL Mode, SslMode||Preferred||This option has the following values:|
|Certificate File, CertificateFile|
The path to a certificate file in PKCS #12 (.pfx) format containing a bundled Certificate and Private Key used for mutual authentication. To create a PKCS #12 bundle from a PEM encoded Certificate and Key, use
If the certificate can't be loaded from a file path, leave this value empty and set
|Certificate Password, CertificatePassword||The password for the certificate specified using the |
|Certificate Store Location, CertificateStoreLocation||None||Specifies whether the connection should be encrypted with a certificate from the Certificate Store on the machine. The default value of |
|Certificate Thumbprint, CertificateThumbprint||Specifies which certificate should be used from the certificate store specified in the setting above. This option must be used to indicate which certificate in the store should be used for authentication.|
|SSL Cert, SslCert, Ssl-Cert||The path to the client’s SSL certificate file in PEM format. |
|SSL Key, SslKey, Ssl-Key||The path to the client’s SSL private key in PEM format. |
|SSL CA, CA Certificate File, CACertificateFile, SslCa, Ssl-Ca|
The path to a CA certificate file in a PEM Encoded (.pem) format. This should be used with
To provide a custom callback to validate the remote certificate, leave this option empty and set
|TLS Version, TlsVersion, Tls-Version||The TLS versions which may be used during TLS negotiation. The default value of |
|TLS Cipher Suites,TlsCipherSuites||The TLS cipher suites which may be used during TLS negotiation. The default value (the empty string) allows the OS to determine the TLS cipher suites to use; this is the recommended setting. Otherwise, specify a comma-delimited list of |
Connection Pooling Options
Connection pooling is enabled by default. These options are used to configure it.
|Pooling||true||Enables connection pooling. When pooling is enabled, |
|Connection Lifetime, ConnectionLifeTime||0||Connections that are returned to the pool will be closed if it’s been more than |
|Connection Reset, ConnectionReset||If |
|Defer Connection Reset, DeferConnectionReset||This option was obsoleted in MySqlConnector 2.0.|
|Connection Idle Timeout, ConnectionIdleTimeout||180||The amount of time (in seconds) that a connection can remain idle in the pool. Any connection above |
|Minimum Pool Size, Min Pool Size, MinimumPoolSize, minpoolsize||0||The minimum number of connections to leave in the pool if ConnectionIdleTimeout is reached.|
|Maximum Pool Size, Max Pool Size, MaximumPoolsize, maxpoolsize||100||The maximum number of connections allowed in the pool.|
|DNS Check Interval, DnsCheckInterval||0||The number of seconds between checks for DNS changes, or 0 to disable periodic checks.
If the periodic check determines that one of the |
These are the other options that MySqlConnector supports. They are set to sensible defaults and typically do not need to be tweaked.
|Allow Load Local Infile, AllowLoadLocalInfile||false||Allows the |
|Allow Public Key Retrieval, AllowPublicKeyRetrieval||false||If the user account uses |
|Allow User Variables, AllowUserVariables||false||Allows user-defined variables (prefixed with |
|Allow Zero DateTime, AllowZeroDateTime||false||If set to |
|Application Name, ApplicationName||null||Sets the |
|Auto Enlist, AutoEnlist||true||If |
|Cancellation Timeout, CancellationTimeout||2||The length of time (in seconds) to wait for a query to be canceled when |
|Character Set, CharSet, CharacterSet||utf8mb4||MySqlConnector always uses |
|Connection Timeout, Connect Timeout, ConnectionTimeout||15||The length of time (in seconds) to wait for a connection to the server before terminating the attempt and generating an error.|
|Convert Zero DateTime, ConvertZeroDateTime||false||True to have |
|DateTime Kind, DateTimeKind||Unspecified||The |
|Default Command Timeout, Command Timeout, DefaultCommandTimeout||30||The length of time (in seconds) each command can execute before the query is cancelled on the server, or zero to disable timeouts. See the note in the Microsoft documentation for more explanation of how this is determined.|
|GUID Format, GuidFormat||Default|
Determines which column type (if any) should be read as a
|Ignore Command Transaction, IgnoreCommandTransaction||false||If |
|Ignore Prepare, IgnorePrepare||false||If |
|Interactive Session, Interactive, InteractiveSession||false||If |
|Keep Alive, Keepalive||0|
TCP Keepalive idle time (in seconds). A value of 0 indicates that the OS default keepalive settings are used; a value greater than 0 is the idle connection time (in seconds) before the first keepalive packet is sent.
On Windows, this option is always supported. On non-Windows platforms, this option only takes effect in .NET Core 3.0 and later. For earlier versions of .NET Core, the OS Default keepalive settings are used instead.
|No Backslash Escapes, NoBackslashEscapes||false||If |
|Old Guids, OldGuids||false||Obsolete; use the |
|Persist Security Info, PersistSecurityInfo||false||When set to |
|Pipelining||true||When set to |
|Server Redirection Mode, ServerRedirectionMode||Disabled|
Whether to use server redirection. The options include:
Server Redirection is supported by Azure Database for MySQL if the
This option is only respected if
|Server RSA Public Key File, ServerRsaPublicKeyFile||For |
|Server SPN, ServerSPN||For MariaDB |
|Treat Tiny As Boolean, TreatTinyAsBoolean||true||When set to |
|Use Affected Rows, UseAffectedRows||false||When |
|Use Compression, Compress, UseCompression||false||If true (and if the server supports compression), compresses packets sent between client and server. This option is unlikely to be useful in practice unless there is a high-latency or low-bandwidth network link between the application and the database server. You should measure performance with and without this option to determine if it’s beneficial in your environment.|
|Use XA Transactions, UseXaTransactions||true||When |
These options are used by Connector/NET but not supported by MySqlConnector. In general, they should be removed from your connection string when migrating from Connector/NET to MySqlConnector.
|AllowBatch, Allow Batch||true||MySqlConnector always allows batch statements.|
|CacheServerProperties, Cache Server Properties||MySqlConnector doesn’t need this optimization.|
|CheckParameters, Check Parameters||true||MySqlConnector always checks stored procedure parameters efficiently; there’s no need to disable this.|
|CommandInterceptors, Command Interceptors||MySqlConnector doesn’t support this extensibility mechanism, which is not compatible with async operations.|
|DnsSrv, Dns-Srv||MySqlConnector doesn’t support discovering server addresses from DNS SRV records.|
|ExceptionInterceptors, Exception Interceptors||MySqlConnector doesn’t support this extensibility mechanism.|
|FunctionsReturnString, Functions Return String||false||Not supported. BLOBs are always returned as |
|IncludeSecurityAsserts, Include Security Asserts||false||Not supported. For partial trust environments.|
|IntegratedSecurity, Integrated Security||false||Windows authentication is not supported.|
|Logging||false||Use MySqlConnector logging (which is more flexible) instead.|
|OldSyntax, Old Syntax, UseOldSyntax, Use Old Syntax||false||This option is deprecated in Connector/NET and unsupported in MySqlConnector.|
|Password1, Password2, Password3||MySqlConnector does not currently support multifactor authentication; see issue 1068.|
|ProcedureCacheSize, Procedure Cache Size, ProcedureCache, Procedure Cache||MySqlConnector places no limit on the amount of stored procedure metadata that is cached. It takes a very small amount of memory.|
|RespectBinaryFlags, Respect Binary Flags||true||The binary type of a column is always respected.|
|SharedMemoryName, Shared Memory Name||true||Shared memory (on Windows) is not supported as a connection protocol.|
|SshHostName, SshPort, SshUserName, SshPassword, SshKeyFile, SshPassPhrase||Connecting via SSH isn’t built into MySqlConnector, but can be set up easily by following these instructions.|
|SqlServerMode, Sql Server Mode||false||Not supported.|
|TreatBlobsAsUtf8, Treat BLOBs as UTF8||false||Not supported. BLOBs are always returned as |
|UsePerformanceMonitor, Use Performance Monitor, UserPerfMon, PerfMon||false||Not supported.|
|UseUsageAdvisor, Use Usage Advisor, Usage Advisor||false||Not supported.|