Migration Guide

Red Hat JBoss Data Virtualization 6.4

This guide is for installation teams

Red Hat Customer Content Services

Abstract

If you are running an older version of Red Hat JBoss Data Virtualization and you want to upgrade to the latest version, there are some tasks you must perform manually. Firstly, you have to back up your repository to mitigate against the risk of data loss. Secondly, there are some discrepancies between an instance of Red Hat JBoss Data Virtualization that has been patched to the latest version and a completely fresh installation. To resolve these differences, you must perform some manual configuration tasks. This book guides you through these tasks.

Chapter 1. Migrating your data

Use Red Hat JBoss Data Virtualization's backup and restore functionality to migrate the data stored in your hierarchical database. Each backup you create will contain all of the content for all of the workspaces in a single repository. Therefore, you will need to back up and restore each of your repositories one by one.
The backup and restore functionality is provided by the org.modeshape.jcr.api.RepositoryManager interface:
public interface RepositoryManager {

    ...

    Problems backupRepository( File backupDirectory ) throws RepositoryException;

    ...

    Problems restoreRepository( File backupDirectory ) throws RepositoryException;

    ...

}
Run this code in an Apache Jackrabbit (JCR) session in any workspace to access the repository manager:
javax.jcr.Repository repository = ...
javax.jcr.Credentials credentials = ...
String workspaceName = ...
javax.jcr.Session session = repository.login(credentials,workspaceName);
org.modeshape.jcr.api.Session msSession = (org.modeshape.jcr.api.Session)session;
org.modeshape.jcr.api.RepositoryManager repoMgr = ((org.modeshape.jcr.api.Session)session).getWorkspace().getRepositoryManager();

1.1. Back up your repository

Use the backupRepository method provided by the org.modeshape.jcr.api.RepositoryManager interface to back up your repository. All of the workspaces that existed when the back up was initiated will be saved. If you call the backup method on a repository that is in use, all of the changes made while the backup process is underway are also saved.

Note

The method blocks other calls until the backup is completed, so you must invoke the method asynchronously to avoid disruptions.
Each backup is stored on the file system in a series of Gzip archives. A sub-directory for storing large binaries is also created.
  • To back up your repository, run this code in your Apache JCR session:
    org.modeshape.jcr.api.RepositoryManager repoMgr = ...
    java.io.File backupDirectory = ...
    Problems problems = repoMgr.backupRepository(backupDirectory);
    if ( problems.hasProblems() ) {
        System.out.println("Problems restoring the repository:");
        // Report the problems (we'll just print them out) ...
        for ( Problem problem : problems ) {
           System.out.println(problem);
        }
    } else {
        System.out.println("The backup was successful");
    }

Note

You must initiate each operation. There is no way to automatically schedule a backup.

1.2. Restore your repository

Once you have a complete backup, you can restore it after upgrading your system by using the restoreRepository method provided by the org.modeshape.jcr.api.RepositoryManager interface.
  • Run this code in your Apache JCR session:
    org.modeshape.jcr.api.RepositoryManager repoMgr = ...
    java.io.File backupDirectory = ...
    Problems problems = repoMgr.restoreRepository(backupDirectory);
    if ( problems.hasProblems() ) {
        System.out.println("Problems backing up the repository:");
        // Report the problems (we'll just print them out) ...
        for ( Problem problem : problems ) {
             System.out.println(problem);
        }
    } else {
        System.out.println("The restoration was successful");
    }

Warning

Do not delete your old data and backups before verifying that your migration is a success.

Chapter 2. Configuring your system

2.1. Required migration tasks

If you are upgrading Red Hat JBoss Data Virtualization from version 6.3 to 6.4, you must make some configuration changes. This is because the installer does not manually update these files:
  1. Edit the [EAP_HOME]/domain/configuration/domain.xml file to change the Salesforce resource adapter in the ha profile. (You do not need to change the standalone configuration):
    <resource-adapter id="salesforce-34">
      <module slot="main" id="org.jboss.teiid.resource-adapter.salesforce"/>
    </resource-adapter>
    
    Change the 'salesforce' part of the resource adapter id to 'salesforce-34'. The resulting resource adapter will look like this:
    <resource-adapter id="salesforce-34">
      <module slot="main" id="org.jboss.teiid.resource-adapter.salesforce-34"/>
    </resource-adapter>
    
  2. Edit the [EAP_HOME]/standalone/configuration/standalone.xml, [EAP_HOME]/standalone/configuration/standalone-ha.xml and [EAP_HOME]/standalone/configuration/standalone-full-ha.xml files and the ha and full-ha profiles of the [EAP_HOME]/domain/configuration/domain.xml file and add these settings and save:
    <translator name="couchbase" module="org.jboss.teiid.translator.couchbase"/> 
    <translator name="amazon-s3" module="org.jboss.teiid.translator.amazon.s3"/>
    
  3. Edit the [EAP_HOME]/standalone/configuration/standalone.xml, [EAP_HOME]/standalone/configuration/standalone-ha.xml and [EAP_HOME]/standalone/configuration/standalone-full-ha.xml files and the ha and full-ha profiles of the [EAP_HOME]/domain/configuration/domain.xml file, add this resource adapter, and save:
     <resource-adapter id="couchbase">
        <module slot="main" id="org.jboss.teiid.resource-adapter.couchbase"/>
     </resource-adapter>
    
  4. Edit the [EAP_HOME]/standalone/configuration/standalone.xml, [EAP_HOME]/standalone/configuration/standalone-ha.xml and [EAP_HOME]/standalone/configuration/standalone-full-ha.xml files and delete this section:
     <local-cache name="resultset-repl" batching="true">
     	<locking isolation="READ_COMMITTED"/>
     	<transaction mode="NON_XA"/>
     	<eviction strategy="LIRS" max-entries="1024"/>
     	<expiration lifespan="7200000"/>
     </local-cache>
    
    Replace it with this and save:
     <replicated-cache name="resultset-repl" mode="SYNC" batching="true">
     	<locking isolation="READ_COMMITTED"/>
     	<transaction mode="NON_XA"/>
     	<eviction strategy="LIRS" max-entries="1024"/>
     	<expiration lifespan="7200000"/>
     </replicated-cache>
    

2.1.1. Migration steps for the Data Services Builder

If you are upgrading from Red Hat JBoss Data Virtualization 6.3 to 6.4, the Data Services Builder will not work initially. You must deploy it manually (this step is only required if you are going to use the Data Services Builder and should only be performed on a non-production system):
  1. Create a keystore:
    keytool -genkeypair -keystore /path/ks.jks -storepass pass11 -keypass pass11 -alias mykey -dname CN=demo,OU=demo,O=demo,L=demo,ST=demo,C=demo -keyalg RSA -keysize 2048
    
  2. Start the server in admin mode.
  3. Create the HTTPS web connector for the profile you are using on the Red Hat JBoss Enterprise Application Platform:
    /subsystem=web/connector=HTTPS:add(name=HTTPS,protocol=HTTP/1.1,scheme=https,socket-binding=https,secure=true)
  4. Apply the secure socket layer to the certificate:
    /subsystem=web/connector=HTTPS/configuration=ssl:add(name=https,key-alias=mykey,password=pass11,certificate-key-file=/path/ks.jks)
    
  5. Execute the CLI scripts for the profile you intend to use in order to deploy the Data Services Builder:

    Standalone Profile

    • [EAP_HOME]/cli-scripts/teiid-standalone-install-ds-builder-war.cli
    • [EAP_HOME]/cli-scripts/teiid-standalone-install-vdb-builder-war.cli

    Domain Profile:

    • [EAP_HOME]/cli-scripts/teiid-domain-install-ds-builder-war.cli
    • [EAP_HOME]/cli-scripts/teiid-domain-install-vdb-builder-war.cli

    Important

    Do not start the Data Service Builder if the data repository is enabled on your server. They are incompatible.

2.2. Other changes to Red Hat JBoss Data Virtualization

Week Function
Red Hat JBoss Data Virtualization now consistently returns the ISO 8601 standard for WEEK statements. Previously, locale was used for many databases. This change can potentially break functionality for users of databases such as H2, Microsoft SQL Server, and Sybase. Avoid using locale with these databases.
ibm.jdk Dependency is Missing From the org.jboss.security.negotiation Module
The ibm.jdk dependency is not present in the org.jboss.security.negotiation module, nor is it in the patched version in the .overlay directory. You must copy this dependency into the directory every time you patch the Red Hat JBoss Enterprise Application Platform.
UDF Functions Definition Model
The UDF Function Definitions model is no longer supported. To avoid compatibility problems, rebuild any models you created with it.

Appendix A. Revision History

Revision History
Revision 6.4.0-43Fri Nov 10 2017David Le Sage
Updates for 6.4.

Legal Notice

Copyright © 2018 Red Hat, Inc.
This document is licensed by Red Hat under the Creative Commons Attribution-ShareAlike 3.0 Unported License. If you distribute this document, or a modified version of it, you must provide attribution to Red Hat, Inc. and provide a link to the original. If the document is modified, all Red Hat trademarks must be removed.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat Software Collections is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.