Difference between revisions of "Migrate - Migrating a Database"
(Created page with '<div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 3. Migrating a Database </th></tr><tr><td width="20%" …') |
|||
| Line 1: | Line 1: | ||
| − | <div class="navheader"><table | + | <div class="navheader"><table summary="Navigation header" width="100%"><tr><th align="center" colspan="3">Chapter 3. Migrating a Database</th></tr><tr><td align="left" width="20%">[[Migrate - Marking Customizations|Prev]] </td><th align="center" width="60%"> </th><td align="right" width="20%"> [[Migrate - Compiling and Extending|Next]]</td></tr></table><hr></div> |
| − | + | ||
| − | + | ||
<div> | <div> | ||
| − | =<span id=" | + | =<span id="N10424">Migrating a Database</span>= |
</div><div><div class="titlepage"><div><div> | </div><div><div class="titlepage"><div><div> | ||
| − | ==<span id=" | + | ==<span id="N10428">Preperation</span>== |
</div></div></div><div><div class="titlepage"><div><div> | </div></div></div><div><div class="titlepage"><div><div> | ||
| − | ===<span id=" | + | ===<span id="N1042C">Disconnect all Users</span>=== |
</div></div></div><p>The target database should be up and running.</p><p>No users should be logged in. Make sure all users are disconnected from the target and source database.</p><p>That includes the <span class="productname">Adempiere</span> server itself: Shut down the application server.</p></div><div><div class="titlepage"><div><div> | </div></div></div><p>The target database should be up and running.</p><p>No users should be logged in. Make sure all users are disconnected from the target and source database.</p><p>That includes the <span class="productname">Adempiere</span> server itself: Shut down the application server.</p></div><div><div class="titlepage"><div><div> | ||
| − | ===<span id=" | + | ===<span id="N10439">Create a Backup</span>=== |
</div></div></div><p>You <span class="emphasis"><em>must</em></span> have a backup of your live data before starting the migration process.</p><p>Remember the disclaimer at the beginning of this document: This program is distributed without warranty of fitness for a particular purpose. It may migrate your data, or it may completely mess up your database.</p><p>The easiest way to quickly create a backup is with <span class="command"><strong>./RUN_DBExport.sh</strong></span> (or <span class="command"><strong>RUN_DBExport.bat</strong></span>) in the <code class="filename">utils</code> directory.</p><p>That script will create a file <code class="filename">ExpDat.dmp</code> in the <code class="filename">data</code> directory, which can be easily restored using <span class="command"><strong>./RUN_DBRestore.sh</strong></span> (or <span class="command"><strong>RUN_DBRestore.bat</strong></span>), if necessary.</p></div><div><div class="titlepage"><div><div> | </div></div></div><p>You <span class="emphasis"><em>must</em></span> have a backup of your live data before starting the migration process.</p><p>Remember the disclaimer at the beginning of this document: This program is distributed without warranty of fitness for a particular purpose. It may migrate your data, or it may completely mess up your database.</p><p>The easiest way to quickly create a backup is with <span class="command"><strong>./RUN_DBExport.sh</strong></span> (or <span class="command"><strong>RUN_DBExport.bat</strong></span>) in the <code class="filename">utils</code> directory.</p><p>That script will create a file <code class="filename">ExpDat.dmp</code> in the <code class="filename">data</code> directory, which can be easily restored using <span class="command"><strong>./RUN_DBRestore.sh</strong></span> (or <span class="command"><strong>RUN_DBRestore.bat</strong></span>), if necessary.</p></div><div><div class="titlepage"><div><div> | ||
| − | ===<span id=" | + | ===<span id="N1045D">Install new Adempiere version</span>=== |
</div></div></div><p>If you want to do an upgrade migration, download the <span class="productname">Adempiere</span> version you want to upgrade to and install it.</p><p>Then execute <span class="command"><strong>./RUN_setup.sh</strong></span> (or <span class="command"><strong>RUN_setup.bat</strong></span>) in <code class="envar">$ADEMPIERE_HOME</code> to configure <span class="productname">Adempiere</span>. The settings saved are also used by <span class="productname">Migrate</span>.</p></div><div><div class="titlepage"><div><div> | </div></div></div><p>If you want to do an upgrade migration, download the <span class="productname">Adempiere</span> version you want to upgrade to and install it.</p><p>Then execute <span class="command"><strong>./RUN_setup.sh</strong></span> (or <span class="command"><strong>RUN_setup.bat</strong></span>) in <code class="envar">$ADEMPIERE_HOME</code> to configure <span class="productname">Adempiere</span>. The settings saved are also used by <span class="productname">Migrate</span>.</p></div><div><div class="titlepage"><div><div> | ||
| − | ===<span id=" | + | ===<span id="N1047A">Import Reference Database</span>=== |
</div></div></div><p>If you want to do an upgrade migration, install the reference database:</p><p>Execute <span class="command"><strong>./RUN_ImportReference.sh</strong></span> (or <span class="command"><strong>RUN_ImportReference.bat</strong></span>) in the <code class="filename">utils</code> directory.</p><p>If you want to do a transfer migration, make sure the source database is up and running.</p></div><div><div class="titlepage"><div><div> | </div></div></div><p>If you want to do an upgrade migration, install the reference database:</p><p>Execute <span class="command"><strong>./RUN_ImportReference.sh</strong></span> (or <span class="command"><strong>RUN_ImportReference.bat</strong></span>) in the <code class="filename">utils</code> directory.</p><p>If you want to do a transfer migration, make sure the source database is up and running.</p></div><div><div class="titlepage"><div><div> | ||
| − | ===<span id=" | + | ===<span id="N1048D">Verify Preconditions</span>=== |
</div></div></div><p>Make sure that</p><div><ul class="itemizedlist" type="disc" compact><li><p>no users are logged in</p></li><li><p>the <span class="productname">Adempiere</span> application server is shut down</p></li><li><p>you have a backup</p></li><li><p>the reference database is imported (for upgrade migrations)</p></li><li><p>the source or reference database is up and running</p></li><li><p>the target database is up and running</p></li></ul></div></div></div><div><div class="titlepage"><div><div> | </div></div></div><p>Make sure that</p><div><ul class="itemizedlist" type="disc" compact><li><p>no users are logged in</p></li><li><p>the <span class="productname">Adempiere</span> application server is shut down</p></li><li><p>you have a backup</p></li><li><p>the reference database is imported (for upgrade migrations)</p></li><li><p>the source or reference database is up and running</p></li><li><p>the target database is up and running</p></li></ul></div></div></div><div><div class="titlepage"><div><div> | ||
| − | ==<span id=" | + | ==<span id="N104AA">Running the Migration Tool</span>== |
| − | </div></div></div><p>Once all preparations have been done and verified, you can start <span class="productname">Migrate</span> by executing <span class="command"><strong>./RUN_Migrate.sh</strong></span> (or <span class="command"><strong>RUN_Migrate.bat</strong></span>) from the <code class="filename">utils</code> directory.</p><p>This will start the migration tool and display the interactive graphical user interface.<sup>[[#ftn. | + | </div></div></div><p>Once all preparations have been done and verified, you can start <span class="productname">Migrate</span> by executing <span class="command"><strong>./RUN_Migrate.sh</strong></span> (or <span class="command"><strong>RUN_Migrate.bat</strong></span>) from the <code class="filename">utils</code> directory.</p><p>This will start the migration tool and display the interactive graphical user interface.<sup>[[#ftn.N104BE|8]]</sup> |
</p><p>When <span class="productname">Migrate</span> is started, it will read environment variables for setting parameters and options. Since the <span class="command"><strong>RUN_Migrate</strong></span> script loads <span class="productname">Adempiere</span>'s environment before calling <span class="productname">Migrate</span>, it effectively means that <span class="productname">Adempiere</span>'s settings will also be used by <span class="productname">Migrate</span>. Any settings not defined by environment variables will be supplemented with sensible values.</p><p>If <code class="envar">$ADEMPIERE_HOME</code> is defined, <span class="productname">Migrate</span> looks for a configuration file called <code class="filename">migration.config</code> in the <code class="filename">$ADEMPIERE_HOME/utils</code> directory, otherwise it will look for the configuration file in the current directory. If the file exists, configuration settings will be read from that configuration file, and any settings loaded from the environment will be overwritten. Once a migration was run, <span class="productname">Migrate</span> saves its settings to that configuration file, so next time it is started, your last parameters and options will be used again.</p><p>Any command line arguments passed to <span class="productname">Migrate</span> will override the settings loaded from the configuration file or from the environment so that command line arguments always take precedence.</p><div><div class="titlepage"><div><div> | </p><p>When <span class="productname">Migrate</span> is started, it will read environment variables for setting parameters and options. Since the <span class="command"><strong>RUN_Migrate</strong></span> script loads <span class="productname">Adempiere</span>'s environment before calling <span class="productname">Migrate</span>, it effectively means that <span class="productname">Adempiere</span>'s settings will also be used by <span class="productname">Migrate</span>. Any settings not defined by environment variables will be supplemented with sensible values.</p><p>If <code class="envar">$ADEMPIERE_HOME</code> is defined, <span class="productname">Migrate</span> looks for a configuration file called <code class="filename">migration.config</code> in the <code class="filename">$ADEMPIERE_HOME/utils</code> directory, otherwise it will look for the configuration file in the current directory. If the file exists, configuration settings will be read from that configuration file, and any settings loaded from the environment will be overwritten. Once a migration was run, <span class="productname">Migrate</span> saves its settings to that configuration file, so next time it is started, your last parameters and options will be used again.</p><p>Any command line arguments passed to <span class="productname">Migrate</span> will override the settings loaded from the configuration file or from the environment so that command line arguments always take precedence.</p><div><div class="titlepage"><div><div> | ||
| − | ===<span id=" | + | ===<span id="N104F5">The User Interface</span>=== |
| − | </div></div></div | + | </div></div></div><span id="doc_gui">[[File:doc_gui.png|thumb|none|Migrate's interactive Graphical User Interface]]</span><p>Once the user interface is displayed, you need to select the migration mode, select some options to be used by the migration process, and set the database connection parameters.</p><div><div class="titlepage"><div><div> |
| − | + | ====<span id="N1050C">Migration Mode</span>==== | |
| − | + | </div></div></div><span id="doc_guiMode">[[File:doc_guiMode.png|thumb|none|Migration Mode Settings]]</span><p>Select the mode in which to run the migration process.</p><p>Two different modes of migration can be performed:</p><div><dl> | |
| − | ====<span id=" | + | ;<span id="N10522"></span><span id="upgrade"></span>upgrade |
| − | </div></div></div | + | |
| − | + | ||
| − | + | ||
| − | ;<span id=" | + | |
:<p>Upgrade target to newest version as found in source.</p><p>This mode can also be used to convert from other applications to <span class="productname">Adempiere</span>.</p> | :<p>Upgrade target to newest version as found in source.</p><p>This mode can also be used to convert from other applications to <span class="productname">Adempiere</span>.</p> | ||
| − | ;<span id=" | + | ;<span id="N10522"></span><span id="transfer"></span>transfer |
:<p>Copy source to target.</p><p>This mode can also be used to convert from other databases to <span class="productname">postgreSQL</span>.</p></dl></div><p>The default is to run an upgrade migration, but if different vendors are used as source and target database (see Parameters below), only a transfer migration can be performed.</p></div><div><div class="titlepage"><div><div> | :<p>Copy source to target.</p><p>This mode can also be used to convert from other databases to <span class="productname">postgreSQL</span>.</p></dl></div><p>The default is to run an upgrade migration, but if different vendors are used as source and target database (see Parameters below), only a transfer migration can be performed.</p></div><div><div class="titlepage"><div><div> | ||
| − | ====<span id=" | + | ====<span id="N10546">Options</span>==== |
| − | </div></div></div | + | </div></div></div><span id="doc_guiOptions">[[File:doc_guiOptions.png|thumb|none|Options]]</span><p>Several options can be set to control migration behavior. Which options are available depends on the migration mode.</p><div><dl> |
| − | + | ;<span id="N1055A"></span><span id="log level"></span>log level | |
| − | + | ||
| − | ;<span id=" | + | |
:<p><span class="productname">Migrate</span> creates three log files containing results of the migration process:</p><div><ul class="itemizedlist" type="disc"><li><p><code class="filename">migration_<em>timestamp</em>.error.log</code></p><p>contains any errors encountered during migration which must be fixed.</p></li><li><p><code class="filename">migration_<em>timestamp</em>.warning.log</code></p><p>contains hints for the database administrator of what has to be checked or might need to be done manually after migration has finished.</p></li><li><p><code class="filename">migration_<em>timestamp</em>.trace.log</code></p><p>contains the output messages of what steps and actions <span class="productname">Migrate</span> has performed.</p></li></ul></div><p>The log level option sets the threshold for messages to be recorded in the trace log. Messages with a lower priority will not be logged.</p><p>Available log levels in order of descending priority are:</p><div><ul class="itemizedlist" type="disc" compact><li><p><code class="constant">no logging</code></p></li><li><p><code class="constant">errors only</code></p></li><li><p><code class="constant">post-migration tasks</code> (warnings)</p></li><li><p><code class="constant">migration steps</code></p></li><li><p><code class="constant">actions</code></p></li><li><p><code class="constant">details</code></p></li><li><p><code class="constant">SQL update queries</code></p></li><li><p><code class="constant">SQL read queries</code></p></li><li><p><code class="constant">everything</code></p></li></ul></div><p>The default log level is <code class="constant">actions</code>.</p><p>Note that levels of <code class="constant">details</code> or lower can create huge trace files. Be sure to have enough disk space available.</p> | :<p><span class="productname">Migrate</span> creates three log files containing results of the migration process:</p><div><ul class="itemizedlist" type="disc"><li><p><code class="filename">migration_<em>timestamp</em>.error.log</code></p><p>contains any errors encountered during migration which must be fixed.</p></li><li><p><code class="filename">migration_<em>timestamp</em>.warning.log</code></p><p>contains hints for the database administrator of what has to be checked or might need to be done manually after migration has finished.</p></li><li><p><code class="filename">migration_<em>timestamp</em>.trace.log</code></p><p>contains the output messages of what steps and actions <span class="productname">Migrate</span> has performed.</p></li></ul></div><p>The log level option sets the threshold for messages to be recorded in the trace log. Messages with a lower priority will not be logged.</p><p>Available log levels in order of descending priority are:</p><div><ul class="itemizedlist" type="disc" compact><li><p><code class="constant">no logging</code></p></li><li><p><code class="constant">errors only</code></p></li><li><p><code class="constant">post-migration tasks</code> (warnings)</p></li><li><p><code class="constant">migration steps</code></p></li><li><p><code class="constant">actions</code></p></li><li><p><code class="constant">details</code></p></li><li><p><code class="constant">SQL update queries</code></p></li><li><p><code class="constant">SQL read queries</code></p></li><li><p><code class="constant">everything</code></p></li></ul></div><p>The default log level is <code class="constant">actions</code>.</p><p>Note that levels of <code class="constant">details</code> or lower can create huge trace files. Be sure to have enough disk space available.</p> | ||
| − | ;<span id=" | + | ;<span id="N1055A"></span><span id="attempt translations"></span>attempt translations |
:<p>This option is only available in transfer mode.</p><p>When converting from one database to another, views and functions need to be translated.</p><p>If selected, <span class="productname">Migrate</span> will attempt to translate views and functions, otherwise they will be replaced with a compilable stub.</p><p>(Note that currently only translation of views is implemented).</p><p>The default is <code class="constant">yes</code>.</p> | :<p>This option is only available in transfer mode.</p><p>When converting from one database to another, views and functions need to be translated.</p><p>If selected, <span class="productname">Migrate</span> will attempt to translate views and functions, otherwise they will be replaced with a compilable stub.</p><p>(Note that currently only translation of views is implemented).</p><p>The default is <code class="constant">yes</code>.</p> | ||
| − | ;<span id=" | + | ;<span id="N1055A"></span><span id="preserve table IDs"></span>preserve table IDs |
:<p>This option is only available in upgrade mode.</p><p>When running an upgrade, all system information is dropped. Table IDs therefore restart with the highest used sequence number available after migration. It may be beneficial, however, to remember higher ID numbers used before migration to ensure consistency over different versions.</p><p>If selected, table ID numbers are preserved through migration, otherwise <span class="productname">Migrate</span> restarts counting after migration</p><p>The default is <code class="constant">yes.</code> | :<p>This option is only available in upgrade mode.</p><p>When running an upgrade, all system information is dropped. Table IDs therefore restart with the highest used sequence number available after migration. It may be beneficial, however, to remember higher ID numbers used before migration to ensure consistency over different versions.</p><p>If selected, table ID numbers are preserved through migration, otherwise <span class="productname">Migrate</span> restarts counting after migration</p><p>The default is <code class="constant">yes.</code> | ||
</p> | </p> | ||
| − | ;<span id=" | + | ;<span id="N1055A"></span><span id="drop source"></span>drop source |
:<p>This option is only available in upgrade mode.</p><p>When done with upgrading, the source database is no longer required and may be dropped to clear space. However, the database administrator may wish not to drop it for reference purposes.</p><p>If selected, the source is dropped after a successful upgrade, otherwise it is kept remaining in the database after migration.</p><p>(Note that the source will only be dropped if no errors occurred during migration).</p><p>The default is <code class="constant">no.</code> | :<p>This option is only available in upgrade mode.</p><p>When done with upgrading, the source database is no longer required and may be dropped to clear space. However, the database administrator may wish not to drop it for reference purposes.</p><p>If selected, the source is dropped after a successful upgrade, otherwise it is kept remaining in the database after migration.</p><p>(Note that the source will only be dropped if no errors occurred during migration).</p><p>The default is <code class="constant">no.</code> | ||
</p> | </p> | ||
| − | ;<span id=" | + | ;<span id="N1055A"></span><span id="optimize database"></span>optimize database |
:<p>After migration, the database can be automatically optimized. Most databases nowadays have scheduled processes which regularly run optimization tasks, so it may not be necessary to explicitly run them here. Examples for optimization tasks are space allocation or gathering of statistics, but what is actually performed depends on which kind of database is running.</p><p>If selected, the target database is optimized after migration, otherwise it is left to the database's automatic scheduler.</p><p>The default is <code class="constant">no.</code> | :<p>After migration, the database can be automatically optimized. Most databases nowadays have scheduled processes which regularly run optimization tasks, so it may not be necessary to explicitly run them here. Examples for optimization tasks are space allocation or gathering of statistics, but what is actually performed depends on which kind of database is running.</p><p>If selected, the target database is optimized after migration, otherwise it is left to the database's automatic scheduler.</p><p>The default is <code class="constant">no.</code> | ||
</p></dl></div></div><div><div class="titlepage"><div><div> | </p></dl></div></div><div><div class="titlepage"><div><div> | ||
| − | ====<span id=" | + | ====<span id="N10615">Parameters</span>==== |
| − | </div></div></div | + | </div></div></div><span id="doc_guiParameters">[[File:doc_guiParameters.png|thumb|none|Connection Parameters]]</span><p>Parameters are used to define the connections to the source and target databases.</p><p>In upgrade mode, the source is the reference against which the target's structure is updated, and live data in the target remains intact.</p><p>In transfer mode, the source is copied to the target, and all live data in the target is overwritten.</p><p>Two identical sets of parameters must be defined, one for the source connection and one for the target connection.</p><div><dl> |
| − | + | ;<span id="N1062F"></span><span id="version"></span>version | |
| − | + | ||
| − | ;<span id=" | + | |
:<p>This field is read-only and displays the <span class="productname">Adempiere</span> version number found in the database.</p><p>If no version number is displayed, it means that either no connection to the database could be established, or the database contains no <span class="productname">Adempiere</span> version information (which means it is not an <span class="productname">Adempiere</span> database).</p> | :<p>This field is read-only and displays the <span class="productname">Adempiere</span> version number found in the database.</p><p>If no version number is displayed, it means that either no connection to the database could be established, or the database contains no <span class="productname">Adempiere</span> version information (which means it is not an <span class="productname">Adempiere</span> database).</p> | ||
| − | ;<span id=" | + | ;<span id="N1062F"></span><span id="vendor"></span>vendor |
:<p>The vendor (or product) of the database. Supported vendors currently are:</p><div><ul class="itemizedlist" type="disc" compact><li><p><span class="productname">Oracle</span></p></li><li><p><span class="productname">postgreSQL</span></p></li></ul></div><p>The default is <code class="constant">postgresql</code>.</p> | :<p>The vendor (or product) of the database. Supported vendors currently are:</p><div><ul class="itemizedlist" type="disc" compact><li><p><span class="productname">Oracle</span></p></li><li><p><span class="productname">postgreSQL</span></p></li></ul></div><p>The default is <code class="constant">postgresql</code>.</p> | ||
| − | ;<span id=" | + | ;<span id="N1062F"></span><span id="host"></span>host |
:<p>The name or IP-address of the server on which the database is running.</p><p>The default is <code class="constant">localhost</code>.</p> | :<p>The name or IP-address of the server on which the database is running.</p><p>The default is <code class="constant">localhost</code>.</p> | ||
| − | ;<span id=" | + | ;<span id="N1062F"></span><span id="port"></span>port |
:<p>The port on which the database is listening. </p><p>Common port numbers are <code class="constant">5432</code> for <span class="productname">postgreSQL</span> or <code class="constant">1521</code> for <span class="productname">Oracle</span>.</p><p>The default is <code class="constant">5432</code>.</p> | :<p>The port on which the database is listening. </p><p>Common port numbers are <code class="constant">5432</code> for <span class="productname">postgreSQL</span> or <code class="constant">1521</code> for <span class="productname">Oracle</span>.</p><p>The default is <code class="constant">5432</code>.</p> | ||
| − | ;<span id=" | + | ;<span id="N1062F"></span><span id="user"></span>user |
:<p>The normal database user as which to log in.</p><p>The default is <code class="constant">reference</code> for source and <code class="constant">adempiere</code> for target.</p> | :<p>The normal database user as which to log in.</p><p>The default is <code class="constant">reference</code> for source and <code class="constant">adempiere</code> for target.</p> | ||
| − | ;<span id=" | + | ;<span id="N1062F"></span><span id="password"></span>password |
:<p>The normal database user's password.</p><p>The default is <code class="constant">adempiere</code> for both source and target.</p> | :<p>The normal database user's password.</p><p>The default is <code class="constant">adempiere</code> for both source and target.</p> | ||
| − | ;<span id=" | + | ;<span id="N1062F"></span><span id="system user"></span>system user |
:<p>Some databases require a system user for certain operations<sup>[[#ftn.sysUsrPwdNoUse|9]]</sup>. This is the name of the system user as which to log in.</p><p>The default is <code class="constant">postgres</code>.</p> | :<p>Some databases require a system user for certain operations<sup>[[#ftn.sysUsrPwdNoUse|9]]</sup>. This is the name of the system user as which to log in.</p><p>The default is <code class="constant">postgres</code>.</p> | ||
| − | ;<span id=" | + | ;<span id="N1062F"></span><span id="system password"></span>system password |
:<p>The system user's password<sup>[[ch03.wiki#ftn.sysUsrPwdNoUse|9]]</sup>.</p><p>The default is <code class="constant">postgres</code>.</p> | :<p>The system user's password<sup>[[ch03.wiki#ftn.sysUsrPwdNoUse|9]]</sup>.</p><p>The default is <code class="constant">postgres</code>.</p> | ||
| − | ;<span id=" | + | ;<span id="N1062F"></span><span id="database"></span>database |
:<p>The name of the database to use.</p><p>The default is <code class="constant">reference</code> for source and <code class="constant">adempiere</code> for target.</p> | :<p>The name of the database to use.</p><p>The default is <code class="constant">reference</code> for source and <code class="constant">adempiere</code> for target.</p> | ||
| − | ;<span id=" | + | ;<span id="N1062F"></span><span id="driver"></span>driver |
:<p>This field is read-only and displays the URL which will be used by <span class="productname">Migrate</span> to connect to the database. The driver and format used depend on the database vendor.</p> | :<p>This field is read-only and displays the URL which will be used by <span class="productname">Migrate</span> to connect to the database. The driver and format used depend on the database vendor.</p> | ||
| − | ;<span id=" | + | ;<span id="N1062F"></span><span id="catalog"></span>catalog |
:<p>The catalog to use.</p><p>The usage and meaning of catalogs varies according to database vendor. If none is given, <span class="productname">Migrate</span> will try to find a sensible catalog.</p> | :<p>The catalog to use.</p><p>The usage and meaning of catalogs varies according to database vendor. If none is given, <span class="productname">Migrate</span> will try to find a sensible catalog.</p> | ||
| − | ;<span id=" | + | ;<span id="N1062F"></span><span id="schema"></span>schema |
:<p>The schema to use.</p><p>The usage and meaning of schemas varies according to database vendor. If none is given, <span class="productname">Migrate</span> will try to find a sensible schema.</p> | :<p>The schema to use.</p><p>The usage and meaning of schemas varies according to database vendor. If none is given, <span class="productname">Migrate</span> will try to find a sensible schema.</p> | ||
| − | ;<span id=" | + | ;<span id="N1062F"></span><span id="reset"></span>reset |
:<p>Pressing this button resets the parameters to their original settings.</p></dl></div></div><div><div class="titlepage"><div><div> | :<p>Pressing this button resets the parameters to their original settings.</p></dl></div></div><div><div class="titlepage"><div><div> | ||
| − | ====<span id=" | + | ====<span id="N10711">Command Buttons</span>==== |
| − | </div></div></div | + | </div></div></div><span id="doc_guiCommand">[[File:doc_guiCommand.png|thumb|none|Command Buttons]]</span><div><dl> |
| − | + | ;<span id="N10723"></span><span id="Start Migration"></span>Start Migration | |
| − | + | ||
| − | ;<span id=" | + | |
:<p>Start the migration process.</p><p>Pressing this button runs sanity checks and starts the migration process. Once the target database has been modified, the process must not be interrupted.</p></dl></div></div><div><div class="titlepage"><div><div> | :<p>Start the migration process.</p><p>Pressing this button runs sanity checks and starts the migration process. Once the target database has been modified, the process must not be interrupted.</p></dl></div></div><div><div class="titlepage"><div><div> | ||
| − | ====<span id=" | + | ====<span id="N10732">Status</span>==== |
| − | </div></div></div | + | </div></div></div><span id="doc_guiStatus">[[File:doc_guiStatus.png|thumb|none|Status Display]]</span><p>The current status of the running migration process is displayed, indicating what action is being performed in which migration step.</p><div><dl> |
| − | + | ;<span id="N10746"></span><span id="step"></span>step | |
| − | + | ||
| − | ;<span id=" | + | |
:<p>This field displays the current migration step being performed, which can be one of:</p><div><ul class="itemizedlist" type="disc" compact><li><p><code class="computeroutput">CONNECT TO DATABASES</code></p></li><li><p><code class="computeroutput">LOAD METADATA</code></p></li><li><p><code class="computeroutput">SYNCHRONIZE TARGET FROM SOURCE</code></p></li><li><p><code class="computeroutput">CLOSE DATABASE CONNECTIONS</code></p></li><li><p><code class="computeroutput">DONE</code></p></li></ul></div> | :<p>This field displays the current migration step being performed, which can be one of:</p><div><ul class="itemizedlist" type="disc" compact><li><p><code class="computeroutput">CONNECT TO DATABASES</code></p></li><li><p><code class="computeroutput">LOAD METADATA</code></p></li><li><p><code class="computeroutput">SYNCHRONIZE TARGET FROM SOURCE</code></p></li><li><p><code class="computeroutput">CLOSE DATABASE CONNECTIONS</code></p></li><li><p><code class="computeroutput">DONE</code></p></li></ul></div> | ||
| − | ;<span id=" | + | ;<span id="N10746"></span><span id="action"></span>action |
:<p>This field displays which action or operation is currently being performed within above migration step.</p> | :<p>This field displays which action or operation is currently being performed within above migration step.</p> | ||
| − | ;<span id=" | + | ;<span id="N10746"></span><span id="detail"></span>detail |
:<p>This field displays details of the current action being performed, for example which record is presently being updated.</p></dl></div></div><div><div class="titlepage"><div><div> | :<p>This field displays details of the current action being performed, for example which record is presently being updated.</p></dl></div></div><div><div class="titlepage"><div><div> | ||
| − | ====<span id=" | + | ====<span id="N10778">View Buttons</span>==== |
| − | </div></div></div | + | </div></div></div><span id="doc_guiView">[[File:doc_guiView.png|thumb|none|View Buttons]]</span><p>Press one of these buttons to view the different log files.</p><div><dl> |
| − | + | ;<span id="N1078C"></span><span id="view trace"></span>view trace | |
| − | + | ||
| − | ;<span id=" | + | |
:<p>View a snapshot of the last 500 lines of the trace log. The trace log contains all output messages as defined with the log level.</p> | :<p>View a snapshot of the last 500 lines of the trace log. The trace log contains all output messages as defined with the log level.</p> | ||
| − | ;<span id=" | + | ;<span id="N1078C"></span><span id="view warnings"></span>view warnings |
:<p>View a snapshot of the last 500 lines of the warning log. The warning log contains tasks to be performed manually by the database administrator after migration, such as making sure that views and functions were translated correctly.</p> | :<p>View a snapshot of the last 500 lines of the warning log. The warning log contains tasks to be performed manually by the database administrator after migration, such as making sure that views and functions were translated correctly.</p> | ||
| − | ;<span id=" | + | ;<span id="N1078C"></span><span id="view errors"></span>view errors |
:<p>View a snapshot of the last 500 lines of the error log. The error log contains all errors which occurred during migration and need to be fixed.</p></dl></div></div><div><div class="titlepage"><div><div> | :<p>View a snapshot of the last 500 lines of the error log. The error log contains all errors which occurred during migration and need to be fixed.</p></dl></div></div><div><div class="titlepage"><div><div> | ||
| − | ====<span id=" | + | ====<span id="N107B0">Close Buttons</span>==== |
| − | </div></div></div | + | </div></div></div><span id="doc_guiClose">[[File:doc_guiClose.png|thumb|none|Close Buttons]]</span><div><dl> |
| − | + | ;<span id="N107C2"></span><span id="Cancel"></span>Cancel | |
| − | + | ||
| − | ;<span id=" | + | |
:<p>Stop the migration process and close the program without saving any settings.</p> | :<p>Stop the migration process and close the program without saving any settings.</p> | ||
| − | ;<span id=" | + | ;<span id="N107C2"></span><span id="Close"></span>Close |
:<p>Stop the migration process and save settings and parameters before closing the program.</p></dl></div></div></div><div><div class="titlepage"><div><div> | :<p>Stop the migration process and save settings and parameters before closing the program.</p></dl></div></div></div><div><div class="titlepage"><div><div> | ||
| − | ===<span id=" | + | ===<span id="N107DA">Starting from the Command Line</span>=== |
</div></div></div><p>Of course <span class="productname">Migrate</span> does not have to be started with the <span class="command"><strong>RUN_Migrate</strong></span> script but can also be started directly from the command line. This allows <span class="productname">Migrate</span> to be called from other scripts for automating migration, if required.</p><p>The command to start <span class="productname">Migrate</span> from the command line is:</p><div class="cmdsynopsis"><p><code class="command">java</code> [<em>java Options</em>] -cp <em>classpath</em> [<em>migrate Options</em>] com.kkalice.adempiere.migrate.Migrate </p></div><div><dl> | </div></div></div><p>Of course <span class="productname">Migrate</span> does not have to be started with the <span class="command"><strong>RUN_Migrate</strong></span> script but can also be started directly from the command line. This allows <span class="productname">Migrate</span> to be called from other scripts for automating migration, if required.</p><p>The command to start <span class="productname">Migrate</span> from the command line is:</p><div class="cmdsynopsis"><p><code class="command">java</code> [<em>java Options</em>] -cp <em>classpath</em> [<em>migrate Options</em>] com.kkalice.adempiere.migrate.Migrate </p></div><div><dl> | ||
| − | ;<span id=" | + | ;<span id="N107FF"></span><span id="Java Options"></span>Java Options |
:<p>These are the options used by the Java Runtime Engine.</p><p>Sufficiently high memory settings should be used so that <span class="productname">Migrate</span> does not run out of memory.</p><p>Recommended are: <em>-Xms64M -Xmx512M</em> | :<p>These are the options used by the Java Runtime Engine.</p><p>Sufficiently high memory settings should be used so that <span class="productname">Migrate</span> does not run out of memory.</p><p>Recommended are: <em>-Xms64M -Xmx512M</em> | ||
</p><p>If the database contains large objects, higher settings may be necessary.</p> | </p><p>If the database contains large objects, higher settings may be necessary.</p> | ||
| − | ;<span id=" | + | ;<span id="N107FF"></span><span id="Classpath"></span>Classpath |
:<p>The classpath should contain the file <code class="filename">migrate.jar</code> as well as the <span class="productname">JDBC</span> database drivers | :<p>The classpath should contain the file <code class="filename">migrate.jar</code> as well as the <span class="productname">JDBC</span> database drivers | ||
for the databases to be used, for example:</p><div class="informalexample"><p><code class="filename">$ADEMPIERE_HOME/lib/migrate.jar:$ADEMPIERE_HOME/lib/postgresql.jar:$ADEMPIERE_HOME/lib/oracle.jar</code> | for the databases to be used, for example:</p><div class="informalexample"><p><code class="filename">$ADEMPIERE_HOME/lib/migrate.jar:$ADEMPIERE_HOME/lib/postgresql.jar:$ADEMPIERE_HOME/lib/oracle.jar</code> | ||
</p><p>or:</p><p><code class="filename">migrate.jar:/usr/share/java/postgresql-jdbc.jar:/opt/oracle/jdbc/lib/ojdbc14.jar</code> | </p><p>or:</p><p><code class="filename">migrate.jar:/usr/share/java/postgresql-jdbc.jar:/opt/oracle/jdbc/lib/ojdbc14.jar</code> | ||
</p></div><p>Of course only the <span class="productname">JDBC</span> drivers for the database vendors you will actually be connecting to need to be supplied.</p> | </p></div><p>Of course only the <span class="productname">JDBC</span> drivers for the database vendors you will actually be connecting to need to be supplied.</p> | ||
| − | ;<span id=" | + | ;<span id="N107FF"></span><span id="Migrate Options"></span>Migrate Options |
:<p>Options passed to <span class="productname">Migrate</span> must be prefixed with <strong><code>-D</code></strong> so that java knows it must pass the options on to the application as system properties.</p><p>It is highly recommended that all options and parameters are explicitly set on the command line to avoid unpleasant surprises when values you were expecting as default are unexpectedly overridden by environment variables or the configuration file.</p><div><dl> | :<p>Options passed to <span class="productname">Migrate</span> must be prefixed with <strong><code>-D</code></strong> so that java knows it must pass the options on to the application as system properties.</p><p>It is highly recommended that all options and parameters are explicitly set on the command line to avoid unpleasant surprises when values you were expecting as default are unexpectedly overridden by environment variables or the configuration file.</p><div><dl> | ||
| − | ;<span id=" | + | ;<span id="N10842"></span><span id="GUI Mode / Text Mode / Silent Mode"></span>GUI Mode / Text Mode / Silent Mode |
:<p>Two options are only available when starting <span class="productname">Migrate</span> from the command line:</p><div><dl> | :<p>Two options are only available when starting <span class="productname">Migrate</span> from the command line:</p><div><dl> | ||
| − | ;<span id=" | + | ;<span id="N1084C"></span><span id="-DisText"></span>-DisText |
:<p><span class="productname">Migrate</span> will run in Text mode, the GUI will not be started. All parameters and options must be provided by environment variables, the configuration file, or command line arguments.</p> | :<p><span class="productname">Migrate</span> will run in Text mode, the GUI will not be started. All parameters and options must be provided by environment variables, the configuration file, or command line arguments.</p> | ||
| − | ;<span id=" | + | ;<span id="N1084C"></span><span id="-DisSilent"></span>-DisSilent |
:<p>All console output will be suppressed. This implies <em>-DisText</em>.</p></dl></div><p>If none of these arguments are passed, <span class="productname">Migrate</span> will run interactively with a Graphical User Interface.</p> | :<p>All console output will be suppressed. This implies <em>-DisText</em>.</p></dl></div><p>If none of these arguments are passed, <span class="productname">Migrate</span> will run interactively with a Graphical User Interface.</p> | ||
| − | ;<span id=" | + | ;<span id="N10842"></span><span id="Migration Mode"></span>Migration Mode |
:<p>Upgrade mode or transfer mode is selected by the <code class="varname">isUpgrade</code> property:</p><div><dl> | :<p>Upgrade mode or transfer mode is selected by the <code class="varname">isUpgrade</code> property:</p><div><dl> | ||
| − | ;<span id=" | + | ;<span id="N10873"></span><span id="-DisUpgrade=Y"></span>-DisUpgrade=Y |
:<p>run migration in upgrade mode.</p> | :<p>run migration in upgrade mode.</p> | ||
| − | ;<span id=" | + | ;<span id="N10873"></span><span id="-DisUpgrade=N"></span>-DisUpgrade=N |
:<p>run migration in transfer mode.</p></dl></div> | :<p>run migration in transfer mode.</p></dl></div> | ||
| − | ;<span id=" | + | ;<span id="N10842"></span><span id="Options"></span>Options |
:<div><dl> | :<div><dl> | ||
| − | ;<span id=" | + | ;<span id="N1088B"></span><span id="-DmaxLogLevel=<log level>"></span>-DmaxLogLevel=<log level> |
:<p>Use following <span class="productname">Java</span> log levels to correspond to the thresholds which can be selected from the GUI: | :<p>Use following <span class="productname">Java</span> log levels to correspond to the thresholds which can be selected from the GUI: | ||
</p><div class="informaltable"><table border="0"><tr><td align="left"> | </p><div class="informaltable"><table border="0"><tr><td align="left"> | ||
| Line 181: | Line 163: | ||
</td></tr></table></div><p> | </td></tr></table></div><p> | ||
</p> | </p> | ||
| − | ;<span id=" | + | ;<span id="N1088B"></span><span id="-DattemptTranslation=Y, N"></span>-DattemptTranslation=Y, N |
:<p>whether to translate views and functions</p> | :<p>whether to translate views and functions</p> | ||
| − | ;<span id=" | + | ;<span id="N1088B"></span><span id="-DpreserveTableID=Y, N"></span>-DpreserveTableID=Y, N |
:<p>whether to preserve table IDs</p> | :<p>whether to preserve table IDs</p> | ||
| − | ;<span id=" | + | ;<span id="N1088B"></span><span id="-DdropSource=Y, N"></span>-DdropSource=Y, N |
:<p>whether to drop the source database after successful migration</p> | :<p>whether to drop the source database after successful migration</p> | ||
| − | ;<span id=" | + | ;<span id="N1088B"></span><span id="-DoptimizeDatabase=Y, N"></span>-DoptimizeDatabase=Y, N |
:<p>whether to optimize the target database</p></dl></div> | :<p>whether to optimize the target database</p></dl></div> | ||
| − | ;<span id=" | + | ;<span id="N10842"></span><span id="Parameters"></span>Parameters |
| − | :<p>Source connection parameters:</p><table | + | :<p>Source connection parameters:</p><table summary="Simple list" border="0"><tr><td><em>-DsourceDB_vendor=</em><em><database vendor></em> |
</td></tr><tr><td><em>-DsourceDB_host=</em><em><host></em> | </td></tr><tr><td><em>-DsourceDB_host=</em><em><host></em> | ||
</td></tr><tr><td><em>-DsourceDB_port=</em><em><port></em> | </td></tr><tr><td><em>-DsourceDB_port=</em><em><port></em> | ||
| Line 200: | Line 182: | ||
</td></tr><tr><td><em>-DsourceDB_systemUser=</em><em><system user></em> | </td></tr><tr><td><em>-DsourceDB_systemUser=</em><em><system user></em> | ||
</td></tr><tr><td><em>-DsourceDB_systemPasswd=</em><em><system password></em> | </td></tr><tr><td><em>-DsourceDB_systemPasswd=</em><em><system password></em> | ||
| − | </td></tr></table><p>And target connection parameters:</p><table | + | </td></tr></table><p>And target connection parameters:</p><table summary="Simple list" border="0"><tr><td><em>-DtargetDB_vendor=</em><em><database vendor></em> |
</td></tr><tr><td><em>-DtargetDB_host=</em><em><host></em> | </td></tr><tr><td><em>-DtargetDB_host=</em><em><host></em> | ||
</td></tr><tr><td><em>-DtargetDB_port=</em><em><port></em> | </td></tr><tr><td><em>-DtargetDB_port=</em><em><port></em> | ||
| Line 211: | Line 193: | ||
</td></tr><tr><td><em>-DtargetDB_systemPasswd=</em><em><system password></em> | </td></tr><tr><td><em>-DtargetDB_systemPasswd=</em><em><system password></em> | ||
</td></tr></table><p>To pass an empty string, either omit the string after the equal sign or write only the parameter name without any equal sign:</p><div class="informalexample"><p><em>-DsourceDB_catalog=</em></p><p>or just</p><p><em>-DsourceDB_catalog</em></p></div></dl></div></dl></div><p>Example:</p><p>The following command runs a transfer migration from an <span class="productname">Oracle</span> to a <span class="productname">postgreSQL</span> database, assuming that <code class="filename">migrate.jar</code> is in the current directory. Everything should be typed on one line:</p><div class="informalexample"><p><span class="command"><strong>java -Xms64M -Xmx512M -cp migrate.jar:/usr/share/java/postgresql-jdbc.jar:/opt/oracle/jdbc/lib/ojdbc14.jar -DisText -DisUpgrade=N -DmaxLogLevel=CONFIG -DattemptTranslation=Y -DoptimizeDatabase=N -DsourceDB_vendor=oracle -DsourceDB_host=localhost -DsourceDB_port=1521 -DsourceDB_name=erp -DsourceDB_schema=compiere -DsourceDB_user=compiere -DsourceDB_passwd=compiere -DsourceDB_systemUser=system -DsourceDB_systemPasswd=manager -DtargetDB_vendor=postgresql -DtargetDB_host=localhost -DtargetDB_port=5432 -DtargetDB_name=adempiere -DtargetDB_schema=adempiere -DtargetDB_user=adempiere -DtargetDB_passwd=adempiere com.kkalice.adempiere.migrate.Migrate</strong></span></p></div></div></div><div><div class="titlepage"><div><div> | </td></tr></table><p>To pass an empty string, either omit the string after the equal sign or write only the parameter name without any equal sign:</p><div class="informalexample"><p><em>-DsourceDB_catalog=</em></p><p>or just</p><p><em>-DsourceDB_catalog</em></p></div></dl></div></dl></div><p>Example:</p><p>The following command runs a transfer migration from an <span class="productname">Oracle</span> to a <span class="productname">postgreSQL</span> database, assuming that <code class="filename">migrate.jar</code> is in the current directory. Everything should be typed on one line:</p><div class="informalexample"><p><span class="command"><strong>java -Xms64M -Xmx512M -cp migrate.jar:/usr/share/java/postgresql-jdbc.jar:/opt/oracle/jdbc/lib/ojdbc14.jar -DisText -DisUpgrade=N -DmaxLogLevel=CONFIG -DattemptTranslation=Y -DoptimizeDatabase=N -DsourceDB_vendor=oracle -DsourceDB_host=localhost -DsourceDB_port=1521 -DsourceDB_name=erp -DsourceDB_schema=compiere -DsourceDB_user=compiere -DsourceDB_passwd=compiere -DsourceDB_systemUser=system -DsourceDB_systemPasswd=manager -DtargetDB_vendor=postgresql -DtargetDB_host=localhost -DtargetDB_port=5432 -DtargetDB_name=adempiere -DtargetDB_schema=adempiere -DtargetDB_user=adempiere -DtargetDB_passwd=adempiere com.kkalice.adempiere.migrate.Migrate</strong></span></p></div></div></div><div><div class="titlepage"><div><div> | ||
| − | ==<span id=" | + | ==<span id="N109D5">Post-Migration Tasks</span>== |
</div></div></div><p><span class="productname">Migrate</span> already runs sanity checks and clean-up procedures after migration, so it is not necessary to start any post-migration scripts such as <span class="command"><strong>RUN_PostMigration.sh</strong></span> (or <span class="command"><strong>RUN_PostMigration.bat</strong></span>).</p><p>However, the database administrator should check the log files to verify whether any manual intervention is required after migration has completed, particularly the warning log and the error log.</p><p>For a transfer migration, warnings and errors issued for non-customized objects or system records can usually be ignored, as they will be replaced during the subsequent version migration anyway. Only problems with customized objects or live data of real clients need to be addressed by the database administrator.</p><div><div class="titlepage"><div><div> | </div></div></div><p><span class="productname">Migrate</span> already runs sanity checks and clean-up procedures after migration, so it is not necessary to start any post-migration scripts such as <span class="command"><strong>RUN_PostMigration.sh</strong></span> (or <span class="command"><strong>RUN_PostMigration.bat</strong></span>).</p><p>However, the database administrator should check the log files to verify whether any manual intervention is required after migration has completed, particularly the warning log and the error log.</p><p>For a transfer migration, warnings and errors issued for non-customized objects or system records can usually be ignored, as they will be replaced during the subsequent version migration anyway. Only problems with customized objects or live data of real clients need to be addressed by the database administrator.</p><div><div class="titlepage"><div><div> | ||
| − | ===<span id=" | + | ===<span id="N109E7">Warnings</span>=== |
| − | </div></div></div><p>The warning log contains tasks to be performed manually by the database administrator after migration.</p><div class="table"><span id="tblWarnings"></span><p class="title"><b> | + | </div></div></div><p>The warning log contains tasks to be performed manually by the database administrator after migration.</p><div class="table"><span id="tblWarnings"></span><p class="title"><b>Table 3.1. Warning Messages</b></p><div class="table-contents"><table summary="Warning Messages" border="1"><tr><th align="center">Warning</th><th align="center">Mode</th><th align="center">Cause</th><th align="center">Solution</th></tr><tr><td align="left"> |
| − | <code class="computeroutput">Preserving node & | + | <code class="computeroutput">Preserving node … in tree …</code> |
</td><td align="center"> | </td><td align="center"> | ||
upgrade | upgrade | ||
| Line 224: | Line 206: | ||
Review this list to verify whether all customized system nodes are really needed in the new version. | Review this list to verify whether all customized system nodes are really needed in the new version. | ||
</td></tr><tr><td align="left"> | </td></tr><tr><td align="left"> | ||
| − | <code class="computeroutput">Not dropping customized table & | + | <code class="computeroutput">Not dropping customized table …</code> |
</td><td align="center"> | </td><td align="center"> | ||
upgrade | upgrade | ||
| Line 233: | Line 215: | ||
Review this list to verify whether all customized tables are really needed in the new version. | Review this list to verify whether all customized tables are really needed in the new version. | ||
</td></tr><tr><td align="left"> | </td></tr><tr><td align="left"> | ||
| − | <code class="computeroutput">Must re-write customized trigger function & | + | <code class="computeroutput">Must re-write customized trigger function …</code> |
</td><td align="center"> | </td><td align="center"> | ||
transfer | transfer | ||
| Line 244: | Line 226: | ||
Translate the function called by the trigger into the target database's syntax. | Translate the function called by the trigger into the target database's syntax. | ||
</td></tr><tr><td align="left"> | </td></tr><tr><td align="left"> | ||
| − | <code class="computeroutput">Must verify customized object & | + | <code class="computeroutput">Must verify customized object …</code> |
</td><td align="center"> | </td><td align="center"> | ||
transfer | transfer | ||
| Line 253: | Line 235: | ||
Review that the object is translated correctly and works the way it is intended to. | Review that the object is translated correctly and works the way it is intended to. | ||
</td></tr><tr><td align="left"> | </td></tr><tr><td align="left"> | ||
| − | <code class="computeroutput">Must re-write object & | + | <code class="computeroutput">Must re-write object … [<em>error message</em>]</code> |
</td><td align="center"> | </td><td align="center"> | ||
transfer | transfer | ||
| Line 262: | Line 244: | ||
Manually translate the object into the target database's syntax. | Manually translate the object into the target database's syntax. | ||
</td></tr><tr><td align="left"> | </td></tr><tr><td align="left"> | ||
| − | <code class="computeroutput">Modified & | + | <code class="computeroutput">Modified … rows in … to comply with check constraint …</code> |
</td><td align="center"> | </td><td align="center"> | ||
upgrade | upgrade | ||
| Line 271: | Line 253: | ||
Review the table to make sure that the modifications do not disrupt any business logic. | Review the table to make sure that the modifications do not disrupt any business logic. | ||
</td></tr><tr><td align="left"> | </td></tr><tr><td align="left"> | ||
| − | <code class="computeroutput">Could not find correct parent for & | + | <code class="computeroutput">Could not find correct parent for … from … in … to |
| − | & | + | …</code> |
</td><td align="center"> | </td><td align="center"> | ||
upgrade | upgrade | ||
| Line 284: | Line 266: | ||
parent, file a bug report). | parent, file a bug report). | ||
</td></tr></table></div></div><br class="table-break"></div><div><div class="titlepage"><div><div> | </td></tr></table></div></div><br class="table-break"></div><div><div class="titlepage"><div><div> | ||
| − | ===<span id=" | + | ===<span id="N10A79">Errors</span>=== |
| − | </div></div></div><p>The error log contains all errors which occurred during migration and need to be fixed. If an error was raised by the database driver, the original error message is added as a hint.</p><div class="table"><span id="tblErrors"></span><p class="title"><b> | + | </div></div></div><p>The error log contains all errors which occurred during migration and need to be fixed. If an error was raised by the database driver, the original error message is added as a hint.</p><div class="table"><span id="tblErrors"></span><p class="title"><b>Table 3.2. Error Messages</b></p><div class="table-contents"><table summary="Error Messages" border="1"><tr><th align="center">Error</th><th align="center">Cause</th><th align="center">Solution</th></tr><tr><td align="left"> |
| − | <code class="computeroutput">Could not find driver & | + | <code class="computeroutput">Could not find driver … [<em>error message</em>]</code> |
</td><td align="left"> | </td><td align="left"> | ||
The required <span class="productname">JDBC</span> driver could not be found. | The required <span class="productname">JDBC</span> driver could not be found. | ||
| Line 292: | Line 274: | ||
Make sure the <span class="productname">JDBC</span> driver is in the classpath. | Make sure the <span class="productname">JDBC</span> driver is in the classpath. | ||
</td></tr><tr><td align="left"> | </td></tr><tr><td align="left"> | ||
| − | <code class="computeroutput">Could not connect to database & | + | <code class="computeroutput">Could not connect to database … |
| − | [<em> | + | [<em>error message</em>]</code> |
</td><td align="left"> | </td><td align="left"> | ||
A connection to the database could not be established. | A connection to the database could not be established. | ||
</td><td align="left"> | </td><td align="left"> | ||
| − | <table | + | <table summary="Simple list" border="0"><tr><td>Make sure host name, port, database name, user name, and user password are correct.</td></tr><tr><td>Make sure the server is reachable over the network.</td></tr><tr><td>Make sure access configuration allows connections from your IP address.</td></tr></table> |
</td></tr><tr><td align="left"> | </td></tr><tr><td align="left"> | ||
| − | <code class="computeroutput">Could not commit changes in & | + | <code class="computeroutput">Could not commit changes in … |
| − | [<em> | + | [<em>error message</em>]</code> |
</td><td rowspan="3" align="left" valign="middle"> | </td><td rowspan="3" align="left" valign="middle"> | ||
Consult the database vendor's manual about the cause of the error. | Consult the database vendor's manual about the cause of the error. | ||
| Line 306: | Line 288: | ||
Eliminate the cause of the error. | Eliminate the cause of the error. | ||
</td></tr><tr><td align="left"> | </td></tr><tr><td align="left"> | ||
| − | <code class="computeroutput">Could not roll back changes in & | + | <code class="computeroutput">Could not roll back changes in … |
| − | [<em> | + | [<em>error message</em>]</code> |
</td></tr><tr><td align="left"> | </td></tr><tr><td align="left"> | ||
| − | <code class="computeroutput">Could not close & | + | <code class="computeroutput">Could not close … [<em>error message</em>]</code> |
</td></tr><tr><td align="left"> | </td></tr><tr><td align="left"> | ||
| − | <code class="computeroutput">Could not determine product vendor for & | + | <code class="computeroutput">Could not determine product vendor for … |
| − | [<em> | + | [<em>error message</em>]</code> |
</td><td align="left"> | </td><td align="left"> | ||
The database vendor could not be determined or is unsupported. | The database vendor could not be determined or is unsupported. | ||
| Line 318: | Line 300: | ||
Explicitly set the database vendor. | Explicitly set the database vendor. | ||
</td></tr><tr><td align="left"> | </td></tr><tr><td align="left"> | ||
| − | <code class="computeroutput">Could not determine catalog for & | + | <code class="computeroutput">Could not determine catalog for … |
| − | [<em> | + | [<em>error message</em>]</code> |
</td><td align="left"> | </td><td align="left"> | ||
No meaningful catalog could be determined. | No meaningful catalog could be determined. | ||
| Line 325: | Line 307: | ||
Explicitly set the catalog to use. | Explicitly set the catalog to use. | ||
</td></tr><tr><td align="left"> | </td></tr><tr><td align="left"> | ||
| − | <code class="computeroutput">Could not determine schema for & | + | <code class="computeroutput">Could not determine schema for … |
| − | [<em> | + | [<em>error message</em>]</code> |
</td><td align="left"> | </td><td align="left"> | ||
No meaningful schema could be determined. | No meaningful schema could be determined. | ||
| Line 332: | Line 314: | ||
Explicitly set the schema to use. | Explicitly set the schema to use. | ||
</td></tr><tr><td align="left"> | </td></tr><tr><td align="left"> | ||
| − | <code class="computeroutput">Could not drop schema & | + | <code class="computeroutput">Could not drop schema … [<em>error message</em>]</code> |
</td><td align="left"> | </td><td align="left"> | ||
The target schema could not be dropped. | The target schema could not be dropped. | ||
| Line 338: | Line 320: | ||
Make sure the user has sufficient privileges to drop a schema. | Make sure the user has sufficient privileges to drop a schema. | ||
</td></tr><tr><td align="left"> | </td></tr><tr><td align="left"> | ||
| − | <code class="computeroutput">Could not test character set in & | + | <code class="computeroutput">Could not test character set in … |
| − | [<em> | + | [<em>error message</em>]</code> |
</td><td align="left"> | </td><td align="left"> | ||
<span class="productname">Migrate</span> temporarily creates a table with some string fields to check how the | <span class="productname">Migrate</span> temporarily creates a table with some string fields to check how the | ||
| Line 347: | Line 329: | ||
Make sure no table with the name <code class="filename">kkax_migr_chartest</code> previously exists in the database. | Make sure no table with the name <code class="filename">kkax_migr_chartest</code> previously exists in the database. | ||
</td></tr><tr><td align="left"> | </td></tr><tr><td align="left"> | ||
| − | <code class="computeroutput">Target table & | + | <code class="computeroutput">Target table … does not exist</code> |
</td><td rowspan="5" align="left" valign="middle"> | </td><td rowspan="5" align="left" valign="middle"> | ||
Tables which were expected to exist for terminology checking could not be found. | Tables which were expected to exist for terminology checking could not be found. | ||
| Line 354: | Line 336: | ||
Application Dictionary. | Application Dictionary. | ||
</td></tr><tr><td align="left"> | </td></tr><tr><td align="left"> | ||
| − | <code class="computeroutput">Source table & | + | <code class="computeroutput">Source table … does not exist</code> |
</td></tr><tr><td align="left"> | </td></tr><tr><td align="left"> | ||
| − | <code class="computeroutput">Target translation table & | + | <code class="computeroutput">Target translation table … does not exist</code> |
</td></tr><tr><td align="left"> | </td></tr><tr><td align="left"> | ||
| − | <code class="computeroutput">Join table & | + | <code class="computeroutput">Join table … does not exist</code> |
</td></tr><tr><td align="left"> | </td></tr><tr><td align="left"> | ||
| − | <code class="computeroutput">Extra table & | + | <code class="computeroutput">Extra table … does not exist</code> |
</td></tr><tr><td align="left"> | </td></tr><tr><td align="left"> | ||
| − | <code class="computeroutput">Could not set savepoint & | + | <code class="computeroutput">Could not set savepoint … |
| − | [<em> | + | [<em>error message</em>]</code> |
</td><td rowspan="19" align="left" valign="middle"> | </td><td rowspan="19" align="left" valign="middle"> | ||
Consult the database vendor's manual about the cause of the error. | Consult the database vendor's manual about the cause of the error. | ||
| Line 369: | Line 351: | ||
Eliminate the cause of the error. | Eliminate the cause of the error. | ||
</td></tr><tr><td align="left"> | </td></tr><tr><td align="left"> | ||
| − | <code class="computeroutput">Could not get savepoint name [<em> | + | <code class="computeroutput">Could not get savepoint name [<em>error message</em>]</code> |
</td></tr><tr><td align="left"> | </td></tr><tr><td align="left"> | ||
| − | <code class="computeroutput">Could not rollback to savepoint & | + | <code class="computeroutput">Could not rollback to savepoint … |
| − | [<em> | + | [<em>error message</em>]</code> |
</td></tr><tr><td align="left"> | </td></tr><tr><td align="left"> | ||
| − | <code class="computeroutput">Could not release savepoint & | + | <code class="computeroutput">Could not release savepoint … |
| − | [<em> | + | [<em>error message</em>]</code> |
</td></tr><tr><td align="left"> | </td></tr><tr><td align="left"> | ||
| − | <code class="computeroutput">Could not prepare statement & | + | <code class="computeroutput">Could not prepare statement … |
| − | [<em> | + | [<em>error message</em>]</code> |
</td></tr><tr><td align="left"> | </td></tr><tr><td align="left"> | ||
| − | <code class="computeroutput">Could not reset prepared statement & | + | <code class="computeroutput">Could not reset prepared statement … |
| − | [<em> | + | [<em>error message</em>]</code> |
</td></tr><tr><td align="left"> | </td></tr><tr><td align="left"> | ||
| − | <code class="computeroutput">Could not close prepared statement & | + | <code class="computeroutput">Could not close prepared statement … |
| − | [<em> | + | [<em>error message</em>]</code> |
</td></tr><tr><td align="left"> | </td></tr><tr><td align="left"> | ||
| − | <code class="computeroutput">Could not count parameters for prepared statement & | + | <code class="computeroutput">Could not count parameters for prepared statement … |
| − | [<em> | + | [<em>error message</em>]</code> |
</td></tr><tr><td align="left"> | </td></tr><tr><td align="left"> | ||
| − | <code class="computeroutput">Could not set parameter & | + | <code class="computeroutput">Could not set parameter … of prepared statement … |
| − | [<em> | + | [<em>error message</em>]</code> |
</td></tr><tr><td align="left"> | </td></tr><tr><td align="left"> | ||
| − | <code class="computeroutput">Could not create statement [<em> | + | <code class="computeroutput">Could not create statement [<em>error message</em>]</code> |
</td></tr><tr><td align="left"> | </td></tr><tr><td align="left"> | ||
| − | <code class="computeroutput">Could not close statement [<em> | + | <code class="computeroutput">Could not close statement [<em>error message</em>]</code> |
</td></tr><tr><td align="left"> | </td></tr><tr><td align="left"> | ||
| − | <code class="computeroutput">Could not execute prepared statement query & | + | <code class="computeroutput">Could not execute prepared statement query … |
| − | [<em> | + | [<em>error message</em>]</code> |
</td></tr><tr><td align="left"> | </td></tr><tr><td align="left"> | ||
| − | <code class="computeroutput">Could not execute sql query & | + | <code class="computeroutput">Could not execute sql query … |
| − | [<em> | + | [<em>error message</em>]</code> |
</td></tr><tr><td align="left"> | </td></tr><tr><td align="left"> | ||
| − | <code class="computeroutput">Could not close resultset & | + | <code class="computeroutput">Could not close resultset … |
| − | [<em> | + | [<em>error message</em>]</code> |
</td></tr><tr><td align="left"> | </td></tr><tr><td align="left"> | ||
| − | <code class="computeroutput">Could not move cursor in result set & | + | <code class="computeroutput">Could not move cursor in result set … |
| − | [<em> | + | [<em>error message</em>]</code> |
</td></tr><tr><td align="left"> | </td></tr><tr><td align="left"> | ||
| − | <code class="computeroutput">Could not read column & | + | <code class="computeroutput">Could not read column … from result set … |
| − | [<em> | + | [<em>error message</em>]</code> |
</td></tr><tr><td align="left"> | </td></tr><tr><td align="left"> | ||
| − | <code class="computeroutput">Could not check last column value from result set & | + | <code class="computeroutput">Could not check last column value from result set … |
| − | [<em> | + | [<em>error message</em>]</code> |
</td></tr><tr><td align="left"> | </td></tr><tr><td align="left"> | ||
| − | <code class="computeroutput">Could not execute prepared statement command & | + | <code class="computeroutput">Could not execute prepared statement command … |
| − | [<em> | + | [<em>error message</em>]</code> |
</td></tr><tr><td align="left"> | </td></tr><tr><td align="left"> | ||
| − | <code class="computeroutput">Could not execute sql command & | + | <code class="computeroutput">Could not execute sql command … |
| − | [<em> | + | [<em>error message</em>]</code> |
</td></tr><tr><td align="left"> | </td></tr><tr><td align="left"> | ||
| − | <code class="computeroutput">unknown data type & | + | <code class="computeroutput">unknown data type …</code> |
</td><td align="left"> | </td><td align="left"> | ||
No unambiguous data type ID exists for the data type | No unambiguous data type ID exists for the data type | ||
| Line 426: | Line 408: | ||
File a bug report. | File a bug report. | ||
</td></tr><tr><td align="left"> | </td></tr><tr><td align="left"> | ||
| − | <code class="computeroutput">unknown data type or extra logic required for data type ID & | + | <code class="computeroutput">unknown data type or extra logic required for data type ID …</code> |
</td><td align="left"> | </td><td align="left"> | ||
The unambiguous data type ID could not be converted to a vendor-specific data type | The unambiguous data type ID could not be converted to a vendor-specific data type | ||
| Line 432: | Line 414: | ||
File a bug report. | File a bug report. | ||
</td></tr><tr><td align="left"> | </td></tr><tr><td align="left"> | ||
| − | <code class="computeroutput">Instantiation Exception for class & | + | <code class="computeroutput">Instantiation Exception for class … |
| − | [<em> | + | [<em>error message</em>]</code> |
</td><td rowspan="3" align="left" valign="middle"> | </td><td rowspan="3" align="left" valign="middle"> | ||
A <span class="productname">Java</span> interface could not be instantiated. | A <span class="productname">Java</span> interface could not be instantiated. | ||
| Line 439: | Line 421: | ||
File a bug report. | File a bug report. | ||
</td></tr><tr><td align="left"> | </td></tr><tr><td align="left"> | ||
| − | <code class="computeroutput">Illegal Access Exception for class & | + | <code class="computeroutput">Illegal Access Exception for class … |
| − | [<em> | + | [<em>error message</em>]</code> |
</td></tr><tr><td align="left"> | </td></tr><tr><td align="left"> | ||
| − | <code class="computeroutput">Could not find interface & | + | <code class="computeroutput">Could not find interface … |
| − | [<em> | + | [<em>error message</em>]</code> |
</td></tr><tr><td align="left"> | </td></tr><tr><td align="left"> | ||
<code class="computeroutput">A database can not be migrated to itself (source and target must be different)</code> | <code class="computeroutput">A database can not be migrated to itself (source and target must be different)</code> | ||
| Line 457: | Line 439: | ||
Choose the correct reference database or run a transfer migration. | Choose the correct reference database or run a transfer migration. | ||
</td></tr></table></div></div><br class="table-break"></div><div><div class="titlepage"><div><div> | </td></tr></table></div></div><br class="table-break"></div><div><div class="titlepage"><div><div> | ||
| − | ===<span id=" | + | ===<span id="N10C63">Start the Application Server</span>=== |
| − | </div></div></div><p>Now that your database has been successfully migrated, all errors have been fixed, and all warnings have been taken care of, the application server may be started again.</p><p>Users are welcome to log in.</p></div></div><div class="footnotes"><br><hr | + | </div></div></div><p>Now that your database has been successfully migrated, all errors have been fixed, and all warnings have been taken care of, the application server may be started again.</p><p>Users are welcome to log in.</p></div></div><div class="footnotes"><br><hr align="left" width="100"><div><p><sup>[<span id="ftn.N104BE" class="para">8</span>] </sup>To run in text mode and/or suppress console output, the keywords <em>text</em> or <em>silent</em> can be given to the <span class="command"><strong>RUN_Migrate</strong></span> script as command line arguments.</p></div><div><p><sup>[<span id="ftn.sysUsrPwdNoUse" class="para">9</span>] </sup>The <span class="guilabel">system user</span> and <span class="guilabel">system password</span> fields are not used if the selected database does not require log in by a system user for migration.</p></div></div> |
| − | <div class="navfooter"><hr><table | + | <div class="navfooter"><hr><table summary="Navigation footer" width="100%"><tr><td align="left" width="40%">[[Migrate - Marking Customizations|Prev]] </td><td align="center" width="20%"> </td><td align="right" width="40%"> [[Migrate - Compiling and Extending|Next]]</td></tr><tr><td valign="top" align="left" width="40%">Chapter 2. Marking Customizations </td><td align="center" width="20%">[[Migrate|Home]]</td><td valign="top" align="right" width="40%"> Chapter 4. Compiling and Extending</td></tr></table></div> |
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
Latest revision as of 00:42, 23 September 2011
Contents
Migrating a Database
Preperation
Disconnect all Users
The target database should be up and running.
No users should be logged in. Make sure all users are disconnected from the target and source database.
That includes the Adempiere server itself: Shut down the application server.
Create a Backup
You must have a backup of your live data before starting the migration process.
Remember the disclaimer at the beginning of this document: This program is distributed without warranty of fitness for a particular purpose. It may migrate your data, or it may completely mess up your database.
The easiest way to quickly create a backup is with ./RUN_DBExport.sh (or RUN_DBExport.bat) in the utils directory.
That script will create a file ExpDat.dmp in the data directory, which can be easily restored using ./RUN_DBRestore.sh (or RUN_DBRestore.bat), if necessary.
Install new Adempiere version
If you want to do an upgrade migration, download the Adempiere version you want to upgrade to and install it.
Then execute ./RUN_setup.sh (or RUN_setup.bat) in $ADEMPIERE_HOME to configure Adempiere. The settings saved are also used by Migrate.
Import Reference Database
If you want to do an upgrade migration, install the reference database:
Execute ./RUN_ImportReference.sh (or RUN_ImportReference.bat) in the utils directory.
If you want to do a transfer migration, make sure the source database is up and running.
Verify Preconditions
Make sure that
no users are logged in
the Adempiere application server is shut down
you have a backup
the reference database is imported (for upgrade migrations)
the source or reference database is up and running
the target database is up and running
Running the Migration Tool
Once all preparations have been done and verified, you can start Migrate by executing ./RUN_Migrate.sh (or RUN_Migrate.bat) from the utils directory.
This will start the migration tool and display the interactive graphical user interface.8
When Migrate is started, it will read environment variables for setting parameters and options. Since the RUN_Migrate script loads Adempiere's environment before calling Migrate, it effectively means that Adempiere's settings will also be used by Migrate. Any settings not defined by environment variables will be supplemented with sensible values.
If $ADEMPIERE_HOME is defined, Migrate looks for a configuration file called migration.config in the $ADEMPIERE_HOME/utils directory, otherwise it will look for the configuration file in the current directory. If the file exists, configuration settings will be read from that configuration file, and any settings loaded from the environment will be overwritten. Once a migration was run, Migrate saves its settings to that configuration file, so next time it is started, your last parameters and options will be used again.
Any command line arguments passed to Migrate will override the settings loaded from the configuration file or from the environment so that command line arguments always take precedence.
The User Interface
Once the user interface is displayed, you need to select the migration mode, select some options to be used by the migration process, and set the database connection parameters.
Migration Mode
Select the mode in which to run the migration process.
Two different modes of migration can be performed:
- upgrade
Upgrade target to newest version as found in source.
This mode can also be used to convert from other applications to Adempiere.
- transfer
Copy source to target.
This mode can also be used to convert from other databases to postgreSQL.
The default is to run an upgrade migration, but if different vendors are used as source and target database (see Parameters below), only a transfer migration can be performed.
Options
Several options can be set to control migration behavior. Which options are available depends on the migration mode.
- log level
Migrate creates three log files containing results of the migration process:
migration_timestamp.error.logcontains any errors encountered during migration which must be fixed.
migration_timestamp.warning.logcontains hints for the database administrator of what has to be checked or might need to be done manually after migration has finished.
migration_timestamp.trace.logcontains the output messages of what steps and actions Migrate has performed.
The log level option sets the threshold for messages to be recorded in the trace log. Messages with a lower priority will not be logged.
Available log levels in order of descending priority are:
no loggingerrors onlypost-migration tasks(warnings)migration stepsactionsdetailsSQL update queriesSQL read querieseverything
The default log level is
actions.Note that levels of
detailsor lower can create huge trace files. Be sure to have enough disk space available.- attempt translations
This option is only available in transfer mode.
When converting from one database to another, views and functions need to be translated.
If selected, Migrate will attempt to translate views and functions, otherwise they will be replaced with a compilable stub.
(Note that currently only translation of views is implemented).
The default is
yes.- preserve table IDs
This option is only available in upgrade mode.
When running an upgrade, all system information is dropped. Table IDs therefore restart with the highest used sequence number available after migration. It may be beneficial, however, to remember higher ID numbers used before migration to ensure consistency over different versions.
If selected, table ID numbers are preserved through migration, otherwise Migrate restarts counting after migration
The default is
yes.- drop source
This option is only available in upgrade mode.
When done with upgrading, the source database is no longer required and may be dropped to clear space. However, the database administrator may wish not to drop it for reference purposes.
If selected, the source is dropped after a successful upgrade, otherwise it is kept remaining in the database after migration.
(Note that the source will only be dropped if no errors occurred during migration).
The default is
no.- optimize database
After migration, the database can be automatically optimized. Most databases nowadays have scheduled processes which regularly run optimization tasks, so it may not be necessary to explicitly run them here. Examples for optimization tasks are space allocation or gathering of statistics, but what is actually performed depends on which kind of database is running.
If selected, the target database is optimized after migration, otherwise it is left to the database's automatic scheduler.
The default is
no.
Parameters
Parameters are used to define the connections to the source and target databases.
In upgrade mode, the source is the reference against which the target's structure is updated, and live data in the target remains intact.
In transfer mode, the source is copied to the target, and all live data in the target is overwritten.
Two identical sets of parameters must be defined, one for the source connection and one for the target connection.
- version
This field is read-only and displays the Adempiere version number found in the database.
If no version number is displayed, it means that either no connection to the database could be established, or the database contains no Adempiere version information (which means it is not an Adempiere database).
- vendor
The vendor (or product) of the database. Supported vendors currently are:
Oracle
postgreSQL
The default is
postgresql.- host
The name or IP-address of the server on which the database is running.
The default is
localhost.- port
The port on which the database is listening.
Common port numbers are
5432for postgreSQL or1521for Oracle.The default is
5432.- user
The normal database user as which to log in.
The default is
referencefor source andadempierefor target.- password
The normal database user's password.
The default is
adempierefor both source and target.- system user
Some databases require a system user for certain operations9. This is the name of the system user as which to log in.
The default is
postgres.- system password
The system user's password9.
The default is
postgres.- database
The name of the database to use.
The default is
referencefor source andadempierefor target.- driver
This field is read-only and displays the URL which will be used by Migrate to connect to the database. The driver and format used depend on the database vendor.
- catalog
The catalog to use.
The usage and meaning of catalogs varies according to database vendor. If none is given, Migrate will try to find a sensible catalog.
- schema
The schema to use.
The usage and meaning of schemas varies according to database vendor. If none is given, Migrate will try to find a sensible schema.
- reset
Pressing this button resets the parameters to their original settings.
Command Buttons
- Start Migration
Start the migration process.
Pressing this button runs sanity checks and starts the migration process. Once the target database has been modified, the process must not be interrupted.
Status
The current status of the running migration process is displayed, indicating what action is being performed in which migration step.
- step
This field displays the current migration step being performed, which can be one of:
CONNECT TO DATABASESLOAD METADATASYNCHRONIZE TARGET FROM SOURCECLOSE DATABASE CONNECTIONSDONE
- action
This field displays which action or operation is currently being performed within above migration step.
- detail
This field displays details of the current action being performed, for example which record is presently being updated.
View Buttons
Press one of these buttons to view the different log files.
- view trace
View a snapshot of the last 500 lines of the trace log. The trace log contains all output messages as defined with the log level.
- view warnings
View a snapshot of the last 500 lines of the warning log. The warning log contains tasks to be performed manually by the database administrator after migration, such as making sure that views and functions were translated correctly.
- view errors
View a snapshot of the last 500 lines of the error log. The error log contains all errors which occurred during migration and need to be fixed.
Starting from the Command Line
Of course Migrate does not have to be started with the RUN_Migrate script but can also be started directly from the command line. This allows Migrate to be called from other scripts for automating migration, if required.
The command to start Migrate from the command line is:
java [java Options] -cp classpath [migrate Options] com.kkalice.adempiere.migrate.Migrate
- Java Options
These are the options used by the Java Runtime Engine.
Sufficiently high memory settings should be used so that Migrate does not run out of memory.
Recommended are: -Xms64M -Xmx512M
- Classpath
The classpath should contain the file
migrate.jaras well as the JDBC database drivers- Migrate Options
Options passed to Migrate must be prefixed with
-Dso that java knows it must pass the options on to the application as system properties.It is highly recommended that all options and parameters are explicitly set on the command line to avoid unpleasant surprises when values you were expecting as default are unexpectedly overridden by environment variables or the configuration file.
- GUI Mode / Text Mode / Silent Mode
Two options are only available when starting Migrate from the command line:
- -DisText
Migrate will run in Text mode, the GUI will not be started. All parameters and options must be provided by environment variables, the configuration file, or command line arguments.
- -DisSilent
All console output will be suppressed. This implies -DisText.
If none of these arguments are passed, Migrate will run interactively with a Graphical User Interface.
- Migration Mode
Upgrade mode or transfer mode is selected by the
isUpgradeproperty:- -DisUpgrade=Y
run migration in upgrade mode.
- -DisUpgrade=N
run migration in transfer mode.
- Options
- <span id="-DmaxLogLevel=<log level>"></span>-DmaxLogLevel=<log level>
Use following Java log levels to correspond to the thresholds which can be selected from the GUI:
OFF=
no loggingSEVERE=
errors onlyWARNING=
post-migration tasksINFO=
migration stepsCONFIG=
actionsFINE=
detailsFINER=
SQL update queriesFINEST=
SQL read queriesALL=
everything- -DattemptTranslation=Y, N
whether to translate views and functions
- -DpreserveTableID=Y, N
whether to preserve table IDs
- -DdropSource=Y, N
whether to drop the source database after successful migration
- -DoptimizeDatabase=Y, N
whether to optimize the target database
- Parameters
Source connection parameters:
-DsourceDB_vendor=<database vendor> -DsourceDB_host=<host> -DsourceDB_port=<port> -DsourceDB_name=<database name> -DsourceDB_catalog=<catalog> -DsourceDB_schema=<schema> -DsourceDB_user=<normal user> -DsourceDB_passwd=<normal password> -DsourceDB_systemUser=<system user> -DsourceDB_systemPasswd=<system password> And target connection parameters:
-DtargetDB_vendor=<database vendor> -DtargetDB_host=<host> -DtargetDB_port=<port> -DtargetDB_name=<database name> -DtargetDB_catalog=<catalog> -DtargetDB_schema=<schema> -DtargetDB_user=<normal user> -DtargetDB_passwd=<normal password> -DtargetDB_systemUser=<system user> -DtargetDB_systemPasswd=<system password> To pass an empty string, either omit the string after the equal sign or write only the parameter name without any equal sign:
-DsourceDB_catalog=
or just
-DsourceDB_catalog
If the database contains large objects, higher settings may be necessary.
$ADEMPIERE_HOME/lib/migrate.jar:$ADEMPIERE_HOME/lib/postgresql.jar:$ADEMPIERE_HOME/lib/oracle.jar
or:
migrate.jar:/usr/share/java/postgresql-jdbc.jar:/opt/oracle/jdbc/lib/ojdbc14.jar
Of course only the JDBC drivers for the database vendors you will actually be connecting to need to be supplied.
Example:
The following command runs a transfer migration from an Oracle to a postgreSQL database, assuming that migrate.jar is in the current directory. Everything should be typed on one line:
java -Xms64M -Xmx512M -cp migrate.jar:/usr/share/java/postgresql-jdbc.jar:/opt/oracle/jdbc/lib/ojdbc14.jar -DisText -DisUpgrade=N -DmaxLogLevel=CONFIG -DattemptTranslation=Y -DoptimizeDatabase=N -DsourceDB_vendor=oracle -DsourceDB_host=localhost -DsourceDB_port=1521 -DsourceDB_name=erp -DsourceDB_schema=compiere -DsourceDB_user=compiere -DsourceDB_passwd=compiere -DsourceDB_systemUser=system -DsourceDB_systemPasswd=manager -DtargetDB_vendor=postgresql -DtargetDB_host=localhost -DtargetDB_port=5432 -DtargetDB_name=adempiere -DtargetDB_schema=adempiere -DtargetDB_user=adempiere -DtargetDB_passwd=adempiere com.kkalice.adempiere.migrate.Migrate
Post-Migration Tasks
Migrate already runs sanity checks and clean-up procedures after migration, so it is not necessary to start any post-migration scripts such as RUN_PostMigration.sh (or RUN_PostMigration.bat).
However, the database administrator should check the log files to verify whether any manual intervention is required after migration has completed, particularly the warning log and the error log.
For a transfer migration, warnings and errors issued for non-customized objects or system records can usually be ignored, as they will be replaced during the subsequent version migration anyway. Only problems with customized objects or live data of real clients need to be addressed by the database administrator.
Warnings
The warning log contains tasks to be performed manually by the database administrator after migration.
Table 3.1. Warning Messages
| Warning | Mode | Cause | Solution |
|---|---|---|---|
|
|
upgrade |
System nodes would normally be purged from trees, but are preserved if they are recognized as a customization (for example, custom entries in the system-wide menu). |
Review this list to verify whether all customized system nodes are really needed in the new version. |
|
|
upgrade |
A table not existing in the reference database would normally be dropped, but it is kept alive if recognized as a customized table. |
Review this list to verify whether all customized tables are really needed in the new version. |
|
|
transfer |
If data is migrated from a database in which triggers can contain inline code to a database in which triggers themselves can not contain code but only point to functions, the inline code has to be converted to a callable function. At the time of conversion, the number of arguments to the function is unknown, and since also translation of functions is not implemented yet, the trigger is basically rendered useless. |
Translate the function called by the trigger into the target database's syntax. |
|
|
transfer |
Migrate attempts to translate objects, but the result is not guaranteed to be correct. |
Review that the object is translated correctly and works the way it is intended to. |
|
|
transfer |
Sometimes translation of an object fails. Migrate then just replaces the object's code with a compilable stub and indicates the last error as hint why translation failed. |
Manually translate the object into the target database's syntax. |
|
|
upgrade |
A table contained values which would violate the check constraint rule. Those values have been modified to comply with the constraint. |
Review the table to make sure that the modifications do not disrupt any business logic. |
|
|
upgrade |
If a new column is added to a table and that column is part of a foreign key, Migrate attempts to find the correct parents for records already existing in the child table. This warning is issued if the correct parents could not be found. |
If no error is reported when the foreign key is created, this warning can be ignored. Otherwise the child records must be linked to the correct parents manually. (If you know what hint can be used to deduce the correct parent, file a bug report). |
Errors
The error log contains all errors which occurred during migration and need to be fixed. If an error was raised by the database driver, the original error message is added as a hint.
Table 3.2. Error Messages
| Error | Cause | Solution | |||
|---|---|---|---|---|---|
|
|
The required JDBC driver could not be found. |
Make sure the JDBC driver is in the classpath. | |||
|
|
A connection to the database could not be established. |
| |||
|
|
Consult the database vendor's manual about the cause of the error. |
Eliminate the cause of the error. | |||
|
| |||||
|
| |||||
|
|
The database vendor could not be determined or is unsupported. |
Explicitly set the database vendor. | |||
|
|
No meaningful catalog could be determined. |
Explicitly set the catalog to use. | |||
|
|
No meaningful schema could be determined. |
Explicitly set the schema to use. | |||
|
|
The target schema could not be dropped. |
Make sure the user has sufficient privileges to drop a schema. | |||
|
|
Migrate temporarily creates a table with some string fields to check how the JDBC driver reports character sizes. An error occurred while trying to create this table. |
Make sure no table with the name | |||
|
|
Tables which were expected to exist for terminology checking could not be found. |
Terminology checking will only be successful on databases with an Adempiere-style Application Dictionary. | |||
|
| |||||
|
| |||||
|
| |||||
|
| |||||
|
|
Consult the database vendor's manual about the cause of the error. |
Eliminate the cause of the error. | |||
|
| |||||
|
| |||||
|
| |||||
|
| |||||
|
| |||||
|
| |||||
|
| |||||
|
| |||||
|
| |||||
|
| |||||
|
| |||||
|
| |||||
|
| |||||
|
| |||||
|
| |||||
|
| |||||
|
| |||||
|
| |||||
|
|
No unambiguous data type ID exists for the data type |
File a bug report. | |||
|
|
The unambiguous data type ID could not be converted to a vendor-specific data type |
File a bug report. | |||
|
|
A Java interface could not be instantiated. |
File a bug report. | |||
|
| |||||
|
| |||||
|
|
Source and target connection parameters must point to different databases. |
Make sure source and target connection parameters are correct. | |||
|
|
Upgrades can only be run if source and target are the same database vendor. |
Choose the correct reference database or run a transfer migration. |
Start the Application Server
Now that your database has been successfully migrated, all errors have been fixed, and all warnings have been taken care of, the application server may be started again.
Users are welcome to log in.
[8] To run in text mode and/or suppress console output, the keywords text or silent can be given to the RUN_Migrate script as command line arguments.
[9] The system user and system password fields are not used if the selected database does not require log in by a system user for migration.
