Skip to content
≡

Administrator

Developer

Tools

External Tools

2. Installation and Configuration#

This chapter describes how to install and configure the Adapter for JDBC.

Pre-installation Tasks#

The following system requirements should be satisfied in order to install and run jdbcAdapter. Also, there are some required configurations for jdbcAdapter to properly perform.

For detailed information about system requirements, please contact Altibase's Customer Support.

OS#

jdbcAdapter is currently only supported in the following OS:

  • LINUX : x86-64bit

Database Versions#

  • Altibase : Version 6.3.1 or later

  • OTHER DB : JDBC 4.1 or earlier versions of other database

Database Character Set#

This is the default character set for storing data.

National Character Set#

The data for a language not supported by the database character set can be stored with NCHAR and NVARCHAR types.

Installing JDBC Driver#

In order to use jdbcAdapter, JDBC driver should be installed on a machine in which jdbcAdapter will be operating. At this point, JDBC driver should be provided by a vendor of the replication target database. For example, if the database to be replicated is Oracle DB, go to the Oracle website. Download and install the version of the JDBC driver that matches the Oracle database server version.

Installation JRE#

jdbcAdapter is an application program running in JRE 7 or above versions; thus, JRE 7 or higher versions should be installed in which jdbcAdapter will be performed.

If the JDBC driver for the remote database to which jdbcAdapter will connect is running on JRE version 7 or above, a version of the JRE compatible with the JDBC driver should be installed.

After installing JRE, environment variables, such as JAVA_HOME and CLASSPATH should be installed. The following is an example of specifying environment variables for JRE in the UNIX operation system.

$ export JAVA_HOME=The path in which export JAVA_HOME=JRE is installed.
$ export CLASSPATH=${JAVA_HOME}/lib:${CLASSPATH}
$ export PATH=${JAVA_HOME}/bin:${PATH}
$ export LD_LIBRARY_PATH=$JAVA_HOME/jre/lib/amd64/server:${ LD_LIBRARY_PATH )


Installation#

jdbcAdapter installer can be executed in GUI mode if DISPLAY environment variables are properly configured. jdbcAdapter installation is described in this manual with an assumption that the installation is being executed in GUI mode. Also, it is possible to install jdbcAdapter in text mode if the appropriate DISPLAY settings have not been properly made or the GUI mode cannot be used.

Installing jdbcAdapter#

It is recommended to install jdbcAdapter on another user's account rather than Altibase server account of the original DB.

  1. The first task is to determine the version of jdbcAdapter installer suitable for the operating system in which jdbcAdapter will run. The naming convention for jdbcAdapter installer is shown as follows. The jdbcAdapter version must be the same as the version of Altibase with which it will be run.

  2. When the installer is executed, the dialog box appears. Verify the version of jdbcAdapter to be installed then click "Forward".

  3. Select the directory in which jdbcAdapter will be installed in the next dialog box. A jdbcAdapter directory will be created within the home directory of the user account.

  4. In order to use jdbcAdapter, Altibase Log Analyzer (ALA) property should be specified as in the following. Refer to ALA Properties section described later in this chapter.

    • ALA_SENDER_IP: This is the IP address of the server on which Altibase is installed. The default value is 127.0.0.1 on the assumption that Altibase and jdbcAdapter will be operating on the same machine.
    • ALA_RECEIVER_PORT: This is a port number for jdbcAdapter to receive data. The number should be specified within the range from 1024 to 65536.
    • ALA_REPLICATION_NAME: This is the name of a replication object existing in Altibase.
    • ALA_XLOG_POOL_SIZE: This is used to specify the maximum size of XLog pool. The default value is set to 100,000 XLogs.
    • ALA_SOCKET_TYPE: This is used to set the communication socket type used by ALA. jdbcAdapter supports TCP/IP and UNIX Domain Socket.
    • ALA_LOGGING_ACTIVE:This is used to specify for ALA whether or not to write trace logs. If the value of this property is 1, trace logs are written. The default value is 1.

  5. Altibase property configuration should be implemented in the following dialog box. Refer to the Properties for Checking Constraints described later in this chapter for detailed information.

    • ALTIBASE_USER: This is the name of the user account accessing Altibase.

    • ALTIBASE_PASSWORD: This is the password for the user account accessing Altibase.

    • ALTIBASE_IP: This is the IP address of the server on which Altibase is installed. Assuming that Altibase and jdbcAdapter work on the same machine, the default value of this property is 127.0.0.1.

    • ALTIBASE_PORT: This is the port number where the Altibase server is listening. It should be set to a value between 1024 and 65536.

  6. Other DB properties should also be properly configured in order to use jdbcAdapter. Refer to the Properties for DML and JDBC Properties for detailed information on properties.

    • OTHER_DATABASE_USER: This is the name of a user account with which to access the Other DB.
    • OTHER_DATABASE_PASSWORD: This is the password corresponding to the user account accessing other database, which is the target database.
    • OTHER_ DATABASE_SKIP_INSERT: If "Yes" is selected, INSERT statement executed in Altibase will not be performed in Other DB.
    • OTHER_DATABASE_SKIP_UPDATE: If "Yes" is selected, UPDATE statement executed in Altibase will not be performed in Other DB.
    • OTHER_DATABASE_SKIP_DELETE: If "Yes" is selected, DELETE statement executed in Altibase will not be performed in Other DB.
    • OTHER_DATABASE_GROUP_COMMIT: This property allows multiple transactions to be executed at once.
    • OTHER_DATABASE_BATCH_DML_MAX_SIZE: "Batch DML" means to process multiple DML statements with batch processing. This property specifies how many DML statements to batch. To disable the Batch DML function, set this property to 1.
    • OTHER_DATABASE_SET_USER_TO_TABLE : When applying DML to Other DB, the user of the target table is set as the user specified in XLog Sender. Set this property to 0 to disable the function.
    • OTHER_DATABASE_JDBC_MAX_HEAP_SIZE : This property determines the maximum size of Heap used in JVM.
    • OTHER_DATABASE_JDBC_DRIVER_PATH : This property specifies JDBC driver path for Other DB.
    • OTHER_DATABASE_JDBC_DRIVER_CLASS : This property sets the name for Other DB JDBC driver class.
    • OTHER_DATABASE_JDBC_CONNECTION_URL : This property specifies the connection URL of Other DB.

  7. Once all of the property settings pertaining to the use of jdbcAdapter, a dialog box showing specified values will appear. Then, verify if every property is properly specified, and click "Forward" to proceed to the next

  8. Click "Forward" in the "Ready to Install" dialog box to start the installation.

  9. While the jdbcAdapter is being installed, the following two environment variables are set. In order for the new environment variable to be applied to the system, the user must log out and log in again.

    • JDBC_ADAPTER_HOME: This environment variable will have jdbcAdapter home directory specified in previous step before the installation process as a value.

    • PATH: $JDBC_ADAPTER_HOME/bin path is included in this environment variable.

  10. A completion dialog box will appear after the installation is successfully completed.

Post-installation Tasks#

Setting Environment Variables#

After installing jdbcAdapter, it is required to configure environment variables, add a library path, and set the database and national character sets.

Refer to the "Configuration" section described later in this chapter for more detailed information on configuring the environment variables.

  • JDBC_ADAPTER_HOME
    This environment variable is automatically set when installing jdbcAdapter

  • ALTIBASE_NLS_USE
    The character set used in Altibase is specified in this environment variable. Refer to the Getting Started Guide for more detailed information on the character set.

Confirmation of Installation Directory#

After jdbcAdapter installation is complete, verify the bin, conf, msg, and trc directories have been created under $JDBC_ADAPTER_HOME directory. The role and structure of each directory is as follows.

  • bin directory
    The executable and internally used files of jdbcAdapter (Adapter for JDBC) and oaUtility (Adapter for JDBC utility) are located in this directory.

  • conf directory
    This directory is located in jdbcAdapter.conf file storing jdbcAdapter property configuration.

  • msg directory
    If an error occurs while jdbcAdapter is being installed, the error is written to the trace log. The error message which is located in the directory will be used.

  • trc directory
    jdbcAdapter writes trace logs to files located in this directory.


Configuration#

The following environment variables should be configured in order to use jdbcAdapter.

JDBC_ADAPTER_HOME#

This is an environment variable specifying the directory in which jdbcAdapter was installed. This environment variable is automatically configured during the jdbcAdapter installation.

ALTIBASE_NLS_USE#

This environment variable specifies the character set used in Altibase for use in ALA. Refer to Getting Started Guide> Multilingual Support for more information on the character set.


Properties#

jdbcAdapter properties are used by ALTIBASE Log Analyzer and JDBC, and they are also used for determining an operation mode.

The property file is jdbcAdapter.conf located in $JDBC_ADPATER_HOME/conf directory.

The properties used in jdbcAdapter are classified as the following:

  • Properties for ALA
  • Properties for verifying constraints
  • Properties of other database which will be the target to which to send data
  • DML related properties

ALA Properties#

The following properties should be configured for jdbcAdapter to appropriately use Altibase Log Analyzer (ALA). Refer to Log Analyzer User's Manual for detailed information.

ALA_SENDER_IP#

This is a property specifying the IP address of Xlog sender. This property enables Altibase to set the IP address of server equipment on which Altibase has been installed.

  • Default Value: 127.0.0.1

ALA_RECEIVER_PORT#

This property specifies the port number used by the XLog collector to receive XLogs. This property specifies the port number on which jdbcAdpater is listening.

  • Range: 1024 - 65535

ALA_SENDER_REPLICATION_PORT#

This property specifies the port number for XLog collector to receive XLog. This property is used to specify the port number on which jdbcAdapter is waiting.

  • Default Value: 0

  • Range: 0 ~ 65535

  • 0: The adapter waits until the sender of the ALA replication object attempts to connect(Depends on the value of the REPLICATION_SENDER_SLEEP_TIMEOUT attribute of the Altibase server).

  • 1 or more: Adapter attempts to connect directly to the replication sender with the corresponding port number

ALA_RECEIVE_XLOG_TIMEOUT (Unit: Second)#

This is a property specifying the waiting time for XLog collector to receive XLogs.

  • Default Value: 300

  • Range: 1 - 4294967295

ALA_REPLICATION_NAME#

This property specifies the name of the replication object which is used as XLog sender. The name is identical to that of the replication object created within Altibase.

ALA_SOCKET_TYPE#

This is a property specifying the socket type which will be used by Altibase Log Analyzer. However, to use Unix Domain socket, Altibase and jdbcAapter should be located on the same machine.

  • TCP: Use of TCP/IP socket (Default value)

  • UNIX: Use of UNIX Domain socket

ALA_XLOG_POOL_SIZE (Unit: count)#

This is a property specifying the maximum size of XLog pool in jdbcAdapter.

In the jdbcAdapter, the record changes before the transaction of the original DB is committed are accumulated in XLog, respectively. If a transaction occurring in the source DB changes a number of records, there is not enough XLog that jdbcAdapter can allocate, and it cannot be replicated normally. Therefore, the value of this property must be adjusted according to the transaction type of the original DB.

When the ALA Sender performs a Sync operation on the original DB, the commit is performed with the number set in the REPLICATION_SYNC_TUPLE_COUNT property. Therefore, if the ALA_XLOG_POOL_SIZE property value is smaller than the REPLICATION_SYNC_TUPLE_COUNT value, there is not enough XLog to allocate and sync operation does not proceed, so the property value must be set larger.

  • Default Value: 100,000

  • Range: 1 - 2147483647

ALA_LOGGING_ACTIVE#

This property determines whether to allow Altibase Log Analyzer to output trace logs.

  • 0: Do not output the trace log.

  • 1: Output the trace log (Default)

Properties for Checking Constraints#

ALTIBASE_USER#

This property specifies the name of the user account with which to access Altibase.

ALTIBASE_PASSWORD#

This property specifies the password of the user account with which to access Altibase.

ALTIBASE_IP#

This property specifies the IP address of the server machine on which Altibase is installed.

  • Default Value: 127.0.0.1

ALTIBASE_PORT#

This property specifies the number of ports at which Altibase listens.

  • Range: 1024 - 65535

ADAPTER_ERROR_RESTART_COUNT (Unit: count)#

This property specifies additional operation on all errors of Adapter.

  • Default Value: 0

  • Range: 0 ~ 65535

  • 0: An error message is output as terminating Adapter.

  • 1 or more: "Re-start Adapter and apply sync target DBMS access/record " is executed for the specified number of times. If it exceeds the specified counts, the error message is output as terminating Adapter.

ADAPTER_ERROR_RESTART_INTERVAL (Unit: count)#

This property specifies the interval when re-attempting for the number of times specified in ADAPTER_ERROR_RESTART_COUNT.

  • Default Value: 0

  • Range: 0 ~ 65535

  • 0: Immediately re-attempt without any interval.

ADAPTER_LOB_TYPE_SUPPORT#

This property determines if the LOB data type is supported or not.

  • Default: -
  • 0: Do not support LOB data type.
  • 1: Support LOB data type.

Other Database Properties#

The following properties must be set in order to use Other DB, which is the target to send data from jdbcAdapter.

OTHER_DATABASE_USER#

This property specifies the name of the user account to access the other DB to which data is sent.

OTHER_DATABASE_PASSWORD#

This property specifies the password of the user account to access the other DB to which data is sent.

OTHER_DATABASE_JDBC_MAX_HEAP_SIZE (Unit: Mega Bytes)#

This specifies the maximum size of Heap JVM uses.

  • Default Value: 2048

  • Range: 0 - 10240

  • This property should be set to 0 to let JVM automatically set the maximum size of Heap.

OTHER_DATABASE_JDBC_DRIVER_PATH#

This property specifies JDBC driver path for other DB.

OTHER_DATABASE_JDBC_DRIVER_CLASS#

This property specifies the class name of JDBC Driver for other DB.

OTHER_DATABASE_JDBC_CONNECTION_URL#

The connection URL of other DB is specified by this property.

The following properties are used to set whether DML statements executed in Altibase will also be executed in the other DB.

OTHER_DATABASE_GROUP_COMMIT#

Multiple transactions can be processed at once. Even if commit execution is performed in the original Altibase server, the Target DB postpones committing until a certain amount of transactions are accumulated. Therefore, the overall performance can be improved, but the response time of individual transactions might be postponed.

  • Default Value: 1

  • 0: Do not commit group.

  • 1: Commit group.

OTHER_DATABASE_BATCH_DML_MAX_SIZE (Unit: count)#

"Batch DML" means to batch process multiple DML statements of the same type. This results in improved performance by reducing network cost.

  • Default Value: 10

  • Range: 1 - 32767

This property has the following characteristics.

This property has the following characteristics:

  • Enabling the OTHER_DATABASE_GROUP_COMMIT property improves performance.
  • Currently, this property only affects INSERT and DELETE statements.
  • In order to turn off Batch DML, this property should be set to 1.
  • If users use the LOB interface to update LOB data, the Batch DML feature will not work.

OTHER_DATABASE_ERROR_RETRY_COUNT (Unit: count)#

This indicates the number of retry attempts if an error occurs when applying to records. However, XLogs that include LOB data are excluded from retry attempts in case of an error.

  • Default Value: 0

  • Range: 0 ~ 65535

  • 0: Do not retry.

OTHER_DATABASE_ERROR_RETRY_INTERVAL (Unit: second)#

This indicates a retry interval between error occurrences when applying records.

  • Default Value: 0

  • Range: 0 ~ 65535

  • 0: Immediately retry without any intervals

OTHER_DATABASE_SKIP_ERROR#

This determines whether to discard writing the relevant records if it fails to record even though retry was attempted as much as OTHER_DATABASE_ERROR_RETRY_TIME at intervals of OTHER_DATABASE_ERROR_RETRY_COUNT.

  • Default Value: 1
  • 0: Error message is output as terminating Adapter. (Do not discard writing the relevant records.) However, the record in which the error included in dbms_skip_error_include.list has occurred is abandoned and the next record is reflected.
  • 1: Write from the next records. (Discard writing the relevant records.) However, the adpater is terminated for records in which errors included in dbms_skip_error_exclude.list have occurred. However, if an error occurs during XLog processing related to LOBs, the adapter does not abandon the record but instead terminates.

The error values included in dbms_skip_error_include.list and dbms_skip_error_exclude.list are SQLSTATE standard error values.

OTHER_DATABASE_SKIP_INSERT#

This property determines whether the INSERT statement performed in Altibase is also executed in other DB to which data is sent. If this property is set to 1, the INSERT statement performed in Altibase is not executed in other DB.

  • Default Value: 0

  • 0: Do not omit statement execution. Thus, the statement execution is normally executed.

  • 1: Omit statement execution.

OTHER_DATABASE_SKIP_UPDATE#

This property determines whether the UPDATE statement executed in Altibase is also executed in other DB to which data is sent. If this property is set to 1, the UPDATE statement executed in Altibase is not executed in other DB.

  • Default Value: 0

  • 0: Do not omit statement execution. That is, the statement execution is normally executed.

  • 1: Omit statement execution.

OTHER_DATABASE_SKIP_DELETE#

This property determines whether the DELETE statement executed in Altibase is also executed in other DB which is the target database to which data is sent. If this property is set to 1, the DELETE statement executed in Altibase is not executed in other DB.

  • Default Value: 0

  • 0: Do not omit statement execution. That is, the statement execution is normally executed.

  • 1: Omit statement execution.

OTHER_DATABASE_SET_USER_TO_TABLE#

When executing DML in other DB, set the user of the reflection table to the user specified in XLog Sender.

  • Default Value: 0

  • 0: Do not specify a user

  • 1: Specify a user

Property Constraints#

Spaces or tabs cannot be used when setting property values.

Also, in order to use characters including special characters together, the property value must be handled with double quotation marks ("").