Failover Clustering
Failover clustering provides for multiple physical servers (nodes) to access a common, shared storage subsystem that contains one or more file shares or volumes. The failover services ensure that only one server controls the file shares or volumes at a time. Control of the shared storage subsystem is passed automatically from a failed server to the next surviving server in the cluster.
Pervasive PSQL must be licensed separately on each cluster node where you install the database engine. This applies whether the node is a physical machine or a virtual machine. See also License Models in Pervasive PSQL User's Guide. (The failover clustering being discussed refers to Microsoft Failover Clustering or Cluster Service and to Linux Heartbeat. This is distinct from other high availability solutions that may incorporate VM-based clusters.)
This section contain the following topics:
•
Microsoft Failover Clustering for Windows Server 2008 and Later
•
Microsoft Cluster Service for Windows Server 2003
•
Linux Heartbeat
•
Managing Pervasive PSQL in a Cluster Environment
Microsoft Failover Clustering for Windows Server 2008 and Later
This topic discusses adding the Pervasive PSQL services to Failover Clustering and assumes the following:
•
You know how to install and configure Failover Clustering and need only the information required to add and manage the Pervasive PSQL services.
•
You are familiar with using Pervasive PSQL and its primary utilities such as Pervasive PSQL Control Center (PCC).
•
You can set up DSNs using ODBC Administrator.
Differences Between Windows Server Versions
Failover Clustering is essentially the same for Windows Server 2008, Windows Server 2008 R2, and Windows Server 2012.
Note the following differences with Windows Server 2012:
•
In Failover Cluster Manager, “Services and Applications” are called “Roles.”
•
Registry Replication is not supported for Generic Services. The Pervasive PSQL database engine must be manually configured on all nodes as explained in Configure Database Engine Properties with PCC.
Preliminary Requirements
It is essential that Failover Clustering functions correctly before you add the Pervasive PSQL services. For example, verify that the failover completes and that all resources are available. Complete the action again and failover back to the original node. Refer to the Microsoft documentation for how to set up Failover Clustering, verify it is working correctly, and perform tasks with it.
Just as you would for any service, set up the essential clustering components before you add the Pervasive PSQL services. As you set up the components, check the following:
•
Modify the NTFS user permissions, if required, for the shared disk where you want the Pervasive PSQL data to reside. The Pervasive PSQL transactional and relational services typically run under the Local System Account. Ensure that the Local System Account has permissions to read and write to the shared disk.
•
Select “SMB” for the share protocol and modify the SMB permissions if required.
•
Skip DFS Namespace Publishing. DFS is not required for the Pervasive PSQL services.
After setting up the components, a good practice is to verify that the machines on which the Pervasive PSQL client is installed can communicate with the Client Access Point. Also, verify that the machines can browse to the share name.
Recommended Installation Process
The following table explains the recommended process to add Pervasive PSQL to Cluster Services on Windows Server 2008. The process for Windows Server 2012 is essentially the same with differences noted above.
Table 37
Adding Pervasive PSQL to Cluster Services on Windows Server 2008 and Later  
Action
Discussion
Install Pervasive PSQL on the Cluster Nodes
Install Pervasive PSQL Server on each cluster node and choose identical options for each installations.
•
Do not install Pervasive PSQL on the cluster shared storage, where the Pervasive PSQL data resides.
•
Do not install the Pervasive PSQL component called Xtreme I/O ( XIO). A node with XIO installed can hang when the machine comes online through a failover and leave the shared storage inaccessible.
After installation, the Pervasive PSQL transactional service and the relational service are both set to start automatically when the operating system starts. Change the startup type to manual.
The Pervasive PSQL transactional and relational services typically run under the Local System Account. Check the domain permissions for your cluster node accounts if you encounter problems installing Pervasive PSQL.
Add a Cluster Resource for Pervasive PSQL and Set the Properties
The transactional service of Pervasive PSQL is always required as a cluster resource. The relational service is optional and is needed only if your application uses the relational interface.
Include the following as you specify properties for the cluster resource:
•
Select the option Use network name for computer name.
•
For the transactional service, use Software\Pervasive Software for the Root Registry Key.
If you include the relational service, decide how you want to handle data source names (DSNs) for Registry Keys. Perform one of the following:
•
Specify the key SOFTWARE\ODBC if you want to affect all ODBC data sources and ODBC providers installed on the cluster node. Add the following key depending on the operating system architecture: Software\ODBC\ODBC.INI for 32-bit Windows or Software\Wow6432Node\ODBC\ODBC.INI for 64-bit Windows
•
To specify separate DSNs, do not add any key(s) for the registry. Instead, you must first configure the database engines with PCC (see Configure Database Engine Properties with PCC). After that, create the DSNs on an active cluster node, initiate failure, and create the same DSNs on the surviving node. Repeat this until all cluster nodes contain the DSNs.
Note: Because of the dependencies, bring the Pervasive PSQL resources online in the following order (and stop them in the reverse order): first the Pervasive PSQL Transactional Engine then the Pervasive PSQL Relational Engine.
Ensure the Shared Storage Has the Necessary Files and Directories
The Pervasive PSQL transactional and relational services typically run under the Local System Account. Ensure that the Local System Account has permissions to read and write to the shared disk.
Copy the DBNAMES.CFG file from the Application Data area on the active node where you installed Pervasive PSQL to a directory of your choice on the shared storage.
Copy the following directories from the Application Data area on the same node to the same directory on the shared storage. For convenience, you can copy them to the same directory as DBNAMES.CFG, but that is optional.
•
defaultdb
•
Demodata
•
tempdb
•
Transaction Logs
If you want to use Pervasive System Analyzer to perform transactional or relational tests, also copy the Pervasive Software\PSQL\Samples directory.
Configure Database Engine Properties with PCC
You configure the database engine with Pervasive PSQL Control Center (PCC) to add certain configuration settings to the registry. Configure the engine on the active node in your cluster, then initiate a failure to migrate the settings to the next node(s) in your cluster.
In PCC, set the following engine properties for Directories. When PCC prompts you to restart the services, select No.
•
For Transaction Log Directory, specify the location on the shared disk where you copied the Transaction Logs directory.
•
For DBNames Configuration Location, specify the location on the shared disk where you copied the DBNAMES.CFG file.
In the Failover Cluster Management console, take the Pervasive PSQL resources offline and back online.
In PCC, set the following engine properties for Databases:
•
For DEFAULTDB, set Dictionary Location to the location on the shared disk where you copied the defaultdb directory. For Data Directory, add the location on the shared disk where you copied the defaultdb directory and remove the default data directory.
•
Set Dictionary Location and Data Directory for databases DEMODATA and TEMPDB to the location on the shared disk where you copied them. For DEMODATA, specify “Demodata” for the Dictionary Location and Data Directory. For TEMPDB, specify “tempdb” for both.
Migrate the Database Engine Configuration Settings
Migrate the database engine configuration settings to the other node(s) in the cluster. In the Failover Cluster Management console, perform the action Move the service or application to move the Pervasive PSQL service to another node in the cluster.
Verify that the failover completes and that all resources are available. Continue to move the service to each desired node and verify that all resources are available until you failover back to the original node.
Pervasive PSQL is now configured for a Failover Cluster.
Microsoft Cluster Service for Windows Server 2003
This topic discusses adding the Pervasive PSQL services to Failover Clustering and assumes the following:
•
You know how to install and configure Cluster Service and need only the information required to add Pervasive PSQL to a Cluster Service group.
•
You are familiar with using Pervasive PSQL and its primary utilities such as Pervasive PSQL Control Center (PCC).
•
You can set up DSNs using ODBC Administrator.
Preliminary Requirements
It is essential that Cluster Service functions correctly before you add Pervasive PSQL. For example, verify that the failover completes and that all resources are available. Complete the action again and failover back to the original node. Refer to the Microsoft documentation for how to set up Cluster Service, verify it is working correctly, and perform tasks with it.
Just as you would for any application, set up the essential clustering components before you add Pervasive PSQL. As you set up the components, modify the user permissions, if required, for the shared disk where you want the Pervasive PSQL data to reside. The Pervasive PSQL transactional and relational services typically run under the Local System Account. Ensure that the Local System Account has permissions to read and write to the shared disk.
After setting up the components, access a Pervasive PSQL client and verify that it can communication with the cluster shared storage. A Pervasive PSQL client must be able to communicate with a cluster shared storage before and after a cluster node failover. The cluster is functioning correctly if you can execute a command on the shared storage subsystem from a Pervasive PSQL client computer before and after failover.
Recommended Installation Process
The following table explains the recommended process to add Pervasive PSQL to Cluster Service on Windows Server 2003.
Table 38
Adding Pervasive PSQL to Cluster Service on Windows Server 2003  
Action
Discussion
Add a Cluster Group for Pervasive PSQL
With Microsoft Cluster Administrator, create a cluster group to which you will add the Pervasive PSQL resources. Because all resources within a cluster group fail together, we suggest that you create a separate cluster group for Pervasive PSQL. This is not mandatory, but is a good administrative method.
At a minimum, ensure that the cluster group for Pervasive PSQL contains the following resources.
•
IP address of the shared storage subsystem.
•
Network name (the name of the shared storage subsystem).
•
Physical disk (the disk subsystem that contains the Pervasive PSQL database). Ensure that the shared storage is a mounted drive not a mapped drive. The Pervasive PSQL Services are configured under Local System Account by default. That account cannot access mapped drives that were mapped under a different user account.
•
File share for you data files.
In addition, you may want to enable failback for the group and specify a preferred controlling node. See also Pervasive PSQL Failure Behavior.
Install Pervasive PSQL on the Cluster Nodes
Install Pervasive PSQL Server on each cluster node and choose identical options for each installations.
•
Do not install Pervasive PSQL on the cluster shared storage, where the Pervasive PSQL data resides.
•
Do not install the Pervasive PSQL component called Xtreme I/O ( XIO). A node with XIO installed can hang when the machine comes online through a failover and leave the shared storage inaccessible.
The Pervasive PSQL transactional and relational services typically run under the Local System Account. Check the domain permissions for your cluster node accounts if you encounter problems installing Pervasive PSQL.
Add Pervasive PSQL Transactional Service to Cluster Group
The transactional service of Pervasive PSQL is always required as a cluster resource.
In Microsoft Cluster Administrator, add a new Resource and specify Generic Service for the resource type. Select the desired group. Do not check the option Run this resource in a separate Resource Monitor.
Specify the nodes that can function as possible owners for the resource.
For Dependencies, add the following to the list of resource dependences:
•
IP Address
•
Network Name
•
File Share
For Generic Services Parameters, specify “Pervasive.SQL (transactional)” for Service name. Leave the Start parameters blank. Select the option Use Network name for computer name, which allows Pervasive PSQL to open files directly on the shared storage.
Add the following for Registry Key: SOFTWARE\Pervasive Software.
After you add the resource, select its properties. Select the options Restart and Affect the group. Optionally, you may set the Threshold and Period values to your choice.
Optionally, Add Pervasive PSQL Relational Service to Cluster Group
The relational service is optional and is needed only if your application uses the relational interface.
Follow the same procedure as list for Add Pervasive PSQL Transactional Service to Cluster Group with the following exceptions.
For Dependencies, select the “Pervasive PSQL transactional resource” In the Available resources list. You do not need to add the IP Address, Network Name, and File Share for the resource because they are dependencies of the transactional resource.
For Generic Services Parameters, specify “Pervasive.SQL (relational)” for Service name.
The Registry Replication, decide how you want to handle data source names (DSNs) for Registry Keys. Perform one of the following:
•
Specify the key SOFTWARE\ODBC if you want to affect all ODBC data sources and ODBC providers installed on the cluster node. Add the following key depending on the operating system architecture: Software\ODBC\ODBC.INI for 32-bit Windows or Software\Wow6432Node\ODBC\ODBC.INI for 64-bit Windows
•
To specify separate DSNs, do not add any key(s) for the registry. Instead, you must first configure the database engines with PCC (see Configure the Engines with PCC). After that, create the DSNs on an active cluster node, initiate failure, and create the same DSNs on the surviving node. Repeat this until all cluster nodes contain the DSNs.
Bring Pervasive PSQL Services Online Using Cluster Administrator.
After installation, both the transactional and relational services are set to start automatically when the operating system starts. Through the operating system, stop both services and change their startup type to Manual.
After you stop the services at the operating system, bring them online using Cluster Administrator.
Ensure the Shared Storage Has the Necessary Files and Directories
The Pervasive PSQL transactional and relational services typically run under the Local System Account. Ensure that the Local System Account has permissions to read and write to the shared disk.
Copy the DBNAMES.CFG file from the Application Data area on the active node where you installed Pervasive PSQL to a directory of your choice on the shared storage.
Copy the following directories from the Application Data area on the same node to the same directory on the shared storage. For convenience, you can copy them to the same directory as DBNAMES.CFG, but that is optional.
•
defaultdb
•
Demodata
•
tempdb
•
Transaction Logs
If you want to use Pervasive System Analyzer to perform transactional or relational tests, also copy the Pervasive Software\PSQL\Samples directory.
Configure the Engines with PCC
You need to configure the database engine with Pervasive PSQL Control Center (PCC) to add certain configuration settings to the registry. Configure the engine on the active node in your cluster, then initiate a failure to migrate the settings to the next node(s) in your cluster.
Create a new server using Pervasive PSQL Explorer in PCC and specify the network name of the cluster shard storage for the server name.
Access the properties of the server you just added and select Directories.
•
For DBNames Configuration Location, specify the location on the cluster shared drive where you copied the files listed in Ensure the Shared Storage Has the Necessary Files and Directories. Ensure that the shared storage is a mounted drive not a mapped drive. The Pervasive PSQL Services are configured under Local System Account by default. That account cannot access mapped drives that were mapped under a different user account.
•
For Transaction Log Directory, specify a directory on the cluster shared drive where you want the log to reside.
•
For Communication Protocols, ensure that TCP/IP Multihomed is “on.”
In Cluster Administrator, take the Pervasive PSQL transactional service offline, which also takes the Pervasive PSQL relational service offline. Bring both services online.
In Cluster Administrator, initiate a failure so that the next surviving node becomes the new controlling node of the cluster. Repeat this until you initiate failure to each cluster node.
Pervasive PSQL is now configured for a Failover Cluster.
Linux Heartbeat
The Heartbeat program is one of the core components of the Linux-HA (High-Availability Linux) project. Heartbeat runs on all Linux platforms and performs death-of-node detection, communications and cluster management in one process. Pervasive PSQL Server is the recommended product if the Heartbeat cluster uses physical nodes. Pervasive PSQL Vx Server is recommended for clusters that use VM nodes.
This topic discusses adding the Pervasive PSQL services to Linux Heartbeat and assumes the following:
•
You know how to install and configure the Heartbeat program and need only the information required to add Pervasive PSQL to a Cluster Service group.
•
You are familiar with using Pervasive PSQL and its primary utilities such as Pervasive PSQL Control Center (PCC).
Preliminary Requirements
It is essential that Linux Heartbeat be functioning correctly before you add Pervasive PSQL to the cluster. Refer to the documentation from the High Availability Linux Project (www.linux-ha.org) for how to install Heartbeat, verify it is working correctly, and perform tasks with it.
Just as you would for any application, set up the essential clustering components before you add Pervasive PSQL.
Recommended Installation Process
The following table explains the recommended process to add Pervasive PSQL to Linux Heartbeat.
Table 39
Adding Pervasive PSQL to Linux Heartbeat  
Action
Discussion
Install Pervasive PSQL on the Cluster Nodes
Install Pervasive PSQL Server on each cluster node and choose identical options for each installations. Do not install Pervasive PSQL on the cluster shared storage, where the Pervasive PSQL database(s) resides.
After installation, the database engine is set to start automatically when the operating system starts. With clustering, however, Linux Heartbeat controls starting and stopping the database engine. The controlling node in the cluster starts the engine, the other nodes do not.
After you install Pervasive PSQL Server, ensure that the Group IDs for “pvsw” and “pvsw-adm” and the UID for “psql” match on all nodes. If required, change the IDs to ensure they are the same.
Configure the Shared Storage
The shared storage is where is the Pervasive PSQL database resides. Shared storage for Heartbeat can be implemented many different ways. The multitude of possible implementations is beyond the scope of this document. This section assumes that an NFS mount is being used.
Create (or at least identify) a location on shared storage where you want the database to reside. The location is your choice. Ensure that user psql has read, write, and execute authority for the location.
Create two groups and a user on the shared storage to ensure that each cluster node can access the database files.
•
Groups pvsw and pvsw-adm must match pvsw Group ID and pvsw-adm Group ID, respectively, on the cluster nodes.
•
User psql must match psql UID on the cluster nodes.
Create the Directory for the Shared Storage Mount
On each cluster node, log in as user psql then create a directory that will be mounted to the shared storage. (User psql has no password and can only be accessed through the “root” account with the su command.) The name of the directory is your choice.
Configure Heartbeat Server
Configure the Heartbeat server on each of the nodes that will control the Pervasive PSQL database engine. Configure the following:
•
Nodes. Add all nodes that you want in the cluster.
•
Authentication. Specify the type of authentication to use for the network communication between the nodes.
•
Media. Specify the method Heartbeat uses for internal communication between nodes.
•
Start-up. Specify the setting for when the Heartbeat Server starts. Set this to on, which means that the “server starts now and when booting.”
Assign Password for Heartbeat User
Linux Heartbeat provides a default user named “hacluster” for logging in to the Heartbeat Management Client. Assign a password to user “hacluster” on each of the nodes from which you want to run Heartbeat Management Client.
Add a Resource Group for Pervasive PSQL
Log in as root and start the Heartbeat Management Client on one of the cluster nodes. Log in as user “hacluster” and add a new group. For ID, specify a name for the Pervasive PSQL group. Set Ordered and Collocated to “true.”
Add the Resources to the Group
Add three resources to the Pervasive PSQL group:
•
IPaddr
•
Filesystem
•
Psql (OCF resource agent)
IPaddr
In the Heartbeat Management Client, add a new “native” item. For Belong to group, select the group you added for Pervasive PSQL. For Type, select “IPaddr.”
On the resource you just added, specify the IP address of the cluster for the IP Value. Use the IP address assigned to the cluster (not the node) when Linux Heartbeat was installed and configured.
Filesystem
Add another new “native” item. For Belong to group, select the group you added for Pervasive PSQL.
For Type, select “Filesystem” and delete the parameter “fstype,” which is not required. Add a new parameter and select “device” for Name. For Value, specify the device name of the shared storage, a colon, and the share mount location.
Add another new parameter and select “directory” for Name. For Value, specify the directory to use with the NFS mount.
Psql (OCF resource agent)
Add another new “native” item. For Belong to group, select the group you added for Pervasive PSQL. For Type, click on “psql” with a Description of “PSQL OCF Resource Agent.” No additional parameters are required for the parameter.
Create the Subdirectories on the Mounted Shared Storage
Now that you have added the Filesystem resource, the mount exists between the cluster server and the shared storage. On one of the cluster nodes, log in as user psql. Under the shared storage mount, create a directory named “log” and another named “etc.”
For example, if the mount directory is “/usr/local/psql/shared,” you would add directories /usr/local/psql/shared/log and /usr/local/psql/shared/etc.
Configure the Cluster Server in PCC
On each of the cluster nodes, you need to configure the cluster server with Pervasive PSQL Control Center (PCC).
Place all cluster nodes into standby mode except for the one from which you will run PCC. As user psql, start PCC on the one active node or from a client that can access the active node.
In Pervasive PSQL Explorer, add a new server and specify the name (or IP address) of the cluster.
Access the properties for the server you just added. If prompted to log in, log in as user “admin.” Leave the password blank. Access the Directories Properties. For Transaction Log Directory, specify the directory that you created for the “log” location. For DBNames Configuration Location, specify the directory that you created for the “etc” location. See Create the Subdirectories on the Mounted Shared Storage.
Use PCC to add a new server and set its properties from each of the other cluster nodes. Place all nodes into standby mode except for the one from which you run PCC.
Create the Database on the Shared Storage
From the operating system on one of the cluster nodes, log on as user psql and create the directory under the file system share where you want the database to reside. (If you create the directory as user root, ensure that user psql has read, write, and execute authority on the directory.)
Place all cluster nodes into standby mode except for the one from which you will run PCC.
As user psql, start PCC on the one active node or from a client that can access the active node. Create a new database for the server you added in Configure the Cluster Server in PCC. For Location, specify the directory you created where you want the database to reside. Specify the other database options as desired.
For the new database, create tables as desired.
Verify Access to the Database from each Node
Each cluster node must be able to access the Pervasive PSQL database on the shared storage. Place the cluster node from which you created the database into standby mode. This is the node running the “psql” resource (the database engine).
Fail over to the next node in the cluster. Verify that the next node receives control of running the “psql” resource. Repeat the standby, fail over and verification process for each node in the cluster until you return to the node from which you began.
Managing Pervasive PSQL in a Cluster Environment
After you install Pervasive PSQL in a failover cluster environment, you can manage Pervasive PSQL as a resource. The following items discuss common management topics.
•
Pervasive PSQL Licensing and Node Maintenance
•
Pervasive PSQL Failure Behavior
•
Restoring Pervasive PSQL on a Failed Node
•
Stopping or Restarting the Pervasive PSQL Transactional Service
•
Pervasive PSQL Configuration Changes
•
Cluster Environment with a Proxy Server
•
Software Upgrades
Pervasive PSQL Licensing and Node Maintenance
The normal procedure pertaining to Pervasive PSQL licensing and machine maintenance also applies to the nodes in a failover cluster environment. Deauthorize the Pervasive PSQL key before you modify the configuration of the physical or virtual machine on which the database engine is installed. Reauthorize the key after the changes are complete.
See To Deauthorize a Key and To Authorize a Key in Pervasive PSQL User's Guide.
Pervasive PSQL Failure Behavior
If a cluster node fails, a Pervasive PSQL client does not automatically reconnect to the Pervasive PSQL engine on the surviving node. Your application must reconnect the client to the Pervasive PSQL database or you must restart the application. This applies even if Enable Auto Reconnect is turned on for the database engine.
If transaction durability is turned off and a failure occurs before a transaction completes, the transaction is automatically rolled back to its state before the transaction began. That is, to the last completed check point. The rollback occurs when the active server requests access to the data file.
If transaction durability was turned on, completed changes can be recovered that occurred between the time of the cluster node failure and the last check point. Transaction durability must be configured the same way on all nodes and the transaction log located on the shared storage. Transactions that had not completed at the time of the cluster failure, however, are lost even if transaction durability was in effect.
Restoring Pervasive PSQL on a Failed Node
Your failover cluster may have a primary node from which you prefer to run. If the primary node fails, you would want to restore it as quickly as possible rather than using secondary nodes. For such a situation you may want to consider Pervasive PSQL Insurance to help establish a primary node with a temporary license for Pervasive PSQL.
Pervasive PSQL Insurance gives you a way to get back online right away to keep your business going until you can restore the original Pervasive PSQL license on the primary node. Pervasive PSQL Insurance provides a 7-Day temporary license that allows 3 separate uses and is available for Windows and Linux 32-bit or 64-bit environments. See www.pervasivedb.com for details.
Stopping or Restarting the Pervasive PSQL Transactional Service
A cluster failover occurs from the active node if you manually stop the Pervasive PSQL transactional service through the operating system. If you are performing service node maintenance and want to avoid such a failover, stop the Pervasive PSQL transactional service through the cluster utilities.
Pervasive PSQL Configuration Changes
Configuration Changes that Require Database Engine Restart
Some configuration changes require that you restart the database engine. For such changes, perform the changes on an inactive mode. Otherwise, the restart could cause a failover to occur. See Configuration Reference chapter.
Adding a User Count Increase (UCI ) Key
You can add an increase key to Pervasive PSQL at any time on either the active node or an inactive node. Adding a UCI key does not require an engine restart and takes effect immediately. See also Increase User Count, Session Count, or Data In Use in Pervasive PSQL User's Guide.
Cluster Environment with a Proxy Server
If your cluster environment also incorporates a proxy server, see Authorization Access Through A Proxy Server in Pervasive PSQL User's Guide.
Software Upgrades
At some point, you may need to upgrade Pervasive PSQL or the failover cluster software. For Pervasive PSQL, ensure that you upgrade the database engine on an inactive node. See also the release notes for the upgrade version. For the failover cluster software, refer to the recommended procedure from the software vendor.