Skip to content

Commit a4008a9

Browse files
laurabrenlaurabren
authored
Merge pull request #20913 from nahk-ivanov/alexiva/update-dsct-config-docs
Document DSCT00005 and new configuration
2 parents 5925a2f + 231e746 commit a4008a9

3 files changed

Lines changed: 136 additions & 2 deletions

File tree

‎docs/azure-data-studio/extensions/dsct/conversion-messages/dsct00005.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
---
2+
title: "DSCT00005: Conversion of system identifier is not supported (Error)"
3+
description: "Covers the reason why Database Schema Conversion Toolkit isn't able to convert certain built-in system identifiers."
4+
ms.prod: azure-data-studio
5+
ms.technology: azure-data-studio
6+
author: nahk-ivanov
7+
ms.author: "alexiva"
8+
ms.reviewer: "maghan"
9+
ms.topic: reference
10+
ms.custom:
11+
ms.date: "12/21/2021"
12+
---
13+
14+
# DSCT00005: Conversion of system identifier is not supported (Error)
15+
16+
This article covers the reason why Database Schema Conversion Toolkit isn't able to convert certain built-in system identifiers.
17+
18+
## Background
19+
20+
Different database platforms provide different built-in functionality, including everything from catalog tables and views (for example, `sys.tables`, `sys.columns` in Microsoft SQL) to special functions and procedures. Not all built-in system objects from the source database have a corresponding match in the new target database. The Database Schema Conversion Toolkit will attempt to emulate the functionality of the source database, but sometimes it isn't possible. In such cases a `DSCT00005` error message is produced.
21+
22+
## Example
23+
24+
Consider the below query using Oracle's `SYS.ALL_UNUSED_COL_TABS` data dictionary:
25+
26+
```sql
27+
SELECT
28+
TABLE_NAME
29+
FROM
30+
SYS.ALL_UNUSED_COL_TABS
31+
WHERE
32+
OWNER = 'TEST'
33+
```
34+
35+
When converting this query targeting Microsoft SQL platform, a `DSCT00005` error message will be produced, as Microsoft SQL does not have a concept of unused table columns.
36+
37+
## Possible remedies
38+
39+
Review the converted code to determine whether this functionality is business-critical or does not apply to the new database platform. Depending on a certain scenario it may not be necessary to transfer the logic in question to the new database platform, like in the example above, where there is simply no concept of the unused columns in the new database platform. In other situations, the code that failed to convert might be a part of the application business logic which cannot be removed. In such cases, the logic will need to be converted manually.

‎docs/azure-data-studio/extensions/dsct/conversion-messages/toc.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@
88
href: dsct00003.md
99
- name: DSCT00004
1010
href: dsct00004.md
11+
- name: DSCT00005
12+
href: dsct00005.md
1113
- name: DSCT01000
1214
href: dsct01000.md
1315
- name: DSCT01001

‎docs/azure-data-studio/extensions/dsct/oracle-to-mssql/configure-conversion.md‎

Lines changed: 95 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,10 @@ Basic structure of the configuration file looks as following:
3030
```json
3131
{
3232
"options" : <simple-conversion-options>,
33+
"dataTypeMappings": [
34+
<data-type-mapping>,
35+
...
36+
],
3337
"nameMappings": [
3438
<object-name-mapping>,
3539
...
@@ -67,6 +71,79 @@ Following table describes all possible configuration options in this region:
6771
| `quoteIdentifiers` | Determines whether all identifiers should be quoted in converted SQL scripts. Default is `true`. It is recommended to set it to `true`, as quotation might be required when special characters are used in identifier names. |
6872
| `isMsSqlCaseSensitive` | Controls whether [DSCT01000](../conversion-messages/dsct01000.md) conversion message will be produced during conversion. This option will be derived from the default collation of the target SQL Database project and you should not need to set it explicitly. |
6973

74+
### Data type mappings
75+
76+
The `dataTypeMappings` configuration region consists of multiple data type mapping records. Each data type mapping record has the following schema:
77+
78+
```json
79+
{
80+
"source": {
81+
"type": "<oracle-data-type-name>",
82+
"arguments": [
83+
<argument-value-matching-expression>,
84+
...
85+
]
86+
},
87+
"target": {
88+
"type": "<ms-sql-data-type-name>",
89+
"arguments": [
90+
<argument-value-expression>,
91+
...
92+
]
93+
}
94+
}
95+
```
96+
97+
The `source` section defines the source data type that is being mapped and consists of two parts:
98+
- `type` is the name of the Oracle data type to map;
99+
- `arguments` is the collection of matching expressions that will further filter a data type based on its arguments values.
100+
101+
The source `arguments` collection defines matching expressions for data type arguments based on their position. The collection should contain one string expression for each data type argument. Supported expressions are:
102+
103+
| Expression | Meaning |
104+
| ---------- | ------- |
105+
| `"<number>"` | Matches the exact value of an argument. |
106+
| `"*"` | Matches special `*` argument value. For example, the first argument in the `NUMBER(*, 5)` data type definition. |
107+
| `"X..Y"` | Matches an argument value in the `[X, Y]` range, where `X` and `Y` can be either `<number>` or `*`. The `*` in the range expression means _unbound_. To match any argument value the `"*..*"` range expression can be used. |
108+
109+
Some data types may have their arguments specified within the type name, for example `INTERVAL DAY (2) TO SECOND (6)`. In such cases, the type name would be `INTERVAL DAY TO SECOND`, while `2` and `6` are considered first and second arguments respectively.
110+
111+
The `target` section of the data type mapping record defines the Microsoft SQL data type that should be used in the target database and consists of two parts:
112+
- `type` is the name of the Microsoft SQL data type to map to;
113+
- `arguments` is the collection of expressions that define values for the target data type arguments.
114+
115+
The `arguments` collection defines data type arguments value expressions based on the arguments position. The collection should contain one string expression for each data type argument. Supported expressions are:
116+
117+
| Expression | Meaning |
118+
| ---------- | ------- |
119+
| `"<number>"` | Specifies an exact value of an argument. |
120+
| `"$<number>"` | Specifies that a value of the `<number>` source argument should be used. The index is 1-based. For example, `$2` will be replaced with the value of the second argument of the matched source data type. |
121+
122+
The following example demonstrates how to map the `VARCHAR2` Oracle data type that holds 4000 characters or less, to the `NVARCHAR` Microsoft SQL data type of the same length as the source data type:
123+
124+
```json
125+
{
126+
"source": {
127+
"type": "VARCHAR2",
128+
"arguments": [
129+
"*..4000"
130+
]
131+
},
132+
"target": {
133+
"type": "NVARCHAR",
134+
"arguments": [
135+
"$1"
136+
]
137+
}
138+
}
139+
```
140+
141+
> [!IMPORTANT]
142+
> Data type mappings should be defined from the least specific to the more specific, as they will be applied in reverse order. In other words, every subsequent data type mapping overrides (entirely or in part) previously defined mappings.
143+
144+
> [!NOTE]
145+
> Database Schema Conversion Toolkit comes with the built-in data type mappings that cover common scenarios, thus custom data type mappings are not required in most cases.
146+
70147
### Object name mappings
71148

72149
The `nameMappings` configuration region consists of multiple name mapping records. Each name mapping record has the following schema:
@@ -135,10 +212,26 @@ The `target` property is always a simple string that defines new name for the so
135212
136213
### Examples
137214

138-
Following example demonstrates entire configuration file that maps `HR` Oracle schema to `dbo` in the target database:
215+
Following example demonstrates entire configuration file that maps the `VARCHAR2` Oracle data type that holds 4000 characters or less, to the `NVARCHAR` Microsoft SQL data type of the same length as the source data type, while also replacing `HR` Oracle schema with `dbo` in the target database:
139216

140217
```json
141218
{
219+
"dataTypeMappings": [
220+
{
221+
"source": {
222+
"type": "VARCHAR2",
223+
"arguments": [
224+
"*..4000"
225+
]
226+
},
227+
"target": {
228+
"type": "NVARCHAR",
229+
"arguments": [
230+
"$1"
231+
]
232+
}
233+
}
234+
],
142235
"nameMappings": [
143236
{
144237
"source": [
@@ -150,4 +243,4 @@ Following example demonstrates entire configuration file that maps `HR` Oracle s
150243
}
151244
```
152245

153-
When this configuration is used all converted objects from `HR` schema will be defined under the `dbo` schema.
246+
When this configuration is used all converted objects from `HR` schema will be defined under the `dbo` schema and all matching references to the `VARCHAR2` data type will be replaced with the `NVARCHAR`.

0 commit comments

Comments
 (0)