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

- Previous: Using the hadbm Management Command
- Next: Managing HADB

# Configuring HADB

This section describes the following basic HADB configuration tasks:

- Creating a Management Domain

- Creating a Database

- Viewing and Modifying Configuration Attributes

- Configuring the JDBC Connection Pool

## 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]
     hostlist

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:

- Not be members of an existing domain.

- Be configured to use the same port.

- Be able to reach each other over UDP, TCP, and with IP multicast.

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.

### To 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) | Description | Default
--- | --- | ---
--datadevices= number -a | Number of data devices on each node, between one and eight inclusive. Data devices are numbered starting at 0. | 1
--devicepath= path -d | 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 -z | 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 | 1024MB 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 -t | 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 -H | 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 `127.0.0.1` as a host name. See Specifying Hosts for more information. | None
--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. | None
--packagepath=path-L | 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. | None
--portbase= number -b | 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. | 15200
--spares= number -s | Number of spare nodes. This number must be even and must be less than the number of nodes specified in the `--hosts` option. | 0
--set=attr-val-list -S | Comma-separated list of database configuration attributes in name =value format. For explanations of database configuration attributes, see Clearing and Archiving History Files | None

##### 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

Where

- x is the total size of user data

- n is the number of nodes (given by the `--hosts` option)

- d is the number of devices per node (given by the `--datadevices` option)

- l is the log buffer size (given by the attribute `LogBufferSize`)

  If refragmentation might occur (for example, using `hadbm addnodes`), then the recommended device size is:

      (8x / 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`:

`node-nodeno.device-devno.Devicepath`

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:

    node-nodeno.historypath=path

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.

### Troubleshooting

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

- Ensure you have started the management agents on all the hosts and defined an HADB domain. For details, see Starting the Management Agent

- File and directory permissions must be set to allow read, write, and execute access to the install, history, device, and config paths for the following users:

  - Sun Java System Application Server administrative user (set during installation)

  - HADB system user

    For details about setting user permissions, see Preparing for HADB Setup

  Application Server and HADB port assignments must not conflict with other port assignments on the same machine. Default recommended port assignments are:

  - Sun Java SystemMessage Queue: 7676

  - IIOP: 3700

  - HTTP server: 80

  - Administration server: 4848

  - HADB nodes: Each node uses six consecutive ports. For example, for default port 15200, node 0 uses 15200 through 15205 , node 1 uses 15220 through 15225, and so on.

  Disk space must be adequate; see the Sun Java System Application Server Release Notes.

## 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
    [dbname]
    [--adminpassword=password | --adminpasswordfile=file]
    [--agent=maurl]

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
    =value[,attribute=
    value...]
     [--adminpassword=password | --adminpasswordfile=file]
     [--agent=maurl]

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).

- DatabaseName

- DevicePath

- HistoryPath

- NumberOfDatadevices

- Portbase

- JdbcUrl (its value is set during database creation based on the `--hosts` and `--portbase` options).

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

Attribute | Description | Default | Range
--- | --- | --- | ---
ConnectionTrace | If true, records a message in the HADB history files when a client connection (JDBC, ODBC) is initiated or terminated. | False | True or False
CoreFile | Do not change the default value. | False | True or False
DatabaseName | Name of the database. | hadb |
DataBufferPoolSize | Size of the data buffer pool allocated in shared memory. | 200MB | 16 - 2047 MB
DataDeviceSize | 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. | 1024MB | 32 - 262144 MB
PackageName | Name of HADB software package used by the database. | V4.x.x.x | None
DevicePath | 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. |
EagerSessionThreshold | 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
EagerSessionTimeout | The time in seconds a database connection can be idle before it expires when eager session expiration is used. | 120 seconds | 0-2147483647 seconds
EventBufferSize | 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
HistoryPath | 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.) |
InternalLogbufferSize | Size of the node internal log device, which keeps track of operations related to storing data. | 12MB | 4 - 128 MB
JdbcUrl | The JDBC connection URL for the database. This is a read-only attribute. | none |
LogbufferSize | Size of the log buffer, which keeps track of operations related to data. | 48MB | 4 - 2048 MB
MaxTables | Maximum number of tables allowed in an HADB database. | 1100 | 100 - 1100
NumberOfDatadevices | Number of data devices used by an HADB node. This is a read-only attribute. | 1 | 1 - 8
NumberOfLocks | Number of locks allocated by an HADB node. | 50000 | 20000-1073741824
NumberOfSessions | Maximum number of sessions (database connections) that can be opened for an HADB node. | 100 | 1 - 10000
PortBase | Base port number used to create different port numbers for different HADB processes. This is a read-only attribute. | 15200 | 10000 - 63000
RelalgDeviceSize | Size of the device used in relational algebra queries. | 128 MB | 32 - 262144 MB
SessionTimeout | Amount of time a database connection can be idle before it expires when normal session expiration is used. | 1800 seconds | 0-2147483647 seconds
SQLTraceMode | 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. | NONE | NONE/SHORT/ FULL
StartRepairDelay | 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
StatInterval | 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
SyslogFacility | 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 | local0, local1, local2, local3, local4, local5, local6, local7, kern, user, mail, daemon, auth, syslog, lpr, news, uucp, cron, none
SysLogging | If true, an HADB node writes information to the operating system’s `syslog` files. | True | True or False
SysLogLevel | 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. | warning | nonealert errorwarninginfo
SyslogPrefix | Text string inserted before all `syslog` messages written by the HADB. | hadb -dbname |
TakeoverTime | 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

- Creating a Connection Pool

- Example 3–5

- Creating a JDBC Resource

  For general information about connection pools and JDBC resources, see Administration Guide.

### 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:

    jdbc:sun:hadb:host:port,
    host:port,...

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

Setting | Required Value for HADB
--- | ---
Name | The HADB JDBC resource’s Pool Name setting must refer to this name
Database Vendor | HADB 4.4
Global Transaction Support | Unchecked/false
DataSource Classname |
    com.sun.hadb.jdbc.ds.HadbDataSource
Steady Pool Size | Use 8 connections for each active HADB node. For more detailed information, see the System Deployment Guide.
Connection Validation Required | Checked/true
Validation Method | `meta-data`
Table Name | Do not specify
Fail All Connections | Unchecked/false
Transaction Isolation | `repeatable-read`
Guarantee Isolation Level | Checked/true

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

Property | Description
--- | ---
username | Name of the `storeuser` to use in the `asadmin create-session-store` command.
password | Password (`storepassword` ) to us in the `asadmin create-session-store` command.
serverList | 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.
cacheDatabaseMetaData | When `false` , as required, ensures that calls to `Connection.getMetaData()` make calls to the database, which ensures that the connection is valid.
eliminateRedundantEndTransaction | When `true` , as required, improves performance by eliminating redundant commit and rollback requests and ignoring these requests if no transaction is open.
maxStatement | 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
    --steadypoolsize=32
    --isolationlevel=repeatable-read
    --isconnectvalidatereq=true
    --validationmethod=meta-data
    --property username=storename:password=secret456:serverList=
    host\:port,host\:port,
    host\\:port,host\:port,
    host\:port,host\:port
    :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

Setting | Description
--- | ---
JNDI Name | 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 | Checked/true

- Previous: Using the hadbm Management Command
- Next: Managing HADB

- © 2010, Oracle Corporation and/or its affiliates