3. Usage Instructions#

This chapter describes how to use the Adapter for JDBC.

jdbcAdapter Constraints#

There are several constraints in order to properly use jdbcAdapter. jdbcAdapter cannot be used If the following conditions are not satisfied.

Prerequisite#

If there is a conflict in input/modify/delete operation in the target DB(Other DB), the operation is canceled and the message is left in the error log file or ignored according to the setting.
The error occurred during the replication can be partially revoked. That is to say, if there is replication data while inputting multiple data, the rest of the data is completed except the replication data.
The replication speed might be slower than the service speed

Data Constraints#

A primary key is required in the table to be replicated.
To be replicated, the primary key of the table cannot be modified.
Tables to be replicated on both servers must have the same order and primary key constraints.

Connection Constraints#

The maximum number of possible XLog Senders and replicated connections in Altibase database is determined by the value set in the REPLICATION_MAX_COUNT property.

Allowed DDL Statements#

Generally, the replication target table cannot execute the data definition language (DDL). However, the following DDLs can be executed regardless of XLog Sender. Refer to Executing DDL Statements on Replication Target Tables in the Replication Manual for more information on other allowed DDL statements.

ALTER INDEX SET PERSISTENT = ON/OFF
ALTER INDEX REBUILD PARTITION
GRANT OBJECT
REVOKE OBJECT
CREATE TRIGGER
DROP TRIGGER

Allowed DDL statements in Replication Target Tables#

In general, if a data definition language (DDL) is executed on a replication target table, jdbcAdapter is terminated after all changes that occurred before the current DDL are reflected in the target database. When jdbcAdapter is terminated, replication can be performed again by executing the same DDL on the target database to make the table schema the same and restarting jdbcAdapter.

For other DDLs that can be executed, please refer to Execution DDL Statements on Replication Target Tables in the Replication Manual.

LOB Data Type Constraints#

LOB data types are supported starting from Adapter for JDBC version 7.1.0.7.0.
To use the LOB data type, set the ADAPTER_LOB_TYPE_SUPPORT property to 1.
A table that includes LOB data type has a constraint for the following three properties. For more information, please refer to the description of each property.
When modifying LOB data using SELECT FOR UPDATE on the Altibase server, it is recommended to perform the operation after committing the transaction.
If users do not commit, LOB data updated by SELECT FOR UPDATE may not be replicated in the following situations:
- If an error occurs during replication of data modified prior to executing SELECT FOR UPDATE.
- If SKIP occurs due to the OTHER_DATABASE_SKIP_ERROR, OTHER_DATABASE_SKIP_INSERT, or OTHER_DATABASE_SKIP_UPDATE properties during replication of data modified prior to executing SELECT FOR UPDATE.

Startup and Shutdown#

This section describes how to start and stop jdbcAdapter.

Startup#

This section explains how to run jdbcAdapter step by step.

To use jdbcAdapter, Altibase and Other DB to which data is to be sent must be running first. Also, Adapter for JDBC properties and environment variables jdbcAdapter must be properly configured as an environment that can be executed.

If any environment variable or property is changed after jdbcAdapter is started, jdbcAdapter must be restarted to apply this change. For detailed information on setting environment variables, refer to Chapter 2, "Post Installation Tasks".

Verify if Altibase's REPLICATION_PORT_NO¹ property is actually set to the replication port number. If the change of this property setting is needed, Altibase must be restarted.
Before starting jdbcAdapter, the user must configure the XLog sender so that Altibase Log Analyzer (ALA) can be used. XLog sender is used to send XLog and meta information from Altibase.
Using PROPAGABLE LOGGING to transfer the log of a replicated transaction to another server, FOR ANALYSIS PROPAGATION must be used.
The following statement creates XLog Sender to replicate data in the table t1 owned by the sys user in Altibase to the table t2 which is owned by user2 in Altibase DB.
```
CREATE REPLICATION ala FOR ANALYSIS WITH '127.0.0.1', 25090
FROM sys.t1 TO user1.t2;
```
Now, it is time to start jdbcAdapter. jdbcAdapter can be started by executing it directly or by using Adapter for JDBC utility. For more detailed information on how to start jdbcAdapter with the Adapter for JDBC utility, please refer to Adapter for JDBC Utility in this manual. It should be noted that the jdbcsAdapter can be started with the following command in the LINUX operating system.
```
$ cd $JDBC_ADAPTER_HOME/bin
$ ./jdbcAdapter
```
Start XLog sender for Altibase Log Analyzer. Attempting to start the XLog sender before running jdbcAdapter will fail.
```
iSQL> ALTER REPLICATION ala START;
```

Shutdown#

The process of shutting down the jdbcAdapter includes stopping the XLog sender. If the jdbcAdapter is forcibly terminated using the Adapter for JDBC utility, it will be successfully terminated, but the Altibase XLog sender will continue to attempt to connect with the jdbcAdapter.

iSQL> ALTER REPLICATION ala STOP;
Alter success.

Data Types#

When Altibase data is applied to other db using JDBC, it is converted to JAVA String type and applied. However, the DATE type is converted to JAVA Timestamp type and applied.

The supported data types are FLOAT, NUMERIC, DOUBLE, REAL, BIGINT, INTEGER, SMALLINT, DATE, CHAR, VARCHAR, NCHAR, and NVARCHAR.

Adapter for JDBC Utility#

Adapter for JDBC utility (oaUtility) is a script that runs jdbcAdapter with the daemon and checks its status. This script is executed in the bash shell in which GNU sed is installed. Constraints on other DB are not checked.

The Adapter for JDBC Utility supports the following options:

oaUtility start
oaUtility stop
oaUtility status
oaUtility check

oaUtility start#

Syntax#

oaUtility {start}

Description#

This is used to start jdbcAdapter as a daemon.

oaUtility stop#

Syntax#

oaUtility {stop}

Description#

This option forcibly terminates jdbcAdapter which is currently processing.

oaUtility status#

Syntax#

oaUtility {status}

Description#

This is used to check whether jdbcAdapter is running.

oaUtility check#

Syntax#

oaUtility { check [ alive ] }

Description#

This option is used to continuously check whether jdbcAdapter operates or not, and restarts if oaUtility is terminated(regardless of normal shutdown or forcible shutdown).

If the alive option is specified, only one check is made to see if jdbcAdapter is running, and then oaUtility is terminated

Command-Line Option#

jdbcAdapter provides the following command options.

Syntax#

jdbcAdapter [ -v | -version ]

Description#

This option is used to output the version of Altibase with which jdbcAdapter was compiled.

Example#

$./jdbcAdapter -v
Adapter for JDBC version 7.3.0.0.1
...

Offline Option#

Syntax#

CREATE REPLICATION ala_replication_name FOR ANALYSIS OPTIONS META_LOGGING 
                   WITH 'remote_host_ip', remote_host_port_no 
                   FROM user_name.table_name TO user_name.table_name;                   
ALTER REPLICATION ala_replication_name SET OFFLINE ENABLE WITH 'log_dir';
ALTER REPLICATION ala_replication_name SET OFFLINE DISABLE;
ALTER REPLICATION ala_replication_name BUILD OFFLINE META [AT SN(sn)];
ALTER REPLICATION ala_replication_name RESET OFFLINE META;
ALTER REPLICATION ala_replication_name START WITH OFFLINE;

Description#

Using the jdbcAdapter to apply changed data from the Altibase server to another database, it is impossible to send logs that were not applied to the other database if a failure occurs on the running Altibase server. In this case, if the Altibase server is running with the META_LOGGING option and there is a Standby server with the same database structure as the Altibase server, the Offline option helps the Standby server access the unsent log files in the Altibase server where the failure occurs directly, and apply them to the other databases.

META_LOGGING
This logs the sender meta and Restart SN information in files. When a failure occurs, the files are used to configure the meta information necessary to read unsent logs. The files are created within the ala_meta_files folder in the log file path.
SET OFFLINE ENABLE WITH 'log_dir'
This enables the use of the offline replication option. This statement can only be executed when replication is stopped. It sets up the Standby server to access the log files directly by specifying the log file path of the Altibase server where the failure occurs.
SET OFFLINE DISABLE
This disables the use of the offline replication option. This statement can only be executed when replication is stopped.
BUILD OFFLINE META
This reads the sender meta and Restart SN files from the ala_meta_files folder in the specified log file path. This constructs the necessary meta information for the offline replication.
RESET OFFLINE META

This command is used to reset the offline replication metadata after executing BUILD OFFLINE META. It can be performed in the following situations:
- When an error occurs during offline replication and the metadata needs to be reconfigured.
- When offline replication is no longer necessary, and the metadata is no longer required.
However, if an error occurs during offline replication due to DDL logs, there is no need to execute RESET OFFLINE META. In this case, running RESET OFFLINE META will cause the DDL logs to be read repeatedly, and the error may recur.
START WITH OFFLINE

Replication is performed using the configured offline path. Offline replication is a one-time operation that applies all untransmitted logs and then immediately terminates. After offline replication is complete, replication can be started again.

If DDL logs are included in the replication gap during offline replication, the operation will be halted. In this case, the user must verify whether the DDL statements executed on the Active server were also executed on the server performing offline replication, and then perform offline replication again.

Constraints#

Reading and writing functions of the sender meta or Restart SN file can be executed by ALA only.
The ALA object name for the server running the offline jdbcAdapter must be the same as the ALA object name for the Active server.
Offline jdbcAdapter does not support ALA objects with compressed tables as replication targets.
If the offline jdbcAdapter cannot access the log file and the sender meta file paths of the Active server due to disk issues, the operation fails.
The log file size of the Active server and Standby server must be the same. The size is determined during the database creation, so it must be verified before using the offline option.
Changing log files and the sender meta files arbitrarily (renaming, copying log files to another system, deleting) can lead to abnormal termination issues.
If users restart the Standby server after performing BUILD OFFLINE META, the Remote Meta information used for analyzing logs disappears. Therefore, users need to execute BUILD OFFLINE META again.
When using the META_LOGGING Option, ALA also does not process the gap as the Archive logs, similar to replication.
If the SM version, OS, OS bit size (32 or 64), or log file size of the two database servers are different, starting Offline jdbcAdapter or creating an ALA object with the offline option fails.

Example#

No	Active Server	Standby Server	Other DB
1. Create scheme	CREATE TABLE T1 (I1 INTEGER PRIMARY KEY, I2 CHAR(20));	CREATE TABLE T1 (I1 INTEGER PRIMARY KEY, I2 CHAR(20));	CREATE TABLE T1 (I1 INTEGER PRIMARY KEY, I2 CHAR(20));
2. Create replication	CREATE REPLICATION ALA FOR ANALYSIS OPTIONS META_LOGGING WITH 'adapter_ip', adapter_port FROM SYS.T1 to SYS.T1;	CREATE REPLICATION ALA FOR ANALYSIS WITH 'adapter_ip', adapter_port FROM SYS.T1 to SYS.T1;
3. Start jdbcAdapter on the Active server	$oaUtility start
4. Start replication on the Active server	ALTER REPLICATION ALA START;
5. Failure occurs on the Active server	Failure occurs
6. Start jdbcAdapter on the Standby server		$oaUtility start
7. Set the offline option on the Standby server replication		ALTER REPLICATION ALA SET OFFLINE ENABLE WITH 'active_home/logs'
8. Configure the offline meta information		ALTER REPLICATION ALA BUILD OFFLINE META;
9. Start offline replication		ALTER REPLICATION ALA START WITH OFFLINE;

Example - Processing When Replication GAP contains DDL#

No	Active Server	Standby Server	Other DB
1. Create scheme	CREATE TABLE T1 (I1 INTEGER PRIMARY KEY, I2 CHAR(20));	CREATE TABLE T1 (I1 INTEGER PRIMARY KEY, I2 CHAR(20));	CREATE TABLE T1 (I1 INTEGER PRIMARY KEY, I2 CHAR(20));
2. Create replication	CREATE REPLICATION ALA FOR ANALYSIS OPTIONS META_LOGGING WITH 'adapter_ip', adapter_port FROM SYS.T1 to SYS.T1;	CREATE REPLICATION ALA FOR ANALYSIS WITH 'adapter_ip', adapter_port FROM SYS.T1 to SYS.T1;
3. Start jdbcAdapter on the Active server	$oaUtility start
4. Start replication on the Active server	ALTER REPLICATION ALA START;
5. DDL on the active server	DDL
6. Failure occurs on the Active server	Failure occurs
7. Start jdbcAdapter on the Standby server		$oaUtility start
8. Set offline option on the Standby server replication		ALTER REPLICATION ALA SET OFFLINE ENABLE WITH 'active_home/logs'
9. Configure the offline meta information		ALTER REPLICATION ALA BUILD OFFLINE META;
10. Start offline replication		ALTER REPLICATION ALA START WITH OFFLINE;
11. The error occurs because of DDL logs		[ERR-611B6 : Offline ALA Sender read DDL log.]
12.DDL on Other DB			DDL
13. Restart jdbcAdatper on the Standby server		$oaUtility start
14. Restart offline replication		ALTER REPLICATION ALA START WITH OFFLINE;

REPLICATION_PORT_NO specifies the replication port number used by the local server for replication connections. For more information about this property, please refer to the Getting Started Guide. ↩

Administrator

Reference

Developer

Tools

External Tools

3. Usage Instructions#

jdbcAdapter Constraints#

Prerequisite#

Data Constraints#

Connection Constraints#

Allowed DDL Statements#

Allowed DDL statements in Replication Target Tables#

LOB Data Type Constraints#

Startup and Shutdown#

Startup#

Shutdown#

Data Types#

Adapter for JDBC Utility#

oaUtility start#

Syntax#

Description#

oaUtility stop#

Syntax#

Description#

oaUtility status#

Syntax#

Description#

oaUtility check#

Syntax#

Description#

Command-Line Option#

Syntax#

Description#

Example#

Offline Option#

Syntax#

Description#

Constraints#

Example#

Example - Processing When Replication GAP contains DDL#