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

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.

Example 3–3 Example of creating a database

The following command is an example of creating a database:

hadbm create --spares 2 --devicesize 1024  --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, and not from different DRUs..

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 re-fragmentation 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.

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

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

  • Sun GlassFishMessage 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 Sun GlassFish Enterprise Server 2.1 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 get 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 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).

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.

Configuring the JDBC Connection Pool

Enterprise 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

• Creating a JDBC Resource

For general information about connection pools and JDBC resources, see Sun GlassFish Enterprise Server 2.1 High Availability 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.

com.sun.hadb.jdbc.ds.HadbDataSource

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

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.