MySQL Connector/NET Developer Guide
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 URI-like connection string (X Protocol). Connector/NET option names and synonyms are not case sensitive.
For instructions about how to use connection strings, see Section 4.1, “Creating a Connector/NET Connection String”. For alternative connection styles, see Connecting to the Server Using URI-Like Strings or Key-Value Pairs.
The following sections list the connection options that apply to both protocols, classic MySQL protocol only, and X Protocol only:
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 6.10.2, “Using PFX Certificates in 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 6.10.2, “Using PFX Certificates in 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 6.10.2, “Using PFX Certificates in 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 6.10.2, “Using PFX Certificates in 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
(or
tcp
)
Specifies the type of connection to make to the server. Values can be:
socket
or tcp
for
a socket connection using TCP/IP.
pipe
for a named pipe connection (not
supported with X Protocol).
unix
for a UNIX socket connection.
memory
to use MySQL shared memory
(not supported with X Protocol).
Database
,
Initial Catalog
Default: mysql
The case-sensitive name of the database to use initially.
dns-srv
,
dnssrv
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);
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
(deprecated)
,
Addr
(deprecated)
,
Network Address
(deprecated)
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.
SshHostName
,
Ssh Host Name
,
Ssh-Host-Name
Default: null
The name or IP address of the computer that hosts the SSH server.
SshKeyFile
,
Ssh Key File
,
Ssh-Key-File
Default: null
The path and name of the SSH key file. The key file supports RSA and DSA private keys in both OpenSSH and ssh.com format. If you provide this file, the related pass phrase may be required for authentication. When both the key file and password are provided, the key file is authenticated first and then, if that fails, the password is used as the fallback configuration. Fallback conditions require that the SSH key file and SSH pass phrase are valid, but the connection attempt failed due to errors on the server.
SshPassPhrase
,
Ssh Pass Phrase
,
Ssh-Pass-Phrase
Default: null
The pass phrase of the SSH key file.
SshPassword
,
Ssh Password
,
Ssh-Password
Default: null
The SSH password. When both the key file and password are provided, the key file is authenticated first and then, if that fails, the password is used as the fallback configuration. Fallback conditions require that the SSH key file and SSH pass phrase are valid, but the connection attempt failed due to errors on the server.
SshPort
,
Ssh Port
,
Ssh-Port
Default: 22
The port number of the SSH server.
SshUserName
,
Ssh User Name
,
Ssh-User-Name
Default: null
The name of the SSH user that is authenticated by the SSH
server using a key file (and pass phrase, if required), a
password, or both. With valid credentials, a connection is
established between the client application and the SSH
server. The SSH server then communicates with an MySQL
server instance in an unencrypted or encrypted connection,
based on the value of the SslMode
connection-string option.
The ConnectionProtocol
connection-string
option must be set to socket
or
tcp
(default) to enable SSH tunneling.
SslCa
,
Ssl-Ca
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.10.1, “Using PEM Certificates in Connector/NET”.
SslCert
,
Ssl-Cert
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.10.1, “Using PEM Certificates in Connector/NET”.
SslKey
,
Ssl-Key
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.10.1, “Using PEM Certificates in Connector/NET”.
SslMode
,
Ssl Mode
,
Ssl-Mode
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.
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.
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 certificate authorities (CA), but tolerate a name
mismatch.
VerifyFull
- Always use SSL. Fail if
the host name is not correct.
tlsversion
,
tls-version
,
tls version
Default: Tlsv1,Tlsv1.1,Tlsv1.2,Tlsv1.3
(A
fallback solution decides which TLS version 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 None
. This option accepts a single
version or a list of versions separated by a comma, for
example, tls-version=TLSv1.1, TLSv1.2,
TLSv1.3;
.
Connector/NET supports the following values:
TLSv1.3
TLSv1.2
TLSv1.1
TLSv1
or TLSv1.0
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.
UserID
,
User Id
,
Username
,
Uid
,
User name
,
User
Default: null
The MySQL login account being used.
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.
AllowLoadLocalInfile
,
Allow Load Local Infile
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.
AllowLoadLocalInfileInPath
,
Allow Load Local Infile In Path
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.
AllowLoadLocalInfile Value | AllowLoadLocalInfileInPath Value | Behavior |
---|---|---|
true |
Empty string or null value |
All uploads are permitted. |
true |
A valid path | All uploads are permitted (the path is not respected). |
false |
Empty string or null value |
No uploads are permitted. |
false |
A valid path | Only uploads from the specified folder and subfolder are permitted. |
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.
This option is prone to man-in-the-middle attacks, so it should be used only in situations where you can ensure by other means that your connections are made to trusted servers.
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.14, “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.14, “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.4, “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: false
Deprecated in the Connector/NET 8.0.23 release. 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.17, “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.3.1, “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.12, “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 transport 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 between the
[
and ]
characters 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.4, “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. 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.
TreatTinyAsBoolean
,
Treat Tiny As Boolean
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.
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 Opening a Connection to a Single Server.
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
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.
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
.
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 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.
Compression
,
use-compression
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.
Use the compression-algorithms
option
to specify one ore more supported algorithms in a
different order. The algorithms are negotiated in the
order provided by client. For usage details, see the
compression-algorithms
option.
Data compression for X Protocol connections was added in
the Connector/NET 8.0.20 release. The
Compression
option accepts the following
values:
preferred
to apply data compression
if the server supports the algorithms chosen by the
client. Otherwise, the data is sent and received without
compression.
required
to ensure that compression
is used or to terminate the connection and return an
error message.
disabled
to prevent data compression.
compression-algorithms
,
CompressionAlgorithms
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:
lz4_message
or lz4
zstd_stream
or
zstd
deflate_stream
or
deflate
(not valid with .NET
Framework)
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.
connection-attributes
,
ConnectionAttributes
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.
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:
URI-like connection string 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);
SslCrl
,
Ssl-Crl
Default: null
Path to a local file containing certificate revocation lists.
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.