For usage information about connection strings, see Section 5.2, “Creating a Connector/Net Connection String”. The first table list options that apply generally to all server configurations. The options related to systems using a connection pool are split into a separate table.
Table 6.1 Connector/Net Connection String Options - General
| Name | Default | Description |
|---|---|---|
Allow Batch, AllowBatch | true | When true, multiple SQL statements can be sent with one command execution. Note: starting with MySQL 4.1.1, batch statements should be separated by the server-defined separator character. Statements sent to earlier versions of MySQL should be separated by ';'. |
Allow User Variables,
AllowUserVariables | false | Setting this to true indicates that the provider
expects user variables in the SQL. This option was added in
Connector/Net version 5.2.2. |
Allow Zero Datetime,
AllowZeroDateTime | 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. |
Auto Enlist, AutoEnlist | 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. |
BlobAsUTF8ExcludePattern | null | A POSIX-style regular expression that matches the names of BLOB columns that do not contain UTF-8 character data. See Section 5.18, “Character Set Considerations for Connector/Net” for usage details. |
BlobAsUTF8IncludePattern | null | A POSIX-style regular expression that matches the names of BLOB columns containing UTF-8 character data. See Section 5.18, “Character Set Considerations for Connector/Net” for usage details. |
Certificate File, CertificateFile | null | This option specifies the path to a certificate file in PKCS #12 format
(.pfx). For an example of usage, see
Section 4.8, “Tutorial: Using SSL with MySQL Connector/Net”. Was
introduced with 6.2.1. |
Certificate Password,
CertificatePassword | 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.8, “Tutorial: Using SSL with MySQL Connector/Net”. Was
introduced with 6.2.1. |
Certificate Store Location,
CertificateStoreLocation | 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.8, “Tutorial: Using SSL with MySQL Connector/Net”. Was introduced with 6.2.1. |
Certificate Thumbprint,
CertificateThumbprint | 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.8, “Tutorial: Using SSL with MySQL Connector/Net”. Was introduced with 6.2.1. |
CharSet, Character Set,
CharacterSet | Specifies the character set that should be used to encode all queries sent to the server. Resultsets are still returned in the character set of the result data. | |
Check Parameters, CheckParameters | true | Indicates if stored routine parameters should be checked against the server. |
Command Interceptors,
CommandInterceptors | The list of interceptors that can intercept SQL command operations. | |
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. |
Connect_Attrs | Passes a predefined set of key/value pairs containing
connection-specific data items to the server, for
application-defined purposes. connector/Net automatically
transmits the following attributes: _pid,
_client_version,
_platform,
_program_name, _os,
_os_details, and
_thread. See
Performance Schema Connection Attribute Tables
for the Performance
Schema tables to query on the server side to make use
of these attributes. | |
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. |
Default Command Timeout,
DefaultCommandTimeout | 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. This option was added in Connector/Net 5.1.4 |
Default Table Cache Age,
DefaultTableCacheAge | 60 | Specifies how long a TableDirect result should be
cached, in seconds. For usage information about table
caching, see
Section 5.8, “Using Connector/Net with Table Caching”.
This option was added in Connector/Net 6.4. |
enableSessionExpireCallback | false | When set to true, causes the session-expiry scanner
to raise the session_end event before
deleting the session data stored in the
my_aspnet_sessions table, when a session
times out. Enable this option to write additional
application-specific cleanup code to handle the
session_end event of the
global.asax class, before the stored data
of the session gets deleted. Within the session_end method,
any other required cleanup can be done. This option was
added in Connector/Net 6.4.5; it is not yet available in
Connector/Net 6.5.x releases. |
Encrypt, UseSSL | false | For Connector/Net 5.0.3 and later, when true, SSL
encryption is used for all data sent between the client and
server if the server has a certificate installed. Recognized
values are true,
false, yes, and
no. In versions before 5.0.3, this option
had no effect. From version 6.2.1, this option is deprecated
and is replaced by SSL Mode. The option
still works if used. If this option is set to true, it is
equivalent to SSL Mode = Preferred. |
Exception Interceptors,
ExceptionInterceptors | The list of interceptors that can triage thrown
MySqlException exceptions. | |
Functions Return String,
FunctionsReturnString | false | Causes the connector to return binary/varbinary values as strings, if they do not have a tablename in the metadata. |
Host, Server, Data
Source, DataSource,
Address, Addr,
Network Address | 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. |
Ignore Prepare, IgnorePrepare | 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.
This option was added in Connector/Net 5.0.3 and
Connector/Net 1.0.9. |
includesecurityasserts, include security
asserts | 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. This requirement is new for
partial-trust applications in Connector/Net 6.6.4 and
higher. See Section 5.21, “Working with Partial Trust / Medium Trust” for
details. |
Initial Catalog, Database | mysql | The case-sensitive name of the database to use initially. |
Interactive, Interactive Session,
InteractiveSession | 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. |
Integrated Security,
IntegratedSecurity | 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.5, “Using the Windows Native Authentication Plugin”.
This option was introduced in Connector/Net 6.4.4. |
Keep Alive, Keepalive | 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. |
Logging | false | When true, various pieces of information is output to any configured TraceListeners. See Section 5.16, “Using the MySQL Connector/Net Trace Source Object” for further details. |
Old Guids, OldGuids | false | This option was introduced in Connector/Net 6.1.1. The backend
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). |
Old Syntax, OldSyntax,
Use Old Syntax,
UseOldSyntax | false | This option was deprecated in Connector/Net 5.2.2. All code should now be written using the '@' symbol as the parameter marker. |
Password, pwd | The password for the MySQL account being used. | |
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. |
Pipe Name, Pipe,
PipeName | 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. |
Port | 3306 | The port MySQL is using to listen for connections. This value is ignored if Unix socket is used. |
Procedure Cache Size,
ProcedureCacheSize, procedure
cache, procedurecache | 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). This option was added in Connector/Net 5.0.2 and Connector/Net 1.0.9. |
Protocol, Connection Protocol,
ConnectionProtocol | 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. |
Replication | false | Indicates if this connection is to use replicated servers. |
Respect Binary Flags,
RespectBinaryFlags | true | Setting this option to false means that Connector/Net
ignores a column's binary flags as set by the server. This
option was added in Connector/Net version 5.1.3. |
Shared Memory Name,
SharedMemoryName | MYSQL | The name of the shared memory object to use for communication if the
connection protocol is set to memory. |
Sql Server Mode, sqlservermode | 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. This option was added in version 6.3.1. |
SSL Mode, SslMode | None | This option has the following values:
This option was introduced in MySQL Connector/Net 6.2.1. |
Table Cache, tablecache,
tablecaching | 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.8, “Using Connector/Net with Table Caching”.
This option was added in Connector/Net 6.4. |
Treat BLOBs as UTF8,
TreatBlobsAsUTF8 | false | |
Treat Tiny As Boolean,
TreatTinyAsBoolean | 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. |
Use Affected Rows, UseAffectedRows | false | When true, the connection reports changed rows
instead of found rows. This option was added in
Connector/Net version 5.2.6. |
Use Procedure Bodies,
UseProcedureBodies, procedure
bodies | true | When set to true, the default value, MySQL Connector/Net expects
the body of the procedure to be viewable. This enables it to
determine the parameter types and order. Set the option to
false when the user connecting to the
database does not have the
SELECT privileges for the
mysql.proc (stored procedures) table, or
cannot view
INFORMATION_SCHEMA.ROUTINES. In
this case, MySQL Connector/Net cannot determine the types and order of
the parameters, and must be alerted to this fact by setting
this option to false. When set to
false, MySQL Connector/Net does not rely on this
information being available when the procedure is called.
Because MySQL Connector/Net will not be able to determine this
information, explicitly set the types of all the parameters
before the call and add the parameters to the command in the
same order as they appear in the procedure definition. This
option was added in MySQL Connector/Net 5.0.4 and MySQL Connector/Net 1.0.10. |
User Id, UserID,
Username, Uid,
User name, User | The MySQL login account being used. | |
Compress, Use Compression,
UseCompression | false |
Setting this option to 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. |
Use Usage Advisor, Usage Advisor,
UseUsageAdvisor | false | Logs inefficient database operations. |
Use Performance Monitor,
UsePerformanceMonitor,
userperfmon, perfmon | false | Indicates that performance counters should be updated during execution. |
The following table lists the valid names for options related to
connection pooling within the ConnectionString.
For more information about connection pooling, see
Section 5.4, “Using Connector/Net with Connection Pooling”.
Table 6.2 Connector/Net Connection String Options - Connection Pooling
| Name | Default | Description |
|---|---|---|
Cache Server Properties,
CacheServerProperties | 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. This option was added
in Connector/Net 6.3. |
Connection Lifetime,
ConnectionLifeTime | 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. |
Connection Reset, ConnectionReset | 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. |
Maximum Pool Size, Max Pool Size,
MaximumPoolsize,
maxpoolsize (only for Connector/Net 6.7
and later) | 100 | The maximum number of connections allowed in the pool. |
Minimum Pool Size, Min Pool Size,
MinimumPoolSize,
minpoolsize (only for Connector/Net 6.7
and later) | 0 | The minimum number of connections allowed in the pool. |
Pooling | 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. |