7.7. Connector Operational States

During operation, the connector goes through a number of different states and state transition during specific events. The default mode is the Online state, where the connector operates as configured.

During operation, all configured connectors within the dataservice remain in contact with the manager, see Section 7.8, “Connector/Manager Interface” for more information.

Supported states by the Connector are:

  • Online State

    The Connector operates as configured, redirecting connections to the corresponding Primary or Replica.

  • On Hold State

    The connector will enter this state as soon as the manager connection is lost if delayBeforeOnHoldIfNoManager=0 (the default), or after the specified delay.

    In this state, new connection requests are paused (client applications trying to connect will see what appears to be a “hang”) while existing connections will continue as normal until the Offline state is reached

    This property can be set using the tpm flag connector-delay-before-onhold.

  • Offline State

    The connector enters the offline state delayBeforeOfflineIfNoManagerseconds after the connection to the manager is lost.

    This property can be set using the tpm flag connector-delay-before-offline. The default value is 30, which means going to the offline state after 30 seconds.

    When entering the offline state, the connector terminates all existing connections, and rejects all new connections requests (client applications will receive an error when trying to connect).

The state of a connector can be modified by using the router command within cctrl. This can be used to manually place the connector into online or offline states. For example, to put a connector online the full host and process ID must be used:

cctrl> router connector@host1[22476] online

Wildcards can be used to enable or disable all the hosts. For example, to place all connectors online:

cctrl> router * online

While in AUTOMATIC policy mode, connectors will automatically be placed online if they have entered the OFFLINE state automatically as part of a failover. If the routers have been manually placed offline, routers must be manually placed back online.

While in the ONLINE state, the connector behaves and alters it's operation according to the following states and events:

7.7.1. Connections During Automatic Failure/Failover

When an automatic failure or failover is identified, for example when the dataservice is in the AUTOMATIC policy mode, and the Primary is automatically switched to a new host, the following sequence occurs:

  1. All connections to the failed datasource are terminated immediately. This ensures that running transactions or operations are terminated by the database server.

  2. Connections to clients will remain open and be reconnected transparently, providing they are not within a transaction. For more information, see Section 7.7.3, “Connections During Connection Failures”.

    Only if there is a problem with the connection or an I/O error will the problem be forwarded to the clients.

As with a direct database connection, the client application should handle the reconnection to the Connector, which will be then be redirected to the corresponding Primary or Replica datasource.

7.7.2. Connections During Manual Switch

When a manual switch operation has been initiated, the Connector follows this sequence:

  1. New connection attempts to the old datasource are suspended; this gives the impression of a 'hung' connection that must be managed by the client application through the normal timeout procedure.

  2. Existing connections to the datasource are terminated under two conditions:

    • As the connections are naturally closed.

    • Open connections are forcibly disconnected after the timeout specified by the waitForDisconnectTimeout parameter. By default, this is 5 seconds. To eliminate waiting, the waitForDisconnect parameter can be set to false.

    Once either condition has been met, any remaining connections are closed.

  3. New connections (including re-connections) are enabled, and will be routed to the appropriate Primary or Replica.

Client applications should be configured to reconnect to the connector with an interval larger than the disconnect timeout within the connector. This will ensure that the client reconnects when the connector is able to accept the new connection.

7.7.3. Connections During Connection Failures

In the event of a connection failure between a running datasource and the connector, and providing the connection is deemed idle, the connector will transparently reconnect to the failed datasource when the following conditions have been met:

  • The connection is not executing any requests.

  • The connection is not in the middle of a transaction.

  • No temporary tables have been created during this connection.

If all three conditions are met, a new connection will be opened. Connections between the client and the connector will be unaffected.

This option is enabled by default. To disable transparent reconnections, use --connector-autoreconnect=false= option to tpm during installation.

7.7.4. Other Errors

The Connector attempts to emulate and effectively represent any errors raised by the datasource to which the connector has routed the client connection.

  • The Tungsten Connector uses the Tanuki Java Service Wrapper to manage the running process. If the Connector process fails, the service wrapper will automatically restart it. If the connector fails repeatedly, attempts to restart will be stopped. The status and reason for these failures can be tracked by examining the connector.log log file.

    Connected client applications will be terminated, but should be able to reconnect once the Connector has been restarted.

  • Database errors, including invalid statements, operations, or security failures, will be represented identically by the Connector to any clients.