This section describes the following basic HADB configuration tasks:
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 .
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.
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.
Create the management domain.
For more information, see Creating a Management Domain
Register the HADB package.
For more information, see Registering HADB Packages for more information.
Use the hadbm create command to create the database.
For information on command syntax, see the following section.
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 |
---|---|---|
-a |
Number of data devices on each node, between one and eight inclusive. Data devices are numbered starting at 0. |
1 |
-d |
Path to the devices. There are four devices:
|
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 |
-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. |
-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.) |
-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. Host names 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 |
-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 |
-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 |
-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 |
The following command is an example of creating a database:
hadbm create --spares 2 --devicesize 1024 --hosts n0,n1,n2,n3,n4,n5
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
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
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.
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.
You can view and modify database configuration attributes with the hadbm get and hadbm set commands, respectively.
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.
hadbm get JdbcUrl,NumberOfSessions
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.
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 |
---|---|---|---|
If true, records a message in the HADB history files when a client connection (JDBC, ODBC) is initiated or terminated. |
False |
True or False |
|
Do not change the default value. |
False |
True or False |
|
Name of the database. |
hadb | ||
Size of the data buffer pool allocated in shared memory. |
200MB |
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. |
1024MB |
32 - 262144 MB |
|
PackageName |
Name of HADB software package used by the database. |
V4.x.x.x |
None |
Location of the devices. Devices are:
|
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. |
12MB |
4 - 128 MB |
|
The JDBC connection URL for the database. This is a read-only attribute. |
none | ||
Size of the log buffer, which keeps track of operations related to data. |
48MB |
4 - 2048 MB |
|
Maximum number of tables allowed in an HADB database. |
1100 |
100 - 1100 |
|
Number of data devices used by an HADB node. This is a read-only attribute. |
1 |
1 - 8 |
|
Number of locks allocated by an HADB node. |
50000 |
20000-1073741824 |
|
Maximum number of sessions (database connections) that can be opened for an HADB node. |
100 |
1 - 10000 |
|
Base port number used to create different port numbers for different HADB processes. This is a read-only attribute. |
15200 |
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. |
NONE |
NONE/SHORT/ FULL |
|
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 |
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 |
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. |
warning |
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 |
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:
For general information about connection pools and JDBC resources, see Sun GlassFish Enterprise Server 2.1 High Availability Administration Guide.
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.
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
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 |
---|---|
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. |
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 ( \).
The following table summarizes JDBC resource settings required for HADB.
Table 3–11 HADB JDBC Resource Settings
Setting |
Description |
---|---|
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. |
|
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 |
|
Checked/true |