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 "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 delayBeforeOfflineIfNoManager seconds 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 its operation according to the following states and events:

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 connector-states-transitions-failure.

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.

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.

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 during installation.

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.

Connector Keepalive

Connections to MySQL servers can automatically time-out according to the wait_timeout variable configured within the MySQL server.

To prevent these connections being automatically closed, the connector can be configured to keep the connection alive by submitting a simple SELECT statement (actually SELECT 'KEEP_ALIVE') periodically to ensure that the MySQL timeout is not reached and the connection closed.

Two parameters configure the keepalive functionality:

• property=connection.keepAlive.interval

  The interval used to check for idle connections. If set to a value of 0, the keep alive check is disabled. Any value greater than zero is the interval check period in seconds.

• connector-keepalive-timeout

  The keep-alive statement is submitted if the time since the last activity reaches this timeout value.

The default setting for both parameters is autodetect.

When set to autodetect default, the values are automatically calculated by the connector computing suitable values based on the wait_timeout value configured in the MySQL server.

connector-keepalive-timeout = (int) Math.floor(wait_timeout * 0.10);
connection.keepAlive.timeout = (int) Math.floor(wait_timeout * 0.7);

These calculations cannot be modified, but the properties can be set explicitly by adding the following to your /etc/tungsten/tungsten.ini:

connector-keepalive-timeour=10000
property=connection.keepAlive.interval=30

warning

Please note that Connector Keepalive is not compatible with Bridge mode.

In Bridge mode, the client session is directly connected to the MySQL server at the TCP level, literally forwarding the client's packet to the server. This means that closing connections is the responsibility of the MySQL server based on the configured wait_timeout value, not the Connector.

Connector Change User as Ping

When using PHP with connection pooling enabled, the change user command is used to ping a connection within a pool to ensure that the connection is open and active before using it. The Tungsten Connector uses JDBC to connect to MySQL, which does not support the change user protocol option.

To provide an alternative to this for PHP applications communication through the connector, the connector can be configured to respond to the COM_CHANGE_USER command from a client application. Rather than performing the change user operation, instead the connector will respond to the client with an acknowledgement, emulating the ping operation.

This operation is disabled by default, and must be explicitly enabled. This can be achieved by setting the correct property value, property=treat.com.change.user.as.ping=true within your /etc/tungsten/tungsten.ini