6.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 6.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

    In this state, the connector will continue as normal allowing existing connections to continue until the delayBeforeOfflineIfNoManager is reached. New connections are paused.

  • Offline State

    When the connector enters the offline state, the connector terminates all connections, and blocks all new connections.

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:

6.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 6.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.

6.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.

6.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.

6.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.