How to use JDBC_PING to discover cluster nodes

This article is a quick walkthough the JDBC_PING JGroups protocol which you can use for initial discovery of cluster nodes in WildFly application server.

JDBC Ping overview

This discovery protocol uses JDBC connection to a shared database. You can define connection options both as configuration properties, or with the JNDI name of a DataSource.

By default, the following DDL will run when you use the protocol without extra parameters:

own_addr varchar(200) NOT NULL,  
cluster_name varchar(200) NOT NULL,  
ping_data varbinary(5000) DEFAULT NULL,  
PRIMARY KEY (own_addr, cluster_name)  

However, you can customize both the schema and the used SQL statements. As you can see, the recommended schema uses a single table, with two String columns being used primary key (local address, cluster name) and a third column to store the serialized form of the objects needed by JGroups.

The default table will be created at first connection.

Configuring the Protocol

In order to configure JDBC Ping using the default Datasource, you need to replace the MPING socket-protocol of your TCP connection with JDBC_PING:

<stack name="tcp">
    <transport type="TCP" socket-binding="jgroups-tcp"/>
    <!-- <socket-protocol type="MPING" socket-binding="jgroups-mping"/> -->
    <jdbc-protocol type="JDBC_PING" data-source="ExampleDS"/>

    <protocol type="MERGE3"/>
    <socket-protocol type="FD_SOCK" socket-binding="jgroups-tcp-fd"/>
    <protocol type="FD_ALL"/>
    <protocol type="VERIFY_SUSPECT"/>
    <protocol type="pbcast.NAKACK2"/>
    <protocol type="UNICAST3"/>
    <protocol type="pbcast.STABLE"/>
    <protocol type="pbcast.GMS"/>
    <protocol type="UFC"/>
    <protocol type="MFC"/>
    <protocol type="FRAG3"/>

Then, set TCP as default stack for your cluster channel:

<subsystem xmlns="urn:jboss:domain:jgroups:9.0">
     <channels default="ee">
         <channel name="ee" stack="tcp" cluster="ejb"/>

Connection Properties

You can check the available properties you can apply on the protocol on the source class:

This table summarizes the available properties:

connection_urlThe JDBC connection URL
connection_usernameThe JDBC connection username
connection_passwordThe JDBC connection password
initialize_sqlIf not empty, a Table will be created at startup
insert_single_sqlSQL used to insert a new row. Customizable, but keep the order of parameters and pick compatible types
delete_single_sqlSQL used to delete a row. Customizable, but keep the order of parameters and pick compatible types
clear_sqlSQL to clear the table
select_all_pingdata_sqlSQL used to fetch all node’s PingData. Customizable, but keep the order of parameters and pick compatible types
contains_sqlFinds a given entry by its address and cluster name, used to implement a contains.
datasource_jndi_nameTo use a DataSource registered in JNDI, specify the JNDI name here.