Skip to content

Commit 6467009

Browse files
bgraingerbgrainger
authored
Merge pull request #1219 from mysql-net/order-connection-string
Serialize connection string options in a consistent order.
2 parents 0b67c69 + 6551484 commit 6467009

File tree

4 files changed

+159
-139
lines changed

4 files changed

+159
-139
lines changed

‎docs/content/connection-options.md

Lines changed: 69 additions & 74 deletions
Original file line numberDiff line numberDiff line change
@@ -20,10 +20,9 @@ For all the other options, see the tables below. MySqlConnector supports most of
2020
There are also several unique options that are supported only by MySqlConnector, a replacement for `MySql.Data` that [fixes bugs](/tutorials/migrating-from-connector-net/#fixed-bugs),
2121
adds new features, and improves database access performance. [Install it now](/overview/installing/).
2222

23-
Base Options
24-
------------
23+
## Connection Options
2524

26-
These are the basic options that need to be defined to connect to a MySQL database.
25+
These options specify how to connect and authenticate to a MySQL database.
2726

2827
<table class="table table-striped table-hover">
2928
<thead>
@@ -62,6 +61,23 @@ These are the basic options that need to be defined to connect to a MySQL databa
6261
<td></td>
6362
<td>(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.</td>
6463
</tr>
64+
<tr id="LoadBalance">
65+
<td>Load Balance, LoadBalance</td>
66+
<td>RoundRobin</td>
67+
<td><p>The load-balancing strategy to use when <code>Host</code> contains multiple, comma-delimited, host names.
68+
The options include:</p>
69+
<dl>
70+
<dt>RoundRobin</dt>
71+
<dd>Each new connection opened for this connection pool uses the next host name (sequentially with wraparound). Requires <code>Pooling=True</code>. This is the default if <code>Pooling=True</code>.</dd>
72+
<dt>FailOver</dt>
73+
<dd>Each new connection tries to connect to the first host; subsequent hosts are used only if connecting to the first one fails. This is the default if <code>Pooling=False</code>.</dd>
74+
<dt>Random</dt>
75+
<dd>Servers are tried in a random order.</dd>
76+
<dt>LeastConnections</dt>
77+
<dd>Servers are tried in ascending order of number of currently-open connections in this connection pool. Requires <code>Pooling=True</code>.</dd>
78+
</dl>
79+
</td>
80+
</tr>
6581
<tr id="ConnectionProtocol">
6682
<td>Connection Protocol, ConnectionProtocol, Protocol</td>
6783
<td>Socket</td>
@@ -80,8 +96,22 @@ These are the basic options that need to be defined to connect to a MySQL databa
8096
</tr>
8197
</table>
8298

83-
SSL/TLS Options
84-
-----------
99+
### Connecting to Multiple Servers
100+
101+
The `Server` option supports multiple comma-delimited host names.
102+
The `LoadBalance` option controls how load is distributed across backend servers.
103+
Some of these options (`RoundRobin`, `LeastConnections`) only take effect if `Pooling=True`; however `Random` and `FailOver` can be used with `Pooling=False`.
104+
105+
* `RoundRobin` (default), `Random`: A total of `MaximumPoolSize` connections will be opened, but they
106+
may be unevenly distributed across back ends.
107+
* `LeastConnections`: A total of `MaximumPoolSize` connections will be opened, and they will be evenly
108+
distributed across back ends. The active connections will be selected from the pool in least-recently-used
109+
order, which does not ensure even load across the back ends. You should set `MaximumPoolSize` to the
110+
number of servers multiplied by the desired maximum number of open connections per backend server.
111+
* `Failover`: All connections will initially be made to the first server in the list. You should set `MaximumPoolSize`
112+
to the maximum number of open connections you want per server.
113+
114+
## SSL/TLS Options
85115

86116
These are the options that need to be used in order to configure a connection to use SSL/TLS.
87117

@@ -117,6 +147,16 @@ These are the options that need to be used in order to configure a connection to
117147
<td></td>
118148
<td>The password for the certificate specified using the <code>CertificateFile</code> option. Not required if the certificate file is not password protected.</td>
119149
</tr>
150+
<tr id="CertificateStoreLocation">
151+
<td>Certificate Store Location, CertificateStoreLocation</td>
152+
<td>None</td>
153+
<td>Specifies whether the connection should be encrypted with a certificate from the Certificate Store on the machine. The default value of <code>None</code> means the certificate store is not used; a value of <code>CurrentUser</code> or <code>LocalMachine</code> uses the specified store.</td>
154+
</tr>
155+
<tr id="CertificateThumbprint">
156+
<td>Certificate Thumbprint, CertificateThumbprint</td>
157+
<td></td>
158+
<td>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.</td>
159+
</tr>
120160
<tr id="SslCert">
121161
<td>SSL Cert, SslCert, Ssl-Cert</td>
122162
<td></td>
@@ -135,30 +175,19 @@ These are the options that need to be used in order to configure a connection to
135175
<p>To provide a custom callback to validate the remote certificate, leave this option empty and set <code>SslMode</code> to <code>Required</code> (or <code>Preferred</code>), then set <a href="/api/mysqlconnector/mysqlconnection/remotecertificatevalidationcallback/"><code>MySqlConnection.RemoteCertificateValidationCallback</code></a> before calling <a href="/api/mysqlconnector/mysqlconnection/open/"><code>MySqlConnection.Open</code></a>. The property should be set to a delegate that will validate the remote certificate, as per <a href="https://docs.microsoft.com/en-us/dotnet/api/system.net.security.remotecertificatevalidationcallback" title="RemoteCertificateValidationCallback Delegate (MSDN)">the documentation</a>.</p>
136176
</td>
137177
</tr>
138-
<tr id="CertificateStoreLocation">
139-
<td>Certificate Store Location, CertificateStoreLocation</td>
140-
<td>None</td>
141-
<td>Specifies whether the connection should be encrypted with a certificate from the Certificate Store on the machine. The default value of <code>None</code> means the certificate store is not used; a value of <code>CurrentUser</code> or <code>LocalMachine</code> uses the specified store.</td>
142-
</tr>
143-
<tr id="CertificateThumbprint">
144-
<td>Certificate Thumbprint, CertificateThumbprint</td>
178+
<tr id="TlsVersion">
179+
<td>TLS Version, TlsVersion, Tls-Version</td>
145180
<td></td>
146-
<td>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.</td>
181+
<td>The TLS versions which may be used during TLS negotiation. The default value of <code>null</code> allows the OS to determine the TLS version to use (see <a href="https://docs.microsoft.com/en-us/dotnet/framework/network-programming/tls" title="Transport Layer Security (TLS) best practices with the .NET Framework">documentation</a>); this is the recommended setting. Otherwise, to restrict the versions that can be used, specify a comma-delimited list of versions taken from the following: <code>TLS 1.0</code>, <code>TLS 1.1.</code>, <code>TLS 1.2</code>, <code>TLS 1.3</code>. (This option allows each version to be specified in a few different formats: <code>Tls12</code>, <code> Tlsv1.2</code>, <code>TLS 1.2</code>, <code>Tls v1.2</code>; they are treated equivalently.)</td>
147182
</tr>
148183
<tr id="TlsCipherSuites">
149184
<td>TLS Cipher Suites,TlsCipherSuites</td>
150185
<td></td>
151186
<td>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 <a href="https://docs.microsoft.com/en-us/dotnet/api/system.net.security.tlsciphersuite"><code>TlsCipherSuite</code> enum values</a> to allow just those cipher suites. (This option is only supported on Linux when using .NET Core 3.1 or .NET 5.0 or later.)</td>
152187
</tr>
153-
<tr id="TlsVersion">
154-
<td>TLS Version, TlsVersion, Tls-Version</td>
155-
<td></td>
156-
<td>The TLS versions which may be used during TLS negotiation. The default value of <code>null</code> allows the OS to determine the TLS version to use (see <a href="https://docs.microsoft.com/en-us/dotnet/framework/network-programming/tls" title="Transport Layer Security (TLS) best practices with the .NET Framework">documentation</a>); this is the recommended setting. Otherwise, to restrict the versions that can be used, specify a comma-delimited list of versions taken from the following: <code>TLS 1.0</code>, <code>TLS 1.1.</code>, <code>TLS 1.2</code>, <code>TLS 1.3</code>. (This option allows each version to be specified in a few different formats: <code>Tls12</code>, <code> Tlsv1.2</code>, <code>TLS 1.2</code>, <code>Tls v1.2</code>; they are treated equivalently.)</td>
157-
</tr>
158188
</table>
159189

160-
Connection Pooling Options
161-
--------------------------
190+
## Connection Pooling Options
162191

163192
Connection pooling is enabled by default. These options are used to configure it.
164193

@@ -183,6 +212,11 @@ Connection pooling is enabled by default. These options are used to configure it
183212
<td><code>true</code></td>
184213
<td>If <code>true</code>, all connections retrieved from the pool will have been reset. The default value of <code>true</code> ensures that the connection is in the same state whether it’s newly created or retrieved from the pool. A value of <code>false</code> avoids making an additional server round trip to reset the connection, but the connection state is not reset, meaning that session variables and other session state changes from any previous use of the connection are carried over. Additionally (if <code>Connection Reset</code> is <code>false</code>), when <code>MySqlConnection.Open</code> returns a connection from the pool (instead of opening a new one), the connection may be invalid (and throw an exception on first use) if the server has closed the connection.</td>
185214
</tr>
215+
<tr id="DeferConnectionReset">
216+
<td>Defer Connection Reset, DeferConnectionReset</td>
217+
<td></td>
218+
<td>This option was obsoleted in MySqlConnector 2.0.</td>
219+
</tr>
186220
<tr id="ConnectionIdleTimeout">
187221
<td>Connection Idle Timeout, ConnectionIdleTimeout</td>
188222
<td>180</td>
@@ -200,22 +234,7 @@ Connection pooling is enabled by default. These options are used to configure it
200234
</tr>
201235
</table>
202236

203-
### Connection Pooling with Multiple Servers
204-
205-
The `Server` option supports multiple comma-delimited host names. When this is used with connection
206-
pooling, the `LoadBalance` option controls how load is distributed across backend servers.
207-
208-
* `RoundRobin` (default), `Random`: A total of `MaximumPoolSize` connections will be opened, but they
209-
may be unevenly distributed across back ends.
210-
* `LeastConnections`: A total of `MaximumPoolSize` connections will be opened, and they will be evenly
211-
distributed across back ends. The active connections will be selected from the pool in least-recently-used
212-
order, which does not ensure even load across the back ends. You should set `MaximumPoolSize` to the
213-
number of servers multiplied by the desired maximum number of open connections per backend server.
214-
* `Failover`: All connections will initially be made to the first server in the list. You should set `MaximumPoolSize`
215-
to the maximum number of open connections you want per server.
216-
217-
Other Options
218-
-------------
237+
## Other Options
219238

220239
These are the other options that MySqlConnector supports. They are set to sensible defaults and typically do not need to be tweaked.
221240

@@ -276,13 +295,6 @@ These are the other options that MySqlConnector supports. They are set to sensib
276295
<td>utf8mb4</td>
277296
<td>MySqlConnector always uses <code>utf8mb4</code> to send and receive strings from MySQL Server. This option may be specified (for backwards compatibility) but it will be ignored.</td>
278297
</tr>
279-
<tr id="UseCompression">
280-
<td>Use Compression, Compress, UseCompression</td>
281-
<td>false</td>
282-
<td>If true (and if the server supports compression), compresses packets sent between client and server. This option is unlikely to be useful in
283-
practice unless there is a high-latency or low-bandwidth network link between the application and the database server. You should measure
284-
performance with and without this option to determine if it’s beneficial in your environment.</td>
285-
</tr>
286298
<tr id="ConnectionTimeout">
287299
<td>Connection Timeout, Connect Timeout, ConnectionTimeout</td>
288300
<td>15</td>
@@ -300,10 +312,12 @@ These are the other options that MySqlConnector supports. They are set to sensib
300312
a <code>MySqlException</code> will be thrown if a <code>DateTime</code> command parameter has a <code>Kind</code> of <code>Local</code> or <code>Utc</code>,
301313
respectively.</td>
302314
</tr>
303-
<tr id="DeferConnectionReset">
304-
<td>Defer Connection Reset, DeferConnectionReset</td>
305-
<td></td>
306-
<td>This option was obsoleted in MySqlConnector 2.0.</td>
315+
<tr id="DefaultCommandTimeout">
316+
<td>Default Command Timeout, Command Timeout, DefaultCommandTimeout</td>
317+
<td>30</td>
318+
<td>The length of time (in seconds) each command can execute before the query is cancelled on the server, or zero to disable timeouts.
319+
See the note in the <a href="https://docs.microsoft.com/en-us/dotnet/api/system.data.sqlclient.sqlcommand.commandtimeout">Microsoft documentation</a>
320+
for more explanation of how this is determined.</td>
307321
</tr>
308322
<tr id="GuidFormat">
309323
<td>GUID Format, GuidFormat</td>
@@ -328,13 +342,6 @@ These are the other options that MySqlConnector supports. They are set to sensib
328342
</dl>
329343
</td>
330344
</tr>
331-
<tr id="DefaultCommandTimeout">
332-
<td>Default Command Timeout, Command Timeout, DefaultCommandTimeout</td>
333-
<td>30</td>
334-
<td>The length of time (in seconds) each command can execute before the query is cancelled on the server, or zero to disable timeouts.
335-
See the note in the <a href="https://docs.microsoft.com/en-us/dotnet/api/system.data.sqlclient.sqlcommand.commandtimeout">Microsoft documentation</a>
336-
for more explanation of how this is determined.</td>
337-
</tr>
338345
<tr id="IgnoreCommandTransaction">
339346
<td>Ignore Command Transaction, IgnoreCommandTransaction</td>
340347
<td>false</td>
@@ -358,23 +365,6 @@ These are the other options that MySqlConnector supports. They are set to sensib
358365
<td><p>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.</p>
359366
<p>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.</p></td>
360367
</tr>
361-
<tr id="LoadBalance">
362-
<td>Load Balance, LoadBalance</td>
363-
<td>RoundRobin</td>
364-
<td><p>The load-balancing strategy to use when <code>Host</code> contains multiple, comma-delimited, host names.
365-
The options include:</p>
366-
<dl>
367-
<dt>RoundRobin</dt>
368-
<dd>Each new connection opened for this connection pool uses the next host name (sequentially with wraparound). Requires <code>Pooling=True</code>. This is the default if <code>Pooling=True</code>.</dd>
369-
<dt>FailOver</dt>
370-
<dd>Each new connection tries to connect to the first host; subsequent hosts are used only if connecting to the first one fails. This is the default if <code>Pooling=False</code>.</dd>
371-
<dt>Random</dt>
372-
<dd>Servers are tried in a random order.</dd>
373-
<dt>LeastConnections</dt>
374-
<dd>Servers are tried in ascending order of number of currently-open connections in this connection pool. Requires <code>Pooling=True</code>.</dd>
375-
</dl>
376-
</td>
377-
</tr>
378368
<tr id="NoBackslashEscapes">
379369
<td>No Backslash Escapes, NoBackslashEscapes</td>
380370
<td>false</td>
@@ -431,6 +421,13 @@ These are the other options that MySqlConnector supports. They are set to sensib
431421
<td>false</td>
432422
<td>When <code>false</code> (default), the connection reports found rows instead of changed (affected) rows. Set to <code>true</code> to report only the number of rows actually changed by <code>UPDATE</code> or <code>INSERT … ON DUPLICATE KEY UPDATE</code> statements.</td>
433423
</tr>
424+
<tr id="UseCompression">
425+
<td>Use Compression, Compress, UseCompression</td>
426+
<td>false</td>
427+
<td>If true (and if the server supports compression), compresses packets sent between client and server. This option is unlikely to be useful in
428+
practice unless there is a high-latency or low-bandwidth network link between the application and the database server. You should measure
429+
performance with and without this option to determine if it’s beneficial in your environment.</td>
430+
</tr>
434431
<tr id="UseXaTransactions">
435432
<td>Use XA Transactions, UseXaTransactions</td>
436433
<td>true</td>
@@ -441,9 +438,7 @@ These are the other options that MySqlConnector supports. They are set to sensib
441438
</tr>
442439
</table>
443440

444-
445-
Unsupported Options
446-
-------------
441+
## Unsupported Options
447442

448443
These options are used by Connector/NET but not supported by MySqlConnector. In general, they should be removed
449444
from your connection string when migrating from Connector/NET to MySqlConnector.

0 commit comments

Comments
 (0)