Skip to content

Commit 3ec25a3

Browse files
gvasquezvargasgvasquezvargas
authored
Merge pull request #5959 from EnterpriseDB/mtk/options_file
MTK: Added new pages for MTK options file feature
2 parents 26f21ce + a367612 commit 3ec25a3

File tree

4 files changed

+242
-0
lines changed

4 files changed

+242
-0
lines changed

‎product_docs/docs/migration_toolkit/55/07_invoking_mtk/08_mtk_command_options.mdx

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,9 +28,14 @@ The command options that work with Migration Toolkit are grouped by their behavi
2828
| [Oracle-specific options](#oracle-specific-options) | -allUsers, -users,<br /><br />-allProfiles, -profiles,<br /><br />-importPartitionAsTable,<br /><br />-objectTypes,<br /><br />-copyViaDBLinkOra, -allDBLinks<br /><br />-allSynonyms, -allPublicSynonyms, -excludeSynonyms,<br /><br />-allPrivateSynonyms, -useOraCase,<br /><br />-skipUserSchemaCreation |
2929
| [Miscellaneous options](#miscellaneous-options) | -help, -logDir, -logFileCount, -logFileSize, -logBadSQL -verbose, -version |
3030
| [Migration options for parallel data loading](#migration-options-for-parallel-data-loading) | -loaderCount, -parallelLoadRowLimit, -tableLoaderLimit |
31+
| [Specify options in file](mtk_command_options_in_file) | -optionsFile |
3132

3233
<div id="offline_migration" class="registered_link"></div>
3334

35+
!!!note
36+
If you are using several options for a migration, or have to specify a long list of objects for an option, consider using the `-optionsFile` option to specify the values in a separate text file. See [Specifying options using a file](mtk_command_options_in_file) for more information.
37+
!!!
38+
3439
## Offline migration options
3540

3641
If you specify the `-offlineMigration` option in the command line, Migration Toolkit performs an offline migration. During an offline migration, Migration Toolkit reads the definition of each selected object and creates an SQL script that, when executed later, replicates each object in Postgres.

‎product_docs/docs/migration_toolkit/55/07_invoking_mtk/mtk_command_options_in_file/creating_txt_file.mdx

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
---
2+
title: "Creating a file with the command options"
3+
navTitle: "Creating the options file"
4+
deepToC: true
5+
---
6+
7+
To specify a text file that contains command line options and values, you must create a `<example.options>` file with the options you want to execute, and then run the `runMTK.sh` command with the `-optionsFile <example.options>` argument.
8+
9+
!!!note
10+
You can store the `<example.options>` file in the same folder as the MTK utility, or in a directory of your choice.
11+
!!!
12+
13+
## Creating the text file - guidelines
14+
15+
Create a text file on a location that is accessible by the user performing the migration. Then, add an option per line following these guidelines:
16+
17+
### Skip the dash
18+
19+
Use the same option syntax as in the command line options without the dash sign (-). The options file recognizes each line as a new parameter and doesn't require a dash as a delimiter.
20+
21+
| Option in CLI | Supported syntax for the option in file |
22+
|----------------|-----------------------------------------|
23+
| `-tables hr` | tables hr |
24+
25+
### Use a line per option
26+
27+
Use a new line for each option. Use a line per key-value pair.
28+
29+
| Option in CLI | Supported syntax for the option in file |
30+
|----------------------------------------------------------------|---------------------------------------------------------------|
31+
| `-tables hr -allViews` <br/> `-excludeViews all_emp,acct_list` | tables hr <br/> allViews <br/> excludeViews all_emp,acct_list |
32+
33+
### Specify values for an option in a single or multiple lines
34+
35+
You can add a single line with an option and multiple values for that option.
36+
37+
You can add several lines for the same option, each time with a different value.
38+
39+
And you can combine both approaches, because MTK will combine all lines that have the same option.
40+
41+
| Option in CLI | Supported syntax for the option in file |
42+
|--------------------------|-------------------------------------------------|
43+
| `-tables TAB1,TAB2,TAB3` | tables TAB1 <br/> tables TAB2 <br/> tables TAB3 |
44+
| | tables TAB1,TAB2,TAB3 |
45+
| | tables TAB1 <br/> tables TAB2,TAB3 |
46+
47+
!!!note
48+
The duplication of options is only supported for the options file. <br/>
49+
When using `-tables` in the command line more than one time, only the last parameter is executed. For example, `./runMTK.sh -tables TAB2 -tables TAB3` only includes the _TAB3_ table in the migration.
50+
!!!
51+
52+
### Use a space or equal sign to provide values
53+
54+
For options that require values (key-value pairs), separate the option from the value with a space or an equal sign (=). Both options are supported.
55+
56+
| Option in CLI | Supported syntax for the option in file |
57+
|------------------|-----------------------------------------|
58+
| `-views all_emp` | views=all_emp |
59+
| | views all_emp |
60+
61+
### Don't specify an option in the file and command line
62+
63+
Don't include an option in the options file if you're specifying it as a flag in the command line.
64+
65+
Specifying an option in both the command line and in the text file will cause the migration to fail.
66+
67+
## Order of processing
68+
69+
Migration Toolkit reads command line options and option files in the order you provide them when running the command.
70+
71+
For example, if you run the following command, MTK first recognizes the `-sourcedbtype oracle` option, then reads the contents of `example.options` in order from top to bottom. Last parameter is always `schema_name`.
72+
73+
```shell
74+
runMTK.sh -sourcedbtype oracle -optionsFile example.options schema_name
75+
```
76+
77+
If you want an option to be executed last, you can either put it at the end of the `example.options` file and add no further options after `-optionsFile` in the command line.
78+
79+
Schema definition (`schema_name` or `-allSchemas`) must always be the last parameter on the command line.
80+
81+
```shell
82+
runMTK.sh -sourcedbtype oracle -optionsFile example.options schema_name
83+
```
84+
85+
Where the content of the `example.options` file is:
86+
87+
```
88+
tables=TAB1
89+
dataOnly
90+
```
91+
92+
Or you can place the options flag (-dataOnly in this case) in the command line after specifying the `-optionsFile`:
93+
94+
```shell
95+
runMTK.sh -sourcedbtype oracle -optionsFile example.options -dataOnly schema_name
96+
```
97+
98+
## Other considerations
99+
100+
- **Commenting out**: Use a pound sign (#) to comment out a line. MTK won’t execute that line.
101+
102+
- **Limitations**: Do not use quote marks.
103+
104+
- **Space processing**: MTK removes spaces between an option and its value. When you separate an option from its value with a space, only one space is treated as a delimiter.
105+
106+
For example, to run the `-views all_emp, mgmt_list, acct_list` command line option, you can add _views all_emp,mgmt_list,acct_list_ OR _views = all_emp,mgmt_list,acct_list_ in the options file.
107+
108+
After you have created the options file, [execute the migration with the options file](executing_migration_with_txt).

‎product_docs/docs/migration_toolkit/55/07_invoking_mtk/mtk_command_options_in_file/executing_migration_with_txt.mdx

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
---
2+
title: "Executing a migration with a command options file"
3+
navTitle: "Executing a migration with the options file"
4+
deepToC: true
5+
---
6+
7+
After you have created the options file, execute the migration command by referencing the options file:
8+
9+
```shell
10+
./runMTK.sh -optionsFile <example.options>
11+
```
12+
13+
!!!note
14+
Provide the full path for `<example.options>` if you are running the MTK command from a different folder than where you have stored the file.
15+
!!!
16+
17+
You can specify all options in the file, or use a mix of command line and options file to specify the migration parameters.
18+
19+
## Provide the scope for the schema migration
20+
21+
You must specify the scope of the schemas to be migrated.
22+
23+
- If you want to migrate all schemas: Add the `-allSchemas` option in the command line or add `allSchemas` in your options file. Regardless of which method you use, this option must be the last parameter.
24+
25+
- If you want to specify one or several schemas: Specify the schemas you want to migrate in the command line with no preceding option. They have to be the last parameter in the command line.
26+
27+
Here are some examples for specifying all options in the file:
28+
29+
## Migrate a schema with specific tables
30+
31+
Content of the `<example.options>` text file:
32+
33+
```
34+
tables comp_schema.emp,comp_schema.dept,finance_schema.acctg
35+
```
36+
37+
Syntax of the migration command:
38+
39+
```shell
40+
./runMTK.sh -optionsFile example.options schema_name
41+
```
42+
43+
Command line equivalent:
44+
45+
```shell
46+
./runMTK.sh -tables comp_schema.emp,comp_schema.dept,finance_schema.acctg schema_name
47+
```
48+
49+
## Use Options File to exclude tables and include functions
50+
51+
The options file can be used to separate table names from configuration options.
52+
It may also contain comments to clarify why parameters are used.
53+
54+
In this example we are excluding tables and including functions.
55+
It shows some extra comments, to explain why tables are excluded.
56+
57+
Content of the `<excludeInclude.options>` text file:
58+
59+
```
60+
# finances
61+
excludeTables comp_schema.emp,finance_schema.jobhist
62+
63+
# temporary, #MIGRATION-123, ask Ben
64+
excludeTables temp_schema.temp_table
65+
66+
excludeTables more_schema.more_tables
67+
68+
funcs finance_schema.add_two_numbers
69+
```
70+
71+
Syntax of the migration command:
72+
73+
```shell
74+
./runMTK.sh -allTables -optionsFile excludeInclude.options -safeMode -connRetryCount 7 schema_name
75+
```
76+
77+
Command line equivalent:
78+
79+
```shell
80+
./runMTK.sh -allTables -excludeTables comp_schema.emp,finance_schema.jobhist,temp_schema.temp_table,more_schema.more_tables -funcs finance_schema.add_two_numbers -safeMode -connRetryCount 7 schema_name
81+
```
82+
83+
## Offline migration
84+
85+
Run an offline migration with all schemas.
86+
87+
Content of the `<example.options>` text file:
88+
89+
```
90+
offlineMigration file_dest
91+
allTables
92+
schemaOnly
93+
```
94+
95+
Syntax of the migration command:
96+
97+
```shell
98+
./runMTK.sh -optionsFile example.options -allSchemas
99+
```
100+
101+
Command line equivalent:
102+
103+
```shell
104+
./runMTK.sh -offlineMigration file_dest -allTables -schemaOnly -allSchemas
105+
```

‎product_docs/docs/migration_toolkit/55/07_invoking_mtk/mtk_command_options_in_file/index.mdx

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
---
2+
title: "Specifying Migration Toolkit command options using a file"
3+
navTitle: "Specifying options using a file"
4+
deepToC: true
5+
---
6+
7+
EDB supports using a text file to specify several [database migration options](../08_mtk_command_options.mdx) instead of manually entering them in the command line. This is particularly helpful when:
8+
9+
- You have to specify a large number of command line options for complex migration scenarios. Entering all options in the command line becomes troublesome, or you might have even reached command line length limits.
10+
11+
- You have to specify a large number of values for a command line option for complex migration scenarios. Entering all values in the command line becomes troublesome, or you might have even reached command line length limits.
12+
13+
- You want to apply the same migration options and values to several different databases, or you might even consider automating the migration of databases. Running `runMTK.sh` with several options and values repeatedly in the command line becomes prone to errors.
14+
15+
The `-optionsFile <example.options>` argument allows you to reference a text file with all options and values, making the migration process easier.
16+
17+
## Execute a migration using an options file
18+
19+
To perform a migration with a file that specifies the command options:
20+
21+
1. [Create a text file with the command options](creating_txt_file).
22+
23+
1. [Perform a migration by invoking the file with the command options](executing_migration_with_txt).
24+

0 commit comments

Comments
 (0)