MySQL ConnectionString Options
The simplest MySQL connection string for C# is:
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 are the basic options that need to be defined to connect to a MySQL database.
|Host, Server, 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.|
|Password, pwd||The password for the MySQL user.|
|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.|
|Protocol, ConnectionProtocol, Connection Protocol||Socket||How to connect to the MySQL Server. This option has the following values:|
|Pipe, PipeName, Pipe Name||MYSQL||The name of the Windows named pipe to use to connect to the server. You must also set |
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||Specifies 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 |
|Certificate Password, CertificatePassword||Specifies the password for the certificate specified using the |
|SslCert, Ssl-Cert||Specifies the path to the client’s SSL certificate file in PEM format. |
|SslKey, Ssl-Key||Specifies the path to the client’s SSL private key in PEM format. |
|CA Certificate File, CACertificateFile, SslCa, Ssl-Ca||This option specifies the path to a CA certificate file in a PEM Encoded (.pem) format. This should be used with |
|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.|
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||Controls the maximum length of time a connection to the server can be open. Connections that are returned to the pool are destroyed if it’s been more than |
|Connection Reset, ConnectionReset||If |
|Connection Idle Ping Time, Connection Idle Ping Time (Experimental)||0||When a connection is retrieved from the pool, and |
|Connection Idle Timeout, ConnectionIdleTimeout||180||The amount of time (in seconds) that a connection can remain idle in the pool. Any connection above |
|Maximum Pool Size, Max Pool Size, MaximumPoolsize, maxpoolsize||100||The maximum number of connections allowed in the pool.|
|Minimum Pool Size, Min Pool Size, MinimumPoolSize, minpoolsize||0||The minimum number of connections to leave in the pool if ConnectionIdleTimeout is reached.|
Connection Pooling with Multiple Servers
Server option supports multiple comma-delimited host names. When this is used with connection
LoadBalance option controls how load is distributed across backend servers.
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 other options that MySqlConnector supports. They are set to sensible defaults and typically do not need to be tweaked.
|AllowPublicKeyRetrieval, Allow Public Key Retrieval||false||If the user account uses |
|AllowUserVariables, Allow User Variables||false||Allows user-defined variables (prefixed with |
|AllowZeroDateTime, Allow Zero DateTime||false||If set to |
|ApplicationName, Application Name||null||Sets the |
|CharSet, Character Set, CharacterSet||utf8mb4||MySqlConnector always uses |
|Compress, Use Compression, 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.|
|Connect Timeout, Connection 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 MySqlDataReader.GetValue() and MySqlDataReader.GetDateTime() return DateTime.MinValue for date or datetime columns that have disallowed values.|
Determines which column type (if any) should be read as a
|Default Command Timeout, Command Timeout, DefaultCommandTimeout||30||The length of time (in seconds) each command can execute before timing out and throwing an exception, or zero to disable timeouts. See the note in the Microsoft documentation for more explanation of how this is determined.|
|IgnoreCommandTransaction, Ignore Command Transaction||false||If |
|Interactive, Interactive Session, InteractiveSession||false||If |
|Keep Alive, Keepalive||0||TCP Keepalive idle time. A value of 0 indicates that the OS Default keepalive settings are used. On Windows, a value greater than 0 is the idle connection time, measured in seconds, before the first keepalive packet is sent. Due to limitations in .NET Core, Unix-based Operating Systems will always use the OS Default keepalive settings.|
|Load Balance, LoadBalance||RoundRobin|
The load-balancing strategy to use when
|Old Guids, OldGuids||false||Obsolete; use the |
|Persist Security Info, PersistSecurityInfo||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.|
|ServerRSAPublicKeyFile, Server RSA Public Key File||For |
|ServerSPN, Server SPN||For MariaDB |
|Treat Tiny As Boolean, TreatTinyAsBoolean||true||When set to |
|Use Affected Rows, UseAffectedRows||false||When |
|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.|
|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.|
|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.|
|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.|
|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.|