Skip to content

Commit bb40be3

Browse files
ttorblettorble
authored
Merge pull request #263248 from v-luckywang/0111-Update_adf_mysql_v2
[New feature] - Update MySQL V2 connector doc in ADF
2 parents feca1c7 + fdd700a commit bb40be3

File tree

2 files changed

+102
-69
lines changed

2 files changed

+102
-69
lines changed

‎articles/data-factory/connector-mysql.md

Lines changed: 102 additions & 69 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ ms.service: data-factory
77
ms.subservice: data-movement
88
ms.custom: synapse
99
ms.topic: conceptual
10-
ms.date: 10/20/2023
10+
ms.date: 01/16/2024
1111
ms.author: jianleishen
1212
---
1313

@@ -33,7 +33,7 @@ This MySQL connector is supported for the following capabilities:
3333

3434
For a list of data stores that are supported as sources/sinks by the copy activity, see the [Supported data stores](copy-activity-overview.md#supported-data-stores-and-formats) table.
3535

36-
Specifically, this MySQL connector supports MySQL **version 5.6, 5.7 and 8.0**.
36+
This connector supports MySQL version 5.5, 5.6, 5.7, 8.0, 8.1 and 8.2 under the recommended new driver version v2 and 5.6, 5.7 and 8.0 for the legacy driver version.
3737

3838
## Prerequisites
3939

@@ -73,23 +73,21 @@ The following sections provide details about properties that are used to define
7373

7474
## Linked service properties
7575

76-
The following properties are supported for MySQL linked service:
76+
If you use the recommended driver version，the following properties are supported for MySQL linked service:
7777

7878
| Property | Description | Required |
7979
|:--- |:--- |:--- |
8080
| type | The type property must be set to: **MySql** | Yes |
81-
| connectionString | Specify information needed to connect to the Azure Database for MySQL instance.<br/> You can also put password in Azure Key Vault and pull the `password` configuration out of the connection string. Refer to the following samples and [Store credentials in Azure Key Vault](store-credentials-in-key-vault.md) article with more details. | Yes |
81+
| driverVersion | The driver version when you select the recommended driver version. The value is v2. | Yes |
82+
| server | The name of your MySQL Server. | Yes |
83+
| port | The port number to connect to the MySQL server. |No|
84+
| database | Your MySQL database name. |Yes|
85+
| username | Your user name.|Yes|
86+
| password | The password for the user name. Mark this field as SecureString to store it securely. Or, you can [reference a secret stored in Azure Key Vault](store-credentials-in-key-vault.md). | Yes |
87+
| sslMode | This option specifies whether the driver uses TLS encryption and verification when connecting to MySQL. E.g., `SSLMode=<0/1/2/3/4>`.<br/>Options: DISABLED (0) / PREFERRED (1) **(Default)** / REQUIRED (2) / VERIFY_CA (3) / VERIFY_IDENTITY (4) | Yes |
88+
| useSystemTrustStore | This option specifies whether to use a CA certificate from the system trust store, or from a specified PEM file. E.g. `UseSystemTrustStore=<0/1>`;<br/>Options: Enabled (1) / Disabled (0) **(Default)** | No |
8289
| connectVia | The [Integration Runtime](concepts-integration-runtime.md) to be used to connect to the data store. Learn more from [Prerequisites](#prerequisites) section. If not specified, it uses the default Azure Integration Runtime. |No |
8390

84-
A typical connection string is `Server=<server>;Port=<port>;Database=<database>;UID=<username>;PWD=<password>`. More properties you can set per your case:
85-
86-
| Property | Description | Options | Required |
87-
|:--- |:--- |:--- |:--- |
88-
| SSLMode | This option specifies whether the driver uses TLS encryption and verification when connecting to MySQL. E.g., `SSLMode=<0/1/2/3/4>`.| DISABLED (0) / PREFERRED (1) **(Default)** / REQUIRED (2) / VERIFY_CA (3) / VERIFY_IDENTITY (4) | No |
89-
| SSLCert | The full path and name of a .pem file containing the SSL certificate used for proving the identity of the client. <br/> To specify a private key for encrypting this certificate before sending it to the server, use the `SSLKey` property.| | Yes, if using two-way SSL verification. |
90-
| SSLKey | The full path and name of a file containing the private key used for encrypting the client-side certificate during two-way SSL verification.| | Yes, if using two-way SSL verification. |
91-
| UseSystemTrustStore | This option specifies whether to use a CA certificate from the system trust store, or from a specified PEM file. E.g. `UseSystemTrustStore=<0/1>;`| Enabled (1) / Disabled (0) **(Default)** | No |
92-
9391
**Example:**
9492

9593
```json
@@ -98,7 +96,17 @@ A typical connection string is `Server=<server>;Port=<port>;Database=<database>;
9896
"properties": {
9997
"type": "MySql",
10098
"typeProperties": {
101-
"connectionString": "Server=<server>;Port=<port>;Database=<database>;UID=<username>;PWD=<password>"
99+
"server": "<server>",
100+
"port": 3306,
101+
"database": "<database>",
102+
"username": "<username>",
103+
"password": {
104+
"type": "SecureString",
105+
"value": "<password>"
106+
},
107+
"sslmode": <sslmode>,
108+
"usesystemtruststore": <UseSystemTrustStore>,
109+
"driverVersion": "v2"
102110
},
103111
"connectVia": {
104112
"referenceName": "<name of Integration Runtime>",
@@ -116,15 +124,21 @@ A typical connection string is `Server=<server>;Port=<port>;Database=<database>;
116124
"properties": {
117125
"type": "MySql",
118126
"typeProperties": {
119-
"connectionString": "Server=<server>;Port=<port>;Database=<database>;UID=<username>;",
127+
"server": "<server>",
128+
"port": 3306,
129+
"database": "<database>",
130+
"username": "<username>",
131+
"sslmode": <sslmode>,
132+
"usesystemtruststore": <UseSystemTrustStore>,
120133
"password": { 
121134
"type": "AzureKeyVaultSecret", 
122135
"store": { 
123136
"referenceName": "<Azure Key Vault linked service name>", 
124137
"type": "LinkedServiceReference" 
125138
}, 
126139
"secretName": "<secretName>" 
127-
}
140+
},
141+
"driverVersion": "v2"
128142
},
129143
"connectVia": {
130144
"referenceName": "<name of Integration Runtime>",
@@ -134,23 +148,32 @@ A typical connection string is `Server=<server>;Port=<port>;Database=<database>;
134148
}
135149
```
136150

137-
If you were using MySQL linked service with the following payload, it is still supported as-is, while you are suggested to use the new one going forward.
151+
If you use the legacy driver version, the following properties are supported:
152+
153+
| Property | Description | Required |
154+
|:--- |:--- |:--- |
155+
| type | The type property must be set to: **MySql** | Yes |
156+
| connectionString | Specify information needed to connect to the Azure Database for MySQL instance.<br/> You can also put password in Azure Key Vault and pull the `password` configuration out of the connection string. Refer to the following samples and [Store credentials in Azure Key Vault](store-credentials-in-key-vault.md) article with more details. | Yes |
157+
| connectVia | The [Integration Runtime](concepts-integration-runtime.md) to be used to connect to the data store. Learn more from [Prerequisites](#prerequisites) section. If not specified, it uses the default Azure Integration Runtime. | No |
158+
159+
A typical connection string is `Server=<server>;Port=<port>;Database=<database>;UID=<username>;PWD=<password>`. More properties you can set per your case:
160+
161+
| Property | Description | Required |
162+
|:--- |:--- |:--- |
163+
| sslMode | This option specifies whether the driver uses TLS encryption and verification when connecting to MySQL. E.g., `SSLMode=<0/1/2/3/4>`.<br/>Options: DISABLED (0) / PREFERRED (1) **(Default)** / REQUIRED (2) / VERIFY_CA (3) / VERIFY_IDENTITY (4) | Yes |
164+
| SSLCert | The full path and name of a .pem file containing the SSL certificate used for proving the identity of the client. <br/> To specify a private key for encrypting this certificate before sending it to the server, use the `SSLKey` property.| Yes, if using two-way SSL verification. |
165+
| SSLKey | The full path and name of a file containing the private key used for encrypting the client-side certificate during two-way SSL verification.| Yes, if using two-way SSL verification. |
166+
| useSystemTrustStore | This option specifies whether to use a CA certificate from the system trust store, or from a specified PEM file. E.g. `UseSystemTrustStore=<0/1>`;<br/>Options: Enabled (1) / Disabled (0) **(Default)** | No |
138167

139-
**Previous payload:**
168+
**Example:**
140169

141170
```json
142171
{
143172
"name": "MySQLLinkedService",
144173
"properties": {
145174
"type": "MySql",
146175
"typeProperties": {
147-
"server": "<server>",
148-
"database": "<database>",
149-
"username": "<username>",
150-
"password": {
151-
"type": "SecureString",
152-
"value": "<password>"
153-
}
176+
"connectionString": "Server=<server>;Port=<port>;Database=<database>;UID=<username>;PWD=<password>"
154177
},
155178
"connectVia": {
156179
"referenceName": "<name of Integration Runtime>",
@@ -242,54 +265,64 @@ If you were using `RelationalSource` typed source, it is still supported as-is,
242265

243266
When copying data from MySQL, the following mappings are used from MySQL data types to interim data types used by the service internally. See [Schema and data type mappings](copy-activity-schema-and-type-mapping.md) to learn about how copy activity maps the source schema and data type to the sink.
244267

245-
| MySQL data type | Interim service data type |
246-
|:--- |:--- |
247-
| `bigint` |`Int64` |
248-
| `bigint unsigned` |`Decimal` |
249-
| `bit(1)` |`Boolean` |
250-
| `bit(M), M>1`|`Byte[]`|
251-
| `blob` |`Byte[]` |
252-
| `bool` |`Int16` |
253-
| `char` |`String` |
254-
| `date` |`Datetime` |
255-
| `datetime` |`Datetime` |
256-
| `decimal` |`Decimal, String` |
257-
| `double` |`Double` |
258-
| `double precision` |`Double` |
259-
| `enum` |`String` |
260-
| `float` |`Single` |
261-
| `int` |`Int32` |
262-
| `int unsigned` |`Int64`|
263-
| `integer` |`Int32` |
264-
| `integer unsigned` |`Int64` |
265-
| `json` |`String` |
266-
| `long varbinary` |`Byte[]` |
267-
| `long varchar` |`String` |
268-
| `longblob` |`Byte[]` |
269-
| `longtext` |`String` |
270-
| `mediumblob` |`Byte[]` |
271-
| `mediumint` |`Int32` |
272-
| `mediumint unsigned` |`Int64` |
273-
| `mediumtext` |`String` |
274-
| `numeric` |`Decimal` |
275-
| `real` |`Double` |
276-
| `set` |`String` |
277-
| `smallint` |`Int16` |
278-
| `smallint unsigned` |`Int32` |
279-
| `text` |`String` |
280-
| `time` |`TimeSpan` |
281-
| `timestamp` |`Datetime` |
282-
| `tinyblob` |`Byte[]` |
283-
| `tinyint` |`Int16` |
284-
| `tinyint unsigned` |`Int16` |
285-
| `tinytext` |`String` |
286-
| `varchar` |`String` |
287-
| `year` |`Int` |
288-
268+
| MySQL data type | Interim service data type | Interim service data type (for the legacy driver version) |
269+
|:--- |:--- |:--- |
270+
| `bigint` |`Int64` |`Int64` |
271+
| `bigint unsigned` |`Decimal` |`Decimal` |
272+
| `bit(1)` |`UInt64` |`Boolean` |
273+
| `bit(M), M>1`|`UInt64`|`Byte[]`|
274+
| `blob` |`Byte[]` |`Byte[]` |
275+
| `bool` |`Boolean` <br/>(If TreatTinyAsBoolean=false, it is mapped as `SByte`. TreatTinyAsBoolean is true by default ) |`Int16` |
276+
| `char` |`String` |`String` |
277+
| `date` |`Datetime` |`Datetime` |
278+
| `datetime` |`Datetime` |`Datetime` |
279+
| `decimal` |`Decimal` |`Decimal, String` |
280+
| `double` |`Double` |`Double` |
281+
| `double precision` |`Double` |`Double` |
282+
| `enum` |`String` |`String` |
283+
| `float` |`Single` |`Single` |
284+
| `int` |`Int32` |`Int32` |
285+
| `int unsigned` |`Int64`|`Int64`|
286+
| `integer` |`Int32` |`Int32` |
287+
| `integer unsigned` |`Int64` |`Int64` |
288+
| `JSON` |`String` |-|
289+
| `long varbinary` |`Byte[]` |`Byte[]` |
290+
| `long varchar` |`String` |`String` |
291+
| `longblob` |`Byte[]` |`Byte[]` |
292+
| `longtext` |`String` |`String` |
293+
| `mediumblob` |`Byte[]` |`Byte[]` |
294+
| `mediumint` |`Int32` |`Int32` |
295+
| `mediumint unsigned` |`Int64` |`Int64` |
296+
| `mediumtext` |`String` |`String` |
297+
| `numeric` |`Decimal` |`Decimal` |
298+
| `real` |`Double` |`Double` |
299+
| `set` |`String` |`String` |
300+
| `smallint` |`Int16` |`Int16` |
301+
| `smallint unsigned` |`Int32` |`Int32` |
302+
| `text` |`String` |`String` |
303+
| `time` |`TimeSpan` |`TimeSpan` |
304+
| `timestamp` |`Datetime` |`Datetime` |
305+
| `tinyblob` |`Byte[]` |`Byte[]` |
306+
| `tinyint` |`SByte` |`Int16` |
307+
| `tinyint unsigned` |`Int16` |`Int16` |
308+
| `tinytext` |`String` |`String` |
309+
| `varchar` |`String` |`String` |
310+
| `year` |`Int` |`Int` |
289311

290312
## Lookup activity properties
291313

292314
To learn details about the properties, check [Lookup activity](control-flow-lookup-activity.md).
293315

316+
## Upgrade the MySQL driver version
317+
318+
Here are steps that help you upgrade your MySQL driver version:
319+
320+
1. Create a new MySQL linked service and configure it by referring to [Linked service properties](connector-mysql.md#linked-service-properties).
321+
322+
1. The data type mapping for the latest MySQL linked service is different from that for the legacy version. To learn the latest data type mapping, see [Data type mapping for MySQL](connector-mysql.md#data-type-mapping-for-mysql).
323+
324+
1. More MySQL versions are supported for the latest driver version. For more information, see [Supported capabilities](connector-mysql.md#supported-capabilities).
325+
294326
## Related content
327+
295328
For a list of data stores supported as sources and sinks by the copy activity, see [supported data stores](copy-activity-overview.md#supported-data-stores-and-formats).

‎articles/data-factory/media/connector-mysql/configure-mysql-linked-service.png

-2.27 KB
Loading

0 commit comments

Comments
 (0)