Enable automatic database reconnection

Specify a connection set using database connection parameters

Database connection parameter considerations

• Like other database startup parameters, -dbalt1, -dbalt2, -retryConnect, and -retryConnectPause apply only to the last database parameter (-db) encountered in the parameter list thus far.
• You must specify the primary database first, before listing an alternate, otherwise the AVM issues an error.
• If both -dbalt1 and -dbalt2 are specified and the connection to the primary database fails, -dbalt1 is tried first and -dbalt2 is tried second.
• If you only specify -dbalt2, it becomes the first alternate.
• If the AVM is unable to connect to any database the CONNECT statement goes through the usual error handling.
• Any database parameters from the primary database, except for -H and -S, are also applied to the alternate databases, such as -ld, -U and -P.
• The logical name of the alternate database is always taken from the primary database, even if not explicitly set with -ld.
• If the same parameter is encountered more than once within the argument list for -dbalt1 or -dbalt2, the last one is used. This is consistent with the parsing rules for parameters in general.
• If multiple -dbalt1 or -dbalt2 parameters are encountered within the parameter list for a particular primary database, the last one is used.
• -ct (Connection Retry Attempts) is an independent, but related, startup parameter that controls the number of connection retries for an individual database connection. The connection attempts are done in succession on the same database connection and have a default value of 50 attempts; the AVM pauses one second between connection attempts. This differs from -retryConnect, which applies to the connection set as a whole. If using both -ct and -retryConnect, you may want to set -ct to 0, or to a value lower than the default.

Example configurations

Example: Specify a primary database with one alternate:

-db mainDb -H PrimarySrvr -S 6999
-dbalt1 'altDb -H AltSrvr1 -S 7999' 
-retryConnect 3

Example: Specify a primary database with two alternates:

-db myDb -H PrimarySrvr -S 6999
-dbalt1 'myDbTarget1 -H AltSrvr1 -S 7999' 
-dbalt2 'myDbTarget2 -H AltSrvr2 -S 7999'
-retryConnect 10 -retryConnectPause 4

Example: Specify multiple primary databases with alternates:

-db myDb -H PrimarySrvr -S 6999
-dbalt1 'myDbTarget1 -H AltSrvr1 -S 7999' 
-dbalt2 'myDbTarget2 -H AltSrvr2 -S 7999'
-retryConnect 10 -retryConnectPause 4
-db otherDb -H OtherDbSrvr -S 6998
-dbalt1 'otherDbTarget1 -H AltOtherSrvr1 -S 7998' 
-dbalt2 'otherDbTarget2 -H AltOtherSrvr2 -S 7998'
-retryConnect 8 -retryConnectPause 3

Usage of parameters in the CONNECT statement

You may also use these database connection parameters in a CONNECT statement. For -dbalt1 and -dbalt2 each alternate database name, along with its host and port parameters, must be enclosed in quotes. In the following example, the arguments to -dbalt1 and -dbalt2 are surrounded by single quotes and the connection string is surrounded by double quotes. You can reverse this and use double quotes to surround the inner arguments and use single quotes for the outer connection string.

In the following example code, one alternate database is specified:

CONNECT -db myDb -H PrimarySrvr -S 6999 -dbalt1 'myDbBackup -H AltSrvr1 -S 7999'.

The following example code assigns the connection string to a CHARACTER variable. It uses single quotes to enclose the inner -dbalt1 parameters and double quotes for the outer string:

conn = "-db myDb -H PrimarySrvr -S 6999 -dbalt1 'myDbBackup -H AltSrvr1 -S 7999'".
CONNECT VALUE(conn).

The following example code specifies two alternate databases:

conn = "-db myDb -H PrimarySrvr -S 6999
  -dbalt1 'myDbBackup -H AltSrvr1 -S 7999' 
  -dbalt2 'myDbBackup -H AltSrvr2 -S 7999'
  -retryConnect 10 -retryConnectPause 4".
CONNECT VALUE(conn).

Enable logging for troubleshooting

The DB.Connects log entry type (-logentrytypes DB.Connects) turns on logging for database connections. (For information on configuring and enabling logging, see Logging infrastructure overview.) Normally, connect and disconnect messages are logged at the basic level (2 or higher). With this feature, additional messages are logged if the initial attempt to connect to the primary database fails. Consider the following connection string:

-db prim -H localhost -S 1234 
-dbalt1 "alt1 -H localhost -S 2345" 
-dbalt2 "alt2 -H localhost -S 3456" 
-retryConnect 2 
-retryConnectPause 3

CONN           Connected to alternate database alt2

CONN           Attempting to connect to database prim (primary)
CONN           Failed to connect to database prim
CONN           Failover: attempting to connect to database alt1 (-dbalt1)
CONN           Failed to connect to database alt1
CONN           Failover: attempting to connect to database alt2 (-dbalt2)

CONN           Pausing 3 seconds between connection attempts

CONN           Session restart: attempting to reconnect any disconnected databases

See also

Connection Retry Attempts (-ct)

CONNECT statement

Database connection logging