Create a SQLFire Cluster

In this procedure you set up and start a cluster of two SQLFire servers.

  1. Begin by opening a command prompt or terminal window on the computer or VM where you installed SQLFire.
  2. Move to the directory in which you installed the SQLFire software. This tutorial uses the example directory ~/vFabric_SQLFire_10x, but you should substitute the actual path to your installation. For example:
    cd ~/vFabric_SQLFire_103
  3. The initial SQLFire cluster in this tutorial contains two standalone SQLFire server members. Create a new directory for each server:
    mkdir server1
    mkdir server2
    Each server will use its local directory to write log files, backup disk store files, a datadictionary directory for persisting data, and a single status file, .sqlfserver.ser.
  4. To manage client connections to the available SQLFire server members, the cluster in this tutorial uses a SQLFire locator member. Create a new directory for the locator member:
    mkdir locator
    A locator maintains a list of available servers in the cluster, and updates that list as servers join and leave the cluster. Locators also load balance client connections across all available servers.
  5. To start or stop a SQLFire locator or a SQLFire server, you use the sqlf script (for Linux platforms) or sqlf.bat script (for Windows platforms). In either case, you must first ensure that the path to the SQLFire bin directory is part of your PATH environment variable. For example, on a Linux platform enter:
    export PATH=$PATH:~/vFabric_SQLFire_10x/bin
    On a Windows platform enter:
    set Path=%Path%;c:\vFabric_SQLFire_10x\bin
  6. When you start a SQLFire distributed system, always begin by starting the locator member. Use the sqlf locator command to start the locator in the specified directory:
    sqlf locator start -dir=locator -peer-discovery-address=ip_address -peer-discovery-port=10101 \
                       -client-bind-address=ip_address -client-port=1527 &
    Note: In this step and in all subsequent steps, replace ip_address with the IP address of your local system.

    The -peer-discovery-address and -peer-discovery-port combination defines a unique connection that all members of this SQLFire distributed system use for communicating with one another.

    Note: Always use a unique -peer-discovery-port number to avoid joining a cluster that is already running on your network. If other people might be evaluating SQLFire on your network, choose a port number other than 10101.

    The -client-bind-address and -client-port combination defines the connection that client applications use to connect to this locator. In this tutorial, all SQLFire members run on the local computer's IP address and use different port numbers to define unique connections.

    You can verify the peer and client connections in the locator startup messages, which are similar to:
    Starting SQLFire Locator using peer discovery on: ip_address[10101]
    Starting network server for SQLFire Locator at address localhost/[1527]
    SQLFire Locator pid: 41149 status: running
    Note: By starting the locator member first, the locator can manage cluster membership from the start as new servers join and leave the distributed system. The locator member should also be the last process that you shut down when you want to stop a SQLFire distributed system.
    Note: As an alternative, SQLFire members can discover each other using multicast messaging. However, important SQLFire features such as WAN replication and user authentication require that a SQLFire system use locators rather than multicast for discovery. See Configuring Discovery Mechanisms.
  7. Now use the sqlf server command to start both SQLFire server members and join them to the distributed system:
    sqlf server start -dir=server1 -locators=ip_address[10101] -client-bind-address=ip_address -client-port=1528 &
    sqlf server start -dir=server2 -locators=ip_address[10101] -client-bind-address=ip_address -client-port=1529 &

    In each command, the -locators option defines the peer discovery address to use for joining the SQLFire distributed system. (Production deployments generally use multiple locator members, in which case you would specify a comma-separated list of locator host[port] connections when starting a server.)

    Again, the combination of -client-bind-address and -client-port indicates that each server will listen for thin clients on a unique connection (ip_address:1528 and ip_address:1529, respectively). However, in this distributed system all clients will connect using the locator instead of making direct connections to servers.

    Note: Always start SQLFire servers in the background (using "&"). In a working system, a server may need to wait for other cluster members to become available.
  8. Both SQLFire servers start in the background and output messages similar to:

    Starting SQLFire Server using locators for peer discovery: ip_address[10101]
    Starting network server for SQLFire Server at address /ip_address[1528]
    SQLFire Server pid: 41502 status: running
      Distributed system now has 2 members.
      Other members: localhost(41149:locator)<v0>:32977/50114
    Logs generated in /Users/yozie/vFabric_SQLFire_10x/server1/sqlfserver.log
    Starting SQLFire Server using locators for peer discovery: ip_address[10101]
    Starting network server for SQLFire Server at address /ip_address[1529]
    SQLFire Server pid: 41533 status: running
      Distributed system now has 3 members.
      Other members: localhost(41149:locator)<v0>:32977/50114,<v1>:49915/50462
    Logs generated in /Users/yozie/vFabric_SQLFire_10x/server2/sqlfserver.log

    Startup messages show the cluster membership details.

    By default, new SQLFire servers host data as data stores, and are automatically added to a default server group. You can optionally specify server group membership at startup using the server-groups boot property.