2 Database Upgrades

Database compatibility

In prior releases of TimesTen, release numbers used either five parts (7.0.0.0.0 and later), or three parts (releases before 7.0.0.0.0, such as 6.0.17) to represent the release. Starting with TimesTen release 11.2.1.0.0, five parts are used, with the first three parts, such as 11.2.1, indicating a major release of TimesTen. The fourth part indicates the patch release of a major release, and the fifth part indicates a port patch. For example, TimesTen release number 11.2.1.2.1 indicates the first port patch of the second patch release of TimesTen Release 11.2.1.

TimesTen databases are not compatible between major releases, but they are always compatible between patch releases. For example, a database created with TimesTen release 7.0.5.1.0 is not compatible with a TimesTen release 11.2.1.1.0 application, but a database created with TimesTen 11.2.1.0.0 is compatible with a TimesTen release 11.2.1.1.0 application.

Data type compatibility

TimesTen supports a selection of Oracle data types in addition to the original TimesTen data types that are maintained for backward compatibility. For details on all data types, see "Type specifications" in the Oracle TimesTen In-Memory Database SQL Reference. Because some Oracle data types have the same names as the backward-compatible TimesTen data types, a set of aliases exists for addressing the data types. Which data types the aliases refer to depends on the TypeMode setting for the database. See "TypeMode" in the Oracle TimesTen In-Memory Database Reference for more information.

TimesTen backward-compatible data types are replication-compatible with the data types in releases of TimesTen before 7.0. However, TimesTen backward-compatible data types are not compatible with TimesTen IMDB Cache to Oracle— use only Oracle data types with IMDB Cache to Oracle. If you want to use IMDB Cache to Oracle, you must convert any original TimesTen data types to the new Oracle data types when performing a database upgrade with ttMigrate. See "Converting data types to Oracle data types" for details.

Oracle data types are not replication-compatible with releases of TimesTen before 7.0. To perform an upgrade that requires replication with a release of TimesTen from before 7.0, you must upgrade the original data types as TimesTen data types. See "Upgrading data types as TimesTen data types" for more information.

Database character set

TimesTen requires a database to be configured to support a specific character set when it is created. The character set for the database is specified using the database attribute DatabaseCharacterSet. The value of this attribute is used to determine which characters may be input to and output from character fields, and how character data is stored and sorted. See "Choosing a database character set" in the Oracle TimesTen In-Memory Database Operations Guide for more information.

Before upgrading your database from a release before TimesTen 7.0, you must specify a database character set by adding the DatabaseCharacterSet attribute to your database's DSN. This attribute is ignored by releases of TimesTen before 7.0. In most cases, you want to choose a database character set that makes sense for your region and that matches the character data that is present in your database. However, there are three important restrictions you must consider:

• If you plan to use the database with TimesTen IMDB Cache to Oracle, you must specify a value for DatabaseCharacterSet that is the same as the character set specified for the Oracle database that the TimesTen database connects to.

• Replication is not possible between databases with different character sets. Because databases created with releases of TimesTen before 7.0 do not have a database character set specified, a special database character set, TIMESTEN8, has been created, which allows replication compatibility between databases created by the current release of TimesTen and those created by earlier releases. If you plan to perform the database upgrade as an online upgrade with replication (see "Performing an online upgrade with replication"), then you must specify a DatabaseCharacterSet setting of TIMESTEN8 in your DSN.

• If you use TimesTen Client/Server and intend to connect to the upgraded database with an application linked to a Client ODBC library from a release before TimesTen 7.0, you must specify a DatabaseCharacterSet of TIMESTEN8 in your DSN to ensure compatibility. See "Performing a Client/Server online upgrade from TimesTen release 6.0 and above".

Converting data types to Oracle data types

To convert the data types from a release before TimesTen 7.0 to Oracle data types, you must use the -convertTypesToOra option for ttMigrate when you restore your database as part of your upgrade procedure. For example, if you restore the database salesdata as part of an upgrade procedure, you may use the following to upgrade the data types to Oracle data types:

ttMigrate -r -convertTypesToOra salesdata salesdata.mig

See "TimesTen to Oracle data type conversions" in the Oracle TimesTen In-Memory Database Reference for more information.

Upgrading data types as TimesTen data types

If you choose to upgrade the data types in a database from a release before TimesTen 7.0 as TimesTen data types, you do not need to use any special options when restoring the database with ttMigrate. The data types from a release before TimesTen 7.0 are automatically restored as TimesTen data types.

Converting from the TIMESTEN8 character set

You may use ttMigrate to convert a database from TIMESTEN8 to any other character set by completing the following steps:

1. Save the database to a file using ttMigrate. For example, to save the database salesdata to the file salesdata.mig, use the command:

   ttMigrate -c DSN=salesdata salesdata.mig
   

2. Destroy the database:

   ttDestroy salesdata
   

3. Change the value of the DSN attribute DatabaseCharacterSet for your database to the value specifying the new character set. For example, if you want your database to use the WE8ISO8859P1 character set instead of TIMESTEN8, use the following line in your ODBCINI file:

   DatabaseCharacterSet=WE8ISO8859P1
   

4. Load the database from the file using ttMigrate with the -noCharsetConversion command-line option. This option ensures that no character values are changed when the data is loaded into the DSN using the new character set. For example:

   ttMigrate -r -noCharsetConversion
   DSN=salesdata salesdata.mig
   

   Note:

   If you find that you have accidentally converted your database from TIMESTEN8 to the wrong character set, you can use the same procedure to convert your database to the correct character set without any accidental modification of the character data.

Converting from a character set other than TIMESTEN8

You may use ttMigrate to convert a database from any character set to any other character set by completing the following steps:

1. Save the database to a file using ttMigrate. For example, to save the database salesdata to the file salesdata.mig, use the command:

   ttMigrate -c DSN=salesdata salesdata.mig
   

2. Destroy the database:

   ttDestroy salesdata
   

3. Change the value of the DSN attribute DatabaseCharacterSet for your database to the value specifying the new character set. For example, if you want your database to use the WE8ISO8859P1 character set, use the following line in your ODBCINI file:

   DatabaseCharacterSet=WE8ISO8859P1
   

4. Load the database from the file using ttMigrate. TimesTen automatically converts the character data from the character set the file was saved with to the character set used by the DSN. For example:

   ttMigrate -r DSN=salesdata salesdata.mig
   

   Note:

   It is possible that character data is lost in the conversion process if no mapping exists from one character set to the other for a given character.

In-place upgrades

In-place upgrades are available for moving to a new patch release of TimesTen, such as moving from the first patch release of 11.2.1, release 11.2.1.1.0, to the second patch release of 11.2.1, release 11.2.1.2.0. You can uninstall an old release of TimesTen, install a new patch release of TimesTen and connect to existing databases with the new release. No separate action is required for existing databases.

In-place upgrades require all applications to disconnect from the database during the upgrade procedure. This kind of upgrade allows you to preserve the existing database without using TimesTen's backup and migration utilities.

Offline upgrades

During the time required to perform an offline upgrade, the database is not available to applications. Offline upgrades usually require enough disk space for an extra copy of the upgraded database.

Offline upgrades are used for the following:

• Move to a new major or patch release of TimesTen.

• Move to a different directory or computer.

• Reduce database size.

• Move between 32-bit and 64-bit databases.

You should perform offline upgrades during a time when applications do not need continuous access to the database. For example, if there is a maintenance window during weekends, schedule the upgrade during that time.

Offline upgrades require all applications to disconnect from the database during the upgrade procedure. The database must also be unloaded from shared memory. Offline upgrades require you to use TimesTen's ttMigrate or ttBackup utilities. (See "ttMigrate" and "ttBackup" in Oracle TimesTen In-Memory Database Reference.)

Online upgrades with replication

When upgrading to a new major release of TimesTen, you may have a mission-critical database that needs to remain continuously available to your applications. You can use TimesTen replication to keep two copies of a database synchronized, even when the databases are from different releases of TimesTen, allowing your applications to stay connected to one copy of the database while the other one is being upgraded. When the upgrade is finished, any updates that have been made on the active database are transmitted immediately to the upgraded database, and your applications can then be switched to the upgraded database with no data loss and no down time. For more information, see "Performing an online upgrade with replication".

The online upgrade process only supports updates to user tables during the upgrade. Data definition changes such as CREATE TABLE or CREATE INDEX are not replicated. In addition, all tables to be replicated must have a PRIMARY KEY or a unique index on non-nullable columns. Because two copies of the database to be upgraded are required, you must have available twice the memory and disk space that the database usually requires, if performing the upgrade on a single system.

Online upgrades with Client/Server

If you are upgrading a TimesTen Client/Server installation to a new major release, you can minimize downtime by performing a Client/Server online upgrade. During this process, TimesTen clients from the previous release are able to continue to communicate with a database that has been upgraded to the new release. See "Performing a Client/Server online upgrade from TimesTen release 6.0 and above".

The Client/Server online upgrade process minimizes, but does not eliminate, the interruption of client application access to the database being upgraded. To maintain nearly continuous availability of a database to all clients, you may use the approach outlined in "Online upgrades with replication". This procedure keeps an identical copy of the database available to the old release of TimesTen Server, while you upgrade the original to the new release. Once the upgraded original database is available to the new release of TimesTen Server, you may stop the old release and start the new release, listening on the same port. The only interruption in availability using this method is the very brief period after the old server is stopped and before the new server is started.

Unloading a database

TimesTen databases remain loaded in shared memory as long as any applications or TimesTen agents (such as the cache or replication agents) are connected to them. Databases may also be kept in shared memory, even when no applications or agents are connected, if the RAM policy of the database has been modified using the ttAdmin utility. (See "ttAdmin" in Oracle TimesTen In-Memory Database Reference.) Perform the following to unload a database:

1. Disconnect all applications from the database.

2. In this example, the database original is from the older release. The database upgrade is in the new release. If replication has been started, pause replication on the databases, and then stop replication on the database that you are unloading from memory, using the commands:

   ttRepAdmin -receiver -name upgrade -state pause original
   ttRepAdmin -receiver -name original -state pause upgrade
   ttAdmin -repStop upgrade
   

3. If the cache agent has been started for the database, stop the cache agent with the command:

   ttAdmin -cacheStop upgrade
   

4. Verify that the RAM policy allows the database to be unloaded. If the RAM policy is set to manual, unload the database using the command:

   ttAdmin -ramUnload upgrade
   

   If the RAM policy is set to always or inUse, change it to manual. If the RAM policy is inUse and a grace period is set, set the grace period to 0 or wait for the grace period to elapse.

5. Use the ttStatus utility to verify that the database has been unloaded from memory. (See "ttStatus" in Oracle TimesTen In-Memory Database Reference.)

Moving to a new patch release of TimesTen

All applications concurrently connected to a database must be directly linked to a TimesTen ODBC driver of the same major release. TimesTen databases from different patch releases are structurally equivalent or identical. For example, when upgrading from release 11.2.1.1.0 to 11.2.1.3.0, you do not need to migrate your existing databases using the ttMigrate utility. However, during the installation of a new major or patch release, you should disconnect your application and stop the TimesTen daemon. If you have not explicitly performed these steps, the TimesTen daemon process from the prior release is stopped, effectively disconnecting all applications from the database. While preparing for the upgrade, make sure that all databases are unloaded from memory before upgrading TimesTen.

For a description of the procedures for unloading a database from memory, see "Unloading a database".

Moving to a different directory

The TimesTen daemon identifies a database by the full path name of the database's checkpoint files. To move a TimesTen database to a different directory, back up the database using the ttBackup utility, create a new DSN definition that specifies the new database path name, then restore the database into its new location using the ttRestore utility. When you have verified that the database functions properly in the new location, free up the disk space by using ttDestroy to remove the old database.

For example, to move a database from /old/SalesData/sales with a database name SalesData ("DSN=SalesData") to /new/SalesData/sales with database name NewSalesData ("DSN=NewSalesData"), using the /tmp/dump directory for temporary storage, use the following commands:

1. mkdir /tmp/dump

2. ttBackup -dir /tmp/dump -fname salesdata "DSN=SalesData"

3. Create a DSN definition for the NewSalesData database and specify the new database path: /new/SalesData/sales/NewSalesData

4. ttRestore -dir /tmp/dump -fname salesdata "DSN=NewSalesData"

   (Verify that NewSalesData is operational.)

5. rm -r /tmp/dump

6. ttDestroy /old/SalesData/sales/SalesData

7. Remove the DSN definition for the SalesData database.

Moving to a different computer

You can also use the ttBackup and ttRestore utilities to move a database between two computers that have the same CPU architecture and are running the same operating system.

To copy a database from one system to another with the same CPU architecture and operating system:

1. Back up the database on the original system using ttBackup.

2. Move the backup to the new system.

3. Reconfigure the replication scheme on any databases the replicate to the moved database to specify the new host computer. (See Oracle TimesTen In-Memory Database TimesTen to TimesTen Replication Guide for details on how to specify a host in a replication scheme.)

4. Restore the backup using ttRestore.

The following example uses the -o flag of ttBackup to use standard output for the backup. Using the -o flag, the backup is stored in a single file, which is easily copied over the network to the other system. Once you have copied the database to the other system, you must create a data source name for access to the new database copy.

To move a database from /ds/Sales/Data with database name salesdata on the source system to /data/Sales/View with database name salesview on the destination system, use the following commands.

Reducing database size

Once a database has been defined with a particular size for the permanent partition (indicated by the PermSize DSN attribute), it cannot be loaded at a smaller size, even if tables or rows are deleted. A copy of the database made with ttBackup also has the database's permanent partition size embedded in it.

To reduce the allocated size of the permanent partition of a database, save a copy using the ttMigrate utility with the -noRepUpgrade option. Then re-create the database with a smaller permanent partition size and restore the data.

Perform these steps to reduce the permanent partition size of a database:

1. Back up the old database: ttMigrate -c -noRepUpgrade

2. Create a new DSN definition for the new copy of the database with a smaller PermSize value.

3. Restore the backup: ttMigrate -r -noRepUpgrade

Here are the steps to reduce a database's allocated size from 400 MB to 100 MB. The database is in /ds/Sales/Data and has the DSN salesdata.

1. ttMigrate -c -noRepUpgrade DSN=salesdata /tmp/salesbackup

2. ttDestroy salesdata

3. Update the DSN salesdata to have a size of 100 MB.

4. ttMigrate -r -noRepUpgrade "DSN=salesdata;AutoCreate\=1" /tmp/salesbackup

Moving between 32-bit and 64-bit databases

The internal format of a 32-bit TimesTen database differs from that of a 64-bit database. To convert a 32-bit database to a 64-bit database:

1. Export the 32-bit database using the TimesTen 32-bit ttMigrate utility with the -noRepUpgrade option.

2. Create a Data Source Name (DSN) for the 64-bit database. See "Creating a Data Manager DSN on UNIX" or "Creating a Data Manager DSN on Windows" in Oracle TimesTen In-Memory Database Operations Guide.

3. Import the file created in Step 1 into the 64-bit database DSN using the 64-bit ttMigrate utility with the -noRepUpgrade option.

For example, suppose that the 32-bit database DSN is salesdata32 while the 64-bit database DSN is salesdata64. If a 32-bit instance of TimesTen is installed in /opt/TimesTen/giraffe32 and a 64-bit instance is installed in /opt/TimesTen/giraffe64, the required steps are:

1. /opt/TimesTen/giraffe32/bin/ttMigrate -c -noRepUpgrade DSN=salesdata32/tmp/salesbackup

2. /opt/TimesTen/giraffe64/bin/ttMigrate -r -noRepUpgrade "DSN=salesdata64;AutoCreate=1"/tmp/salesbackup

Moving to a different major release of TimesTen

You can have multiple TimesTen major releases installed on a system at the same time. However, TimesTen databases created by one major release cannot be accessed directly by applications of a different major release. To migrate data between TimesTen major releases, for example from TimesTen 6.0 to 11.2.1, you must export the data using the ttMigrate utility from the old release and import it using the ttMigrate utility from the new release. The procedure for this upgrade is similar to the steps outlined in "Moving between 32-bit and 64-bit databases".

If you need to upgrade two or more databases that are replicating to each other, you must perform a few extra steps to ensure that replication continues to operate during and after the upgrade. For example, to migrate two replicating databases, master1 on host computer masterhost and subscriber1 on host computer subscriberhost, from TimesTen release 6.0 to TimesTen release 11.2.1, perform the following steps.

1. Configure the replication scheme on both databases to use static TCP/IP ports for replication. This is necessary because the intermediate result of this procedure is that replication occurs between two different releases of TimesTen. Each release does not necessarily know how to find the main daemon of the other to have the replication ports assigned dynamically. See "Port assignments" in the Oracle TimesTen In-Memory Database TimesTen to TimesTen Replication Guide for more information.

2. On the computer masterhost, use the ttAdmin utility of the 6.0 release to stop the replication daemon on the database:

   ttAdmin -repStop master1
   

3. Next, use the ttMigrate utility of the 6.0 release with the -c option to back up database master1 to a binary file:

   ttMigrate -c DSN=master1 master1.bak
   

4. Use the ttDestroy utility of the 6.0 release to destroy database master1, where the database's files are located in the directory data_store_path:

   ttDestroy /data_store_path/master1
   

5. Use the ttMigrate utility of the 11.2.1 release with the -r option to restore database master1 from the binary file. Restoring the database automatically upgrades it from release 6.0 to release 11.2.1. If you are restoring a very large database, you should use the -C option to tell ttMigrate to perform a checkpoint operation on the database periodically. This saves time if the restore fails at some point before the operation has been completed. For more information, see "Checkpoint operations" in the Oracle TimesTen In-Memory Database Operations Guide.

   ttMigrate -r -C 20 DSN=master1 master1.bak
   

6. Use the ttAdmin utility of the 11.2.1 release to start the replication daemon:

   ttAdmin -repStart master1
   

   Replication is now occurring between the database master1 on release 11.2.1 and the database subscriber1 on release 6.0.

   Now upgrade database subscriber1 from release 6.0 to release 11.2.1 with the steps that follow.

7. On the computer subscriberhost, use the ttAdmin utility of the 6.0 release to stop the replication daemon:

   ttAdmin -repStop subscriber1
   

8. Use the ttDestroy utility of the 6.0 release to destroy database subscriber1, where the database files are located in the directory data_store_path:

   ttDestroy data_store_path/subscriber1
   

9. If you are upgrading from a release previous to 11.2.1, you must create a user with ADMIN privileges to duplicate a database using replication. For example, to create the user pat with the password patpwd on the standby master database:

   CREATE USER pat IDENTIFIED BY patpwd;
   GRANT ADMIN TO pat;
   

10. Use the ttRepAdmin utility of the 11.2.1 release with the -duplicate option to duplicate database subscriber1 from database master1 using replication.

    ttRepAdmin -duplicate -from master1 -host masterhost -uid pat -pwd patpwd
     -setMasterRepStart subscriber1
    

11. Use the ttAdmin utility of the 11.2.1 release to start the replication daemon:

    ttAdmin -repStart subscriber1
    

The databases are now upgraded and replicating to each other.

Overview

Upgrading a database from an older TimesTen release to a newer release is performed by disconnecting all applications from one of two replicated copies of a database, making a backup of the database with the ttMigrate utility from the older release, loading the backup into a newer release database using the ttMigrate utility from the newer release, and then reconnecting all applications to the upgraded database.

The general steps in an online upgrade include:

1. Disconnect all applications from the database being upgraded.

2. Shut down replication on the system being upgraded.

3. Back up the database residing on the system being upgraded using the older release's ttMigrate with the -c option.

4. Install the newer release of TimesTen on the system being upgraded.

5. Restore the replicated database on the system being upgraded using the newer release's ttMigrate with the -r option.

6. Reconnect all applications to the upgraded database.

7. Restart replication on the upgraded system.

To maintain continuous availability, applications continue to run on one copy of the database while the upgrade is performed on the disconnected copy of the database. TimesTen replication retains updates made to the active copy of the database during the upgrade period, and then transfers and applies the updates to the upgraded database when replication is restarted. When the replicated updates have been completely applied, the applications may be reconnected to the upgraded database.

The following timeline illustrates the steps for performing an online upgrade while replication is running. The upgrade system is the system on which the database upgrade is being performed, and the active system is the system containing the database to which the application remains connected.

After the above procedures are carried out on the upgrade system, the active system can be upgraded using the same steps.

Limitations

Online upgrades can be performed only on databases for which all the user tables meet the replication requirements. All the user tables must contain either a PRIMARY KEY declaration or have a unique index declared over non-nullable columns.

Requirements

To perform online upgrades with replication, replication must be configured to use static ports. See "Port assignments" in the Oracle TimesTen In-Memory Database TimesTen to TimesTen Replication Guide.

If you are performing an online upgrade on a single system where a bidirectional replication configuration does not exist, you must make sure that enough memory and disk space are available to support two copies of the database being upgraded. Both the original database and its copy remain active for the duration of the upgrade. To maintain the performance of your production applications, you may want to create the copy of the database on a second system.

Additional disk space must be allocated to hold a backup copy of the database made by the ttMigrate utility. The size of the backup copy is typically about the same as the in-use size of the database. This size may be determined by querying the sys.monitor table, using ttIsql:

Command> SELECT perm_in_use_size FROM sys.monitor;

Online upgrade example

This section describes how to perform an online upgrade of two bidirectionally replicated TimesTen databases, using a specific example.

We'll refer to the two TimesTen systems being upgraded as the upgrade system, on which the TimesTen instance and the database are upgraded, and the active system, which remains operational and connected to the application for the duration of the upgrade. After this procedure is completed, the same steps can be followed to upgrade the active system. However, you may prefer to delay conversion of the active system to first test the upgraded TimesTen instance.

The upgrade system in this example consists of the database upgrade on the server upgradehost. The active system consists of the database active on the server activehost.

Follow the steps listed here in the order they are presented. The online upgrade procedures are:

ttRepAdmin -connStr DSN=active
 -receiver -name upgrade
 -state pause

ttAdmin -repStop upgrade

ttAdmin -repStop active

ttRepAdmin -connStr DSN=upgrade
  -receiver -name active
  -state stop

ttMigrate -c DSN=upgrade /backup/upgrade.dat

ttDestroy upgrade

ttAdmin -ramUnload upgrade

ttAdmin -repStart active

ttRepAdmin -connStr DSN=active
 -receiver -name upgrade
 -start start

ttMigrate -r
 "DSN=upgrade;AutoCreate=0"
 /backup/upgrade.dat

ttAdmin -ramLoad upgrade

ttRepAdmin -connStr DSN=upgrade
   -receiver -name active -reset
ttRepAdmin -connStr DSN=upgrade
   -receiver -name active
   -state stop
sleep 10
ttRepAdmin -connStr DSN=upgrade
   -receiver -name active
   -state start
sleep 10

ttAdmin -repStart upgrade

Upgrading the databases in an active standby pair with no cache groups

This section includes the following topics:

• Upgrades for TimesTen patch releases on the standby master database and subscriber databases

• Upgrades for TimesTen patch releases on the active master database

• Upgrades for major TimesTen releases, application software and hardware

Upgrading the databases in an active standby pair with cache groups

This section includes the following topics:

• Upgrades for TimesTen patch releases on the standby master database and subscriber databases

• Upgrades for TimesTen patch releases on the active master database

• Upgrades for major TimesTen releases, application software and hardware

Client/Server online upgrade

To perform an online upgrade of a TimesTen Client/Server system to a new major release with minimal reconfiguration, perform the following steps:

1. Stop the TimesTen Server on the old release of TimesTen. From this point until the TimesTen Server for the new release is started, your client applications do not have access to the database. Any attempted updates to the database by the clients fail, and you should stop user applications if necessary.

2. Install the new release of TimesTen. At install time, configure the server to listen on the same port as the old release of TimesTen.

3. Use ttMigrate to migrate the database from the old release to the new release. See "Moving between 32-bit and 64-bit databases" for an example of this procedure.

4. Start the new release of TimesTen Server. The client applications now have access to the upgraded databases.

Client/Server online upgrade with continuous access to the database

The migration of a database using ttMigrate can be a long process if your databases are very large. If it is critical that your client applications have nearly continuous access to the database during the Client/Server online upgrade procedure, you may incorporate the procedure for performing an online upgrade with replication by following these steps:

1. Install the new release of TimesTen, making sure to configure TimesTen Server to listen on the same port as the old release. The installation script asks whether you would like to start the new server. You must answer "no".

2. Follow the steps in "Performing an online upgrade with replication" to upgrade one copy of the database. The client applications remain connected to the other, non-upgraded copy of the database.

3. Disconnect all clients from the old release of the database.

4. Stop the old release of TimesTen Server.

5. Wait for all updates to finish replicating from the old release of the database to the new release.

6. Start the new release of TimesTen Server. It begins listening on the same port as the old release, and client applications may now connect to the new release of the database with no change to their configurations.