Sun Java System Application Server Enterprise Edition 8.1 2005Q2 High Availability Administration Guide

Configuring HADB

This section describes the following basic HADB configuration tasks:

Creating a Management Domain

The command hadbm createdomain creates a management domain containing the specified HADB hosts. The command initializes internal communication channels between hosts and the persistence configuration store.

The syntax of the command is:

hadbm createdomain
 [--adminpassword=password |--adminpasswordfile=
file | --no-adminauthentication] [--agent=maurl]

The hostlist operand is a comma-separated list of HADB hosts, each of which is a valid IPv4 network address. Include all the hosts that you want to be in the new domain in the hostlist.

See General Options for a description of the command options.

Before using this command, be sure an HADB management agent is running on every host in the hostlist. Additionally, the management agents must:

After hadbm creates the management domain, it enables all the hosts in the domain. Then the management agents are ready to manage databases. After creating HADB domains, the next step is to create the HADB database. For more information on creating HADB databases, see Creating a Database .

Example 3–2 Creating an HADB Management Domain

The following example creates a management domain on the four specified hosts:

hadbm createdomain --adminpassword= password host1,host2,host3,host4

After hadbm successfully executes the command, you will see the message:

Domain host1,host2,host3, host4 created.

After creating HADB domains, register the path and version of the HADB packages with the management agents.

Creating a Database

Use the hadbm create command to create a database manually.

Before you use this command to create a database, create the management domain and register the HADB package. If you have not performed these two steps when you run hadbm create , it implicitly performs them. Although this might seem like less work, failures in any of the commands can make debugging difficult. Besides, hadbm create is not atomic, that is, if one of the implicit commands fails, the commands that executed successfully will not be rolled back. Therefore, it is best to create the database only after creating the domain and registering the HADB package.

For example, if hadbm createdomain and hadbm registerpackage execute successfully but hadbm create database fails, the changes made by hadbm createdomain and hadbm registerpackage will persist.

ProcedureTo create a database

  1. Create the management domain.

    For more information, see Creating a Management Domain

  2. Register the HADB package.

    For more information, see Registering HADB Packages for more information.

  3. Use the hadbm create command to create the database.

    For information on command syntax, see the following section.

hadbm create Command Syntax

hadbm create [--package=name] [--packagepath=path] [--historypath=path] [--devicepath=path] [--datadevices=number ] [--portbase=number] [--spares=number] [--set=attr-val-list] [--agent=maurl] [--no-cleanup] [ --no-clear ] [ --devicesize =size] [--dbpassword=password | --dbpasswordfile=file ] --hosts=host list [--adminpassword=password | --adminpasswordfile=file | --no-adminauthentication ] [dbname]

The dbname operand specifies the database name, which must be unique. To make sure the database name is unique, use the hadbm list command to list existing database names. Use the default database name unless you need to create multiple databases. For example, to create multiple clusters with independent databases on the same set of HADB machines, use a separate database name for each cluster.

The hadbm create command writes error messages to the console, not log files.

Table 3–7 describes the special hadbm create command options. See General Options for a description of additional command options.

Table 3–7 hadbm create Options

Option(Short Form) 



--datadevices= number


Number of data devices on each node, between one and eight inclusive. Data devices are numbered starting at 0. 

--devicepath= path


Path to the devices. There are four devices: 

  • DataDevice

  • NiLogDevice (node internal log device)

  • RelalgDevice (relational algebra query device)

  • NoManDevice (node manager device).

    This path must exist and be writable. To set this path differently for each node or each device, see Setting Heterogeneous Device Paths

Solaris and Linux: /var/opt/SUNWhadb

Windows: C:\Sun\AppServer\SUNWhadb\vers, where vers is the HADB version number.

Default is specified by ma.server.dbdevicepath in management agent configuration file. For more details, see Configuration File

--devicesize= size


Device size for each node. For more information, see Specifying Device Size.

Increase the device size as described in Adding Storage Space to Existing Nodes


Maximum size is lesser of maximum operating system file size or 256 GB. Minimum size is: 

(4 x LogbufferSize + 16MB) / n

Where n is the number of data devices given by the option --datadevices.

--historypath= path


Path to the history files. This path must already exist and be writable. 

For more information on history files, see Clearing and Archiving History Files

Default is specified by ma.server.dbhistorypath in management agent configuration file. For details, see Configuration File

Solaris and Linux:/var/opt/SUNWhadb

On Windows: REPLACEDIR (replaced by the actual URL at runtime.) 

--hosts= hostlist


Comma-separated list of host names or IP addresses (IPv4 only) for the nodes in the database. Use IP addresses to avoid dependence on DNS lookups. Host names must be absolute. You cannot use localhost or as a host name.

See Specifying Hosts for more information.


--package=name -k

Name of the HADB package (version). If the package is not found, a default package is registered. 

This option is deprecated. Use the hadbm registerpackage command to register a package in the domain. 



Path to the HADB software package. Use only if the package is not registered in the domain. 

This option is deprecated. Use the hadbm registerpackage command to register a package in the domain. 


--portbase= number


Port base number used for node 0. Successive nodes are automatically assigned port base numbers in steps of 20 from this number. Each node uses its port base number and the next five consecutively numbered ports. 

To run several databases on the same machine, have a plan for allocating port numbers explicitly. 


--spares= number


Number of spare nodes. This number must be even and must be less than the number of nodes specified in the --hosts option.



Comma-separated list of database configuration attributes in name =value format. For explanations of database configuration attributes, see Clearing and Archiving History Files


Example 3–3 Example of creating a database

The following command is an example of creating a database:

hadbm create --spares 2 --devicesize 1024 --dbpassword secret123
 --hosts n0,n1,n2,n3,n4,n5

Specifying Hosts

Use the --hosts option to specify a comma-separated list of host names or IP addresses for the nodes in the database. The hadbm create command creates one node for each host name (or IP address) in the list. The number of nodes must be even. Use duplicate host names to create multiple nodes on the same machine with different port numbers. Make sure that nodes on the same machine are not mirror nodes.

Nodes are numbered starting at zero in the order listed in this option. The first mirrored pair are nodes zero (0) and one (1), the second two (2) and three (3), and so on. Odd numbered nodes are in one DRU, even numbered nodes in the other. With --spares option, spare nodes are those with the highest numbers.

For information about configuring double network interfaces, see Configuring Network Redundancy

Specifying Device Size

Specify the device size using the --devicesize option. The recommended device size is:

(4x / nd + 4l/d) / 0.99 


Setting Heterogeneous Device Paths

To set a different device path for each node or service, use the -- set option of hadbm create. There are four types of devices: the DataDevice, the NiLogDevice (node internal log device), the RelalgDevice (relational algebra query device), and the NoManDevice (node manager device). The syntax for each name =value pair is as follows, where -devno is required only if the device is DataDevice:


For example:

--set Node-0.DataDevice-0.DevicePath=/disk0,
Node-1.DataDevice-0.DevicePath=/disk 1

You can also set a heterogeneous path to history files, as follows:


For information on history files, see Clearing and Archiving History Files

Any device path that is not set for a particular node or device defaults to the --devicepath value.

Note –

Change device paths and location of history files using hadbm set and hadbm addnodes commands.


If you have difficulty creating a database, check the following:

Viewing and Modifying Configuration Attributes

You can view and modify database configuration attributes with the hadbm get and hadbm set commands, respectively.

Getting the Values of Configuration Attributes

To get the values of configuration attributes, use the hadbm get command. For a list of valid attributes, see Configuration Attributes. The command syntax is:

hadbm get attribute-list | --all  
[--adminpassword=password | --adminpasswordfile=file]  

The dbname operand specifies the database name. The default is hadb.

The attribute-list operand is a comma-separated or quote-enclosed space-separated list of attributes. The --all option displays values for all attributes. For a list of all attributes for hadbm get, see Configuration Attributes.

See General Options for a description of command options.

Example 3–4 Example of using hadbm get

hadbm get JdbcUrl,NumberOfSessions

Setting the Values of Configuration Attributes

To set the values of configuration attributes, use the hadbm set command. For a list of valid attributes, see Configuration Attributes

hadbm set [dbname] attribute
 [--adminpassword=password | --adminpasswordfile=file]

The dbname operand specifies the database name. The default is hadb.

The attribute=value list is a comma-separated or quote-enclosed space-separated list of attributes.

See General Options for a description of command options.

If this command executes successfully, it restarts the database in the state it was in previously, or in a better state. For information about database states, see Getting the Status of HADB restart the HADB as described in Restarting a Database.

You cannot set the following attributes with hadbm set. Instead, set them when you create a database (see Creating a Database).

Note –

Using hadbm set to set any configuration attribute, except ConnectionTrace or SQLTraceMode, causes a rolling restart of HADB. In a rolling restart, each node is stopped, and started with the new configuration, one at a time; HADB services are not interrupted.

If you set ConnectionTrace or SQLTraceMode, no rolling restart occurs, but the change only takes effect for new HADB connections made from an Application Server instance.

Configuration Attributes

The following table lists the configuration attributes that you can modify with hadbm set and retrieve with hadbm get.

Table 3–8 Configuration Attributes






If true, records a message in the HADB history files when a client connection (JDBC, ODBC) is initiated or terminated. 


True or False 


Do not change the default value. 


True or False 


Name of the database. 




Size of the data buffer pool allocated in shared memory. 


16 - 2047 MB 


Specifies the device size for the node. For information on the recommended DataDeviceSize, see Specifying Device Size

The maximum value is the smaller of 256GB or the maximum operating system file size. The minimum value is: 

(4 x LogbufferSize + 16MB) / n

where n is number of data devices.


32 - 262144 MB 


Name of HADB software package used by the database. 




Location of the devices. Devices are: 

  • Data device (DataDevice)

  • Node internal log device (NiLogDevice)

  • Relational algebra query device (RelalgDevice)

Solaris and Linux: /var/opt/SUNWhadb

Windows: C:\Sun\AppServer\SUNWhadb\vers, where vers is the HADB version number.



Determines whether normal or eager idle session expiration is used. 

In normal idle session expiration, sessions that are idle for more than SessionTimeout seconds are expired.

When the number of concurrent sessions exceeds the EagerSessionThreshold percentage of the maximum number of sessions, sessions that are idle for more than EagerSessionTimeout seconds are expired.

Half of NumberOfSessions attribute 

0 - 100 


The time in seconds a database connection can be idle before it expires when eager session expiration is used. 

120 seconds 

0-2147483647 seconds 


Size of the event buffer, where database events are logged. If set to 0, no event buffer logging is performed.

During failures, the event buffer is dumped. This gives valuable information on the cause of the failures and is useful during trial deployment. 

Writing events to memory has a performance penalty. 

0 MB

0-2097152 MB 


Location of the HADB history files, which contain information, warnings, and error messages. 

This is a read-only attribute. 

Solaris and Linux: /var/opt/SUNWhadb

Windows: REPLACEDIR (replaced by the actual URL at runtime.) 



Size of the node internal log device, which keeps track of operations related to storing data. 


4 - 128 MB 


The JDBC connection URL for the database. 

This is a read-only attribute. 




Size of the log buffer, which keeps track of operations related to data. 


4 - 2048 MB 


Maximum number of tables allowed in an HADB database. 


100 - 1100 


Number of data devices used by an HADB node. 

This is a read-only attribute. 

1 - 8 


Number of locks allocated by an HADB node. 




Maximum number of sessions (database connections) that can be opened for an HADB node. 


1 - 10000 


Base port number used to create different port numbers for different HADB processes. 

This is a read-only attribute. 


10000 - 63000 


Size of the device used in relational algebra queries. 

128 MB 

32 - 262144 MB 


Amount of time a database connection can be idle before it expires when normal session expiration is used. 

1800 seconds 

0-2147483647 seconds 


Amount of information about executed SQL queries written to the history files. 

If SHORT, login and logout of SQL sessions are recorded. If FULL, all SQL queries being prepared and executed, including parameter values, are recorded.




Maximum time a spare node allows for a failed active node to perform a node recovery. If the failed node cannot recover within this time interval, the spare node starts copying data from the failed node’s mirror and becomes active. Changing the default value is not recommended. 

20 seconds 

0 - 100000 seconds 


Interval at which an HADB node writes throughput and response time statistics to its history file. To disable, set to 0. 

Here is an example of a statistics line: 

Req-reply time: # 123, min= 69 avg= 1160 max= 9311 %=100.0

The number after the has sign (#) is the number of requests serviced over the StatInterval. The next three numbers are the minimum, average, and maximum time in microseconds taken by transactions completed over the StatInterval. The number afer the percent sign ( %) is the number of transactions completed successfully within 15 milliseconds over the StatInterval.

600 seconds 

0 - 600 seconds 


Facility used when reporting to syslog. The syslog daemon should be configured (see man syslogd.conf for details).

Use a facility that is not used by other applications running on the same machine. 

Set to none to disable syslog logging.


local0, local1, local2, local3, local4, local5, local6, local7, kern, user, mail, daemon, auth, syslog, lpr, news, uucp, cron, none 


If true, an HADB node writes information to the operating system’s syslog files.


True or False 


Minimum level of HADB message saved to operating system’s syslog files. All messages of that level or higher will be logged. For example, “info” logs all messages.


nonealert errorwarninginfo 


Text string inserted before all syslog messages written by the HADB.

hadb -dbname 



Time between when a node fails and when its mirror takes over. Do not change the default value. 

10000 (milliseconds) 

500 - 16000 milliseconds 

Configuring the JDBC Connection Pool

Application Server communicates with HADB using the Java Database Connectivity (JDBC) API. The asadmin configure-ha-cluster command automatically creates a JDBC connection pool for use with HADB (for a cluster cluster-name ). The name of the connection pool is cluster-name-hadb-pool. The JNDI URL of JDBC resource is jdbc/cluster-name-hastore.

The initial configuration of the connection pool is normally sufficient. When you add a node, change the steady pool size so that there are eight connections for each HADB active node. See Adding Nodes.

This chapter covers the following topics:

Getting the JDBC URL

Before you can set up the JDBC connection pool, you need to determine the JDBC URL of HADB using the hadbm get command as follows:

hadbm get JdbcUrl [dbname]

For example:

hadbm get JdbcUrl

This command displays the JDBC URL, which is of he following form:


Remove the jdbc:sun:hadb: prefix and use the host:port, host:port... part as the value of the serverList connection pool property, described in Table 3–10.

Creating a Connection Pool

The following table summarizes connection pool settings required for the HADB. Change the Steady Pool Size when adding nodes, but do not change other settings.

Table 3–9 HADB Connection Pool Settings


Required Value for HADB 


The HADB JDBC resource’s Pool Name setting must refer to this name 

Database Vendor

HADB 4.4 

Global Transaction Support


DataSource Classname


Steady Pool Size

Use 8 connections for each active HADB node. For more detailed information, see the System Deployment Guide.

Connection Validation Required


Validation Method


Table Name

Do not specify 

Fail All Connections


Transaction Isolation


Guarantee Isolation Level


The following table summarizes connection pool properties required for the HADB. Change serverList when adding nodes, but do not change other properties.

Table 3–10 HADB Connection Pool Properties




Name of the storeuser to use in the asadmin create-session-store command.


Password (storepassword ) to us in the asadmin create-session-store command.


JDBC URL of the HADB. To determine this value, see Getting the JDBC URL

You must change this value if you add nodes to the database. See Adding Nodes.


When false , as required, ensures that calls to Connection.getMetaData() make calls to the database, which ensures that the connection is valid.


When true , as required, improves performance by eliminating redundant commit and rollback requests and ignoring these requests if no transaction is open.


Maximum number of statements per open connection that are cached in the driver statement pool. Set this property to 20.

Example 3–5 Creating a Connection Pool

Here is an example asadmin create-jdbc-connection-pool command that creates an HADB JDBC connection pool:

asadmin create-jdbc-connection-pool
--user adminname --password secret 
--datasourceclassname com.sun.hadb.jdbc.ds.HadbDataSource
--property username=storename:password=secret456:serverList=
:cacheDatabaseMetaData=false:eliminateRedundantEndTransaction=true hadbpool

On Solaris, escape colon characters (:) within property values with double backslashes (\\). On Windows, escape colon characters (:) with single backslashes ( \).

Creating a JDBC Resource

The following table summarizes JDBC resource settings required for HADB.

Table 3–11 HADB JDBC Resource Settings




The following JNDI name is the default in the session persistence configuration: jdbc/hastore. You can use the default name or a different name.

You must also specify this JNDI name as the value of the store-pool-jndi-name Persistence Store property when you activate the availability service.

Pool Name

Select from the list the name (or ID) of the HADB connection pool used by this JDBC resource. For more information, see Configuring Network Redundancy

Data Source Enabled