The cluster database switcher tool performs all the operations necessary to switch from the default PostgreSQL database to a pre-existing PostgreSQL or Oracle database. The tool performs the following operations:
Connects to both the default PostgreSQL database and to the pre‑existing database.
Creates an application user and schema in the pre-existing database. Creates multiple schemas if your Visualization Platform installation uses more than one volume.
Copies iHub configuration data and volume metadata from the default PostgreSQL database to the pre-existing database.
Updates the database connection settings in the iHub configuration file, acserverconfig.xml.
To use the cluster database switcher tool, you perform the following tasks:
Create a properties file.
The properties listed in the properties file support the tool connecting to the pre-existing database and creating the application user and schema or schemas. You pass the properties file to the tool when you run it.
Run the tool.
You open a command prompt, navigate to the folder containing the cluster database switcher tool script, and run it.
Creating a properties file for the Cluster Database Switcher
Using a text editor, create a properties file named switch_cluster_database.properties. You can create the file in any folder that is convenient. For example, you can create the properties file in the folder containing the cluster database switcher tool. By default, this is the \bin folder inside the iHub tools folder:
The properties file you create is slightly different for each of the following scenarios:
When switching to a pre-existing Oracle database
When switching to a pre-existing PostgreSQL database
When switching to either database type and you have more than one volume
The following sections describe the details for creating a properties file for each of these scenarios.
When you create the properties file, you must provide database entity names, including names for databases, schemas, tablespaces, and users. Database entity names are subject to the following restrictions:
Database entity names must contain only 7-bit ASCII characters.
The name must begin with an ASCII letter and contain only ASCII letters, digits, and underscores.
An Oracle schema name cannot be longer than 30 characters.
Specifying properties for switching to an Oracle database
Table 2‑1 describes the properties to use when switching to a pre-existing Oracle database. Properties having names that begin with TARGET_ pertain to the database to which you are switching. The tool automatically retrieves properties pertaining to the default PostgreSQL database from the iHub configuration file, acserverconfig.xml. An example properties file follows the table.
Table 2‑1 Properties required for switching to an Oracle database
Parameter
Description
AC_SERVER_HOME
Path of the Visualization Platform home folder.
TARGET_DATABASE_TYPE
Type of relational database management system (RDBMS). Specify Oracle.
TARGET_ORACLE_TNS _NAMES_FILE
Full path to an Oracle TNS names file, named tnsnames.ora, which defines the net service for the Oracle database.
BIRT iHub does not use an Oracle client. BIRT iHub only needs a valid TNS names file. If an Oracle client is not installed on the machine where Visualization Platform is installed, you can create a TNS names file to define the net service for the Oracle database. Actuate recommends placing the TNS names file in the BIRT iHub configuration folder, which contains acserverconfig.xml. By default, the path to the iHub configuration folder is <Visualization Platform home folder>\shared\config.
TARGET_DATABASE_NAME
Net service name for the Oracle database.
TARGET_DATABASE _ADMINISTRATOR
Name of a user that has administration privileges on the Oracle database, for example SYSTEM. Do not specify a user with SYSDBA privileges, for example SYS.
TARGET_CREATE_DATABASE _USER
Whether to create a database user. Valid values are true or false. Specify true.
TARGET_DATABASE_USER
User ID that BIRT iHub uses to connect to the Oracle database.
TARGET_CREATE_SCHEMA
Whether to create a schema. Valid values are true or false. Specify true.
TARGET_SCHEMA_NAME
Name of the schema to create for BIRT iHub tables.
TARGET_TABLESPACE_NAME
Name of the Oracle tablespace to use for the BIRT iHub tables and indexes.
Use the following example to create the properties file. In the properties file, paths must always use forward slashes.
Specifying properties for switching to a PostgreSQL database
Table 2‑2 describes the properties to use when switching to a pre-existing PostgreSQL database. Properties having names that begin with TARGET_ pertain to the database to which you are switching. The tool automatically retrieves properties pertaining to the default PostgreSQL database from the iHub configuration file, acserverconfig.xml. An example properties file follows the table.
Table 2‑2 Properties required for switching to a PostgreSQL database
Parameter
Description
AC_SERVER_HOME
Path to the Visualization Platform home folder.
TARGET_DATABASE_TYPE
Type of relational database management system (RDBMS). Specify PostgreSQL.
TARGET_DATABASE_HOST
Network host name of the database server.
TARGET_DATABASE_PORT
Network port for the database server.
TARGET_DATABASE_NAME
Name of the PostgreSQL database.
TARGET_DATABASE _ADMINISTRATOR
Name of a user that has administration privileges on the PostgreSQL database.
TARGET_CREATE_DATABASE _USER
Whether to create a database user. Valid values are true or false. Specify true.
TARGET_DATABASE_USER
User ID that BIRT iHub uses to connect to the PostgreSQL database.
TARGET_CREATE_SCHEMA
Whether to create a schema. Valid values are true or false. Specify true.
TARGET_SCHEMA_NAME
Name of the schema to create for BIRT iHub tables.
Use the following example to create the properties file. In the properties file, paths must always use forward slashes.
Specifying properties when you have multiple volumes
If the cluster has a single volume, the metadata for the volume resides in the same schema as the cluster configuration data. If the cluster has more than one volume, the cluster configuration data resides in a separate schema and the metadata for each volume resides in a separate schema for each volume. The properties required when you have multiple volumes are listed in Table 2‑3.
Table 2‑3 Properties required when you have multiple volumes
Parameter
Description
TARGET_CLUSTER
_SCHEMA_NAME
Name of the schema to create for the cluster configuration data.
TARGET_VOLUME _SCHEMA_NAMES
A list of volume name and schema name pairs. Each pair defines the schema name for a volume. A volume name must be separated from its schema name by a colon (:). Schema and volume name pairs must be separated by a pipe character (|). Use a backslash (\) to continue the list onto a new line.
Use the following example to add these two properties to a properties file.
TARGET_CLUSTER_SCHEMA_NAME = ac_cluster
TARGET_VOLUME_SCHEMA_NAMES = Volume One : ac_volume_01 |\
Volume Two : ac_volume_02 |\
Volume Three : ac_volume_03
Running the Cluster Database Switcher
The Cluster Database Switcher is a batch script named switch_cluster_database.bat. The script is in the /bin folder inside the iHub tools folder. The script takes a single command-line argument, the path to the properties file.
BIRT iHub connects to the metadata database using a database user name and password. When you create the properties file for the cluster database switcher script, you provide the name of the user that BIRT iHub uses to connect to the target database in the TARGET_DATABASE_USER property. You do not, however, include the password in the properties file for security reasons. When you run the script, the script pauses to prompt you for this and other passwords. When you enter the password, the script resumes. The default source database user password is postgres.
How to run the cluster database switcher
1 Open a command prompt. Navigate to the \bin folder inside the iHub tools folder. For example:
Connects to both the default PostgreSQL database and to the pre‑existing database.