Skip to content

Commit 4ad75e5

Browse files
Lucky-Wang16Lucky-Wang16
committed
Update Amazon RDS for Oracle V2
1 parent 71045ab commit 4ad75e5

File tree

2 files changed

+157
-2
lines changed

2 files changed

+157
-2
lines changed

‎articles/data-factory/connector-amazon-rds-for-oracle.md

Lines changed: 157 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ author: jianleishen
66
ms.subservice: data-movement
77
ms.custom: synapse
88
ms.topic: conceptual
9-
ms.date: 01/05/2024
9+
ms.date: 05/22/2025
1010
ms.author: jianleishen
1111
---
1212

@@ -31,7 +31,9 @@ This Amazon RDS for Oracle connector is supported for the following capabilities
3131

3232
Specifically, this Amazon RDS for Oracle connector supports:
3333

34-
- The following versions of an Amazon RDS for Oracle database:
34+
- The following versions of an Amazon RDS for Oracle database for version 2.0:
35+
- Amazon RDS for Oracle 19c or later
36+
- The following versions of an Amazon RDS for Oracle database for version 1.0:
3537
- Amazon RDS for Oracle 19c R1 (19.1) and higher
3638
- Amazon RDS for Oracle 18c R1 (18.1) and higher
3739
- Amazon RDS for Oracle 12c R1 (12.1) and higher
@@ -79,6 +81,104 @@ The following sections provide details about properties that are used to define
7981

8082
## Linked service properties
8183

84+
The Amazon RDS for Oracle connector now supports version 2.0. Refer to this [section](#upgrade-the-amazon-rds-for-oracle-connector) to upgrade your Amazon RDS for Oracle connector connector version from version 1.0. For the property details, see the corresponding sections.
85+
86+
- [Version 2.0](#version-20)
87+
- [Version 1.0](#version-10)
88+
89+
### Version 2.0
90+
91+
The Amazon RDS for Oracle connector linked service supports the following properties when apply version 2.0:
92+
93+
| Property | Description | Required |
94+
|:--- |:--- |:--- |
95+
| type | The type property must be set to **AmazonRdsForOracle**. | Yes |
96+
| version | The version that you specify. The value is `2.0`. | Yes |
97+
| server | The location of Amazon RDS for Oracle database you want to connect to. You can refer to [server property configuration](#server-property-configuration) to specify it. | Yes |
98+
| authenticationType | Authentication type for connecting to the Amazon RDS for Oracle database. Only **Basic** auth is supported now. | Yes |
99+
| username | The Amazon RDS for Oracle database username. | Yes |
100+
| password | The Amazon RDS for Oracle database password. 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 |
101+
| 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, the default Azure Integration Runtime is used. |No |
102+
103+
More connection properties you can set in linked service per your case:
104+
105+
| Property | Description | Required | Default value |
106+
|:--- |:--- |:--- |:--- |
107+
| encryptionClient | Specifies the encryption client behavior. Supported values are `accepted`, `rejected`, `requested`, or `required`. Type: string | No | `required` |
108+
| encryptionTypesClient | Specifies the encryption algorithms that client can use. Supported values are `AES128`, `AES192`, `AES256`, `3DES112`, `3DES168`. Type: string | No | `(AES256)` |
109+
| cryptoChecksumClient | Specifies the desired data integrity behavior when this client connects to a server. Supported values are `accepted`, `rejected`, `requested`, or `required`. Type: string | No | `required` |
110+
| cryptoChecksumTypesClient | Specifies the crypto-checksum algorithms that client can use. Supported values are `SHA1`, `SHA256`, `SHA384`, `SHA512`. Type: string | No | `(SHA512)` |
111+
| initialLobFetchSize | Specifies the amount that the source initially fetches for LOB columns. Type: int | No | 0 |
112+
| fetchSize | Specifies the number of bytes that the driver allocates to fetch the data in one database round-trip. Type: int | No | 10 MB |
113+
| statementCacheSize | Specifies the number of cursors or statements to be cached for each database connection. Type: int | No | 0 |
114+
| initializationString | Specifies a command that is issued immediately after connecting to the database to manage session settings. Type: string | No | null |
115+
| enableBulkLoad | Specifies whether to use bulk copy or batch insert when loading data into the database. Type: boolean | No | true |
116+
| supportV1DataTypes | Specifies whether to use the version 1.0 data type mappings. Do not set this to true unless you want to keep backward compatibility with version 1.0's data type mappings. Type: boolean | No, this property is for backward compatibility use only | false |
117+
| fetchTswtzAsTimestamp | Specifies whether the driver returns column value with the TIMESTAMP WITH TIME ZONE data type as DateTime or string. This setting is ignored if supportV1DataTypes is not true. Type: boolean | No, this property is for backward compatibility use only | true |
118+
119+
**Example:**
120+
121+
```json
122+
{
123+
"name": "AmazonRdsForOracleLinkedService",
124+
"properties": {
125+
"type": "AmazonRdsForOracle",
126+
"version": "2.0",
127+
"typeProperties": {
128+
"server": "<server name>",
129+
"username": "<user name>",
130+
"password": "<password>",
131+
"authenticationType": "<authentication type>"
132+
},
133+
"connectVia": {
134+
"referenceName": "<name of Integration Runtime>",
135+
"type": "IntegrationRuntimeReference"
136+
}
137+
}
138+
}
139+
```
140+
141+
**Example: store password in Azure Key Vault**
142+
143+
```json
144+
{
145+
"name": "AmazonRdsForOracleLinkedService",
146+
"properties": {
147+
"type": "AmazonRdsForOracle",
148+
"version": "2.0",
149+
"typeProperties": {
150+
"server": "<server name>",
151+
"username": "<user name>",
152+
"authenticationType": "<authentication type>",
153+
"password": {
154+
"type": "AzureKeyVaultSecret",
155+
"store": {
156+
"referenceName": "<Azure Key Vault linked service name>",
157+
"type": "LinkedServiceReference"
158+
},
159+
"secretName": "<secretName>"
160+
}
161+
},
162+
"connectVia": {
163+
"referenceName": "<name of Integration Runtime>",
164+
"type": "IntegrationRuntimeReference"
165+
}
166+
}
167+
}
168+
```
169+
170+
#### `server` property configuration
171+
172+
For `server` property, you can specify it in one of the following three formats:
173+
174+
| Format | Example |
175+
|:--- |:--- |
176+
|[Connect Descriptor](https://docs.oracle.com/en/database/oracle/oracle-database/23/netag/identifying-and-accessing-database.html#GUID-8D28E91B-CB72-4DC8-AEFC-F5D583626CF6)| (DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=sales-server)(PORT=1521))(CONNECT_DATA=(SERVICE_NAME=sales.us.acme.com)))|
177+
|[Easy Connect (Plus) Naming](https://download.oracle.com/ocomdocs/global/Oracle-Net-Easy-Connect-Plus.pdf)|salesserver1:1521/sales.us.example.com|
178+
|[Oracle Net Services Name (TNS Alias)](https://docs.oracle.com/en/database/oracle/oracle-database/23/netrf/local-naming-parameters-in-tns-ora-file.html#GUID-12C94B15-2CE1-4B98-9D0C-8226A9DDF4CB) (only for the self-hosted integration runtime)|sales|
179+
180+
### Version 1.0
181+
82182
The Amazon RDS for Oracle linked service supports the following properties:
83183

84184
| Property | Description | Required |
@@ -229,6 +329,7 @@ To copy data from Amazon RDS for Oracle, set the source type in the copy activit
229329
|:--- |:--- |:--- |
230330
| type | The type property of the copy activity source must be set to `AmazonRdsForOracleSource`. | Yes |
231331
| oracleReaderQuery | Use the custom SQL query to read data. An example is `"SELECT * FROM MyTable"`.<br>When you enable partitioned load, you need to hook any corresponding built-in partition parameters in your query. For examples, see the [Parallel copy from Amazon RDS for Oracle](#parallel-copy-from-amazon-rds-for-oracle) section. | No |
332+
| convertDecimalToInteger | Oracle NUMBER type with zero or unspecified scale will be converted to corresponding integer. Allowed values are **true** and **false** (default). <br>If you are using Oracle version 2.0, this property will only be allowed to be set when supportV1DataTypes is true. | No |
232333
| partitionOptions | Specifies the data partitioning options used to load data from Amazon RDS for Oracle. <br>Allowed values are: **None** (default), **PhysicalPartitionsOfTable**, and **DynamicRange**.<br>When a partition option is enabled (that is, not `None`), the degree of parallelism to concurrently load data from an Amazon RDS for Oracle database is controlled by the [`parallelCopies`](copy-activity-performance-features.md#parallel-copy) setting on the copy activity. | No |
233334
| partitionSettings | Specify the group of the settings for data partitioning. <br>Apply when the partition option isn't `None`. | No |
234335
| partitionNames | The list of physical partitions that needs to be copied. <br>Apply when the partition option is `PhysicalPartitionsOfTable`. If you use a query to retrieve the source data, hook `?AdfTabularPartitionName` in the WHERE clause. For an example, see the [Parallel copy from Amazon RDS for Oracle](#parallel-copy-from-amazon-rds-for-oracle) section. | No |
@@ -258,6 +359,7 @@ To copy data from Amazon RDS for Oracle, set the source type in the copy activit
258359
"typeProperties": {
259360
"source": {
260361
"type": "AmazonRdsForOracleSource",
362+
"convertDecimalToInteger": false,
261363
"oracleReaderQuery": "SELECT * FROM MyTable"
262364
},
263365
"sink": {
@@ -318,10 +420,63 @@ You are suggested to enable parallel copy with data partitioning especially when
318420
}
319421
}
320422
```
423+
## Data type mapping for Amazon RDS for Oracle
424+
425+
When you copy data from and to Amazon RDS for Oracle, the following interim data type mappings are used within the service. To learn about how the copy activity maps the source schema and data type to the sink, see [Schema and data type mappings](copy-activity-schema-and-type-mapping.md).
426+
427+
| Amazon RDS for Oracle data type | Interim service data type (for version 2.0) | Interim service data type (for version 1.0) |
428+
|:--- |:--- |:--- |
429+
| BFILE |Byte[] | Byte[] |
430+
| BINARY_FLOAT | Single | Single |
431+
| BINARY_DOUBLE | Double | Double |
432+
| BLOB |Byte[] | Byte[] |
433+
| CHAR |String |String |
434+
| CLOB |String |String |
435+
| DATE |DateTime |DateTime |
436+
| FLOAT (P < 16) | Double | Double |
437+
| FLOAT (P >= 16) | Decimal | Double |
438+
| INTERVAL YEAR TO MONTH |Int64 |String |
439+
| INTERVAL DAY TO SECOND |TimeSpan |String |
440+
| LONG |String |String |
441+
| LONG RAW |Byte[] |Byte[] |
442+
| NCHAR |String |String |
443+
| NCLOB |String |String |
444+
| NUMBER (p,s) |Int16, Int32, Int64, Double, Single, Decimal |Decimal, String (if p > 28) |
445+
| NUMBER without precision and scale | Decimal |Double |
446+
| NVARCHAR2 |String |String |
447+
| RAW |Byte[] |Byte[] |
448+
| TIMESTAMP |DateTime |DateTime |
449+
| TIMESTAMP WITH LOCAL TIME ZONE |DateTime |DateTime |
450+
| TIMESTAMP WITH TIME ZONE |DateTimeOffset |DateTime |
451+
| VARCHAR2 |String |String |
452+
| XMLTYPE |String |String |
453+
454+
> [!NOTE]
455+
> NUMBER(p,s) is mapped to the appropriate interim service data type depending on the precision (p) and scale (s).
321456
322457
## Lookup activity properties
323458

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

461+
## Upgrade the Amazon RDS for Oracle connector
462+
463+
Here are steps that help you upgrade the Amazon RDS for Oracle connector:
464+
465+
1. In **Edit linked service** page, select version 2.0 and configure the linked service by referring to [Linked service properties version 2.0](#version-20).
466+
467+
2. The data type mapping for the Amazon RDS for Oracle linked service version 2.0 is different from that for the version 1.0. To learn the latest data type mapping, see [Data type mapping for Amazon RDS for Oracle](#data-type-mapping-for-amazon-rds-for-oracle).
468+
469+
An additional connection property `supportV1DataTypes` in version 2.0 can reduce upgrade difficulties caused by data type changes. Setting this property to `true` ensures that the data type in version 2.0 remains consistent with version 1.0.
470+
471+
## Differences between Amazon RDS for Oracle version 2.0 and version 1.0
472+
473+
The Amazon RDS for Oracle connector version 2.0 offers new functionalities and is compatible with most features of version 1.0. The following table shows the feature differences between version 2.0 and version 1.0.
474+
475+
| Version 2.0 | Version 1.0  |
476+
|:--- |:--- |
477+
|The following mappings are used from Amazon RDS for Oracle data types to interim service data types used by the service internally. <br><br>NUMBER(p,s) -> Int16, Int32, Int64, Double, Single, Decimal <br>FLOAT(p)-> Double or Decimal based on its precision <br>NUMBER -> Decimal <br>TIMESTAMP WITH TIME ZONE -> DateTimeOffset <br>INTERVAL YEAR TO MONTH -> Int64 <br>INTERVAL DAY TO SECOND -> TimeSpan |The following mappings are used from Amazon RDS for Oracle data types to interim service data types used by the service internally. <br><br>NUMBER(p,s) -> Decimal or String based on its precision <br>FLOAT(p)-> Double <br>NUMBER -> Double <br>TIMESTAMP WITH TIME ZONE -> DateTime <br>INTERVAL YEAR TO MONTH -> String <br>INTERVAL DAY TO SECOND -> String |
478+
| Support convertDecimalToInteger in copy source when `supportV1DataTypes` is set to `true`. | Support convertDecimalToInteger in copy source.  |
479+
480+
326481
## Related content
327482
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-amazon-rds-for-oracle/configure-amazon-rds-for-oracle-linked-service.png

-3.38 KB
Loading

0 commit comments

Comments
 (0)