7.12.3. Advanced Listeners


This feature is available from v7.0.3.

The idea behind the Connector Advanced Listeners feature is to allow easy definition of one or more listening addresses and ports via a single JSON file. A binding port/address pair can be mapped to a given set of options that will provide a “way” to choose data sources to connect to, through existing connector configuration elements.

The configuration file is written in JSON format in a file located by default in tungsten-connector/conf/listeners.json.


If present, this file will be loaded and will override the main configuration, therefore when defining configuration(s) through listeners, other configurations, for example, --connector-readonly-port will be ignored.


To reload the configuration after changes to the JSON file, the command connector restart must be used, this will cause any existing connections through the connector to be terminated, so care must be taken if implementing this on an existing production system with active clients.

Below is example content defining two Connector ports, one for reads in a local cluster and one for writes in a remote site:

        "description": "R/W port",
        "dataService": "global",
        "bridgeMode": true,
        "qos": "RW_STRICT"
        "description": "R/O port",
        "dataService": "global",
        "bridgeMode": true,
        "qos": "RO_RELAXED",
        "affinity": "west"
        "description": "SmartScale port",
        "dataService": "global",
        "smartScale": true,
        "sessionId": "CONNECTION"

Field Descriptions

  • listenAddress (string) : Can be used to restrict connections to a single address. For example, to listen only to local network connections, the local address “” (or whichever appropriate) will be specified. Default is “”, which is all configured network addresses.

  • listenPort (integer) : The Connector port on which to listen for incoming connections. Default is port 3306.

  • serverTargetPort (integer) : The MySQL server port to connect to, typically 13306 or any port configured in the target MySQL server. This setting overrides the port from the current cluster definition and should be used with care.

  • bridgeMode (boolean) : If set to true, the connection to the data source will be made in Bridge mode using the specified QoS to select primary or replica. When false or unspecified, connection will be in Proxy mode

  • QoS (predefined string) : Quality of Service, either RW_STRICT for read/write connections (routes to a primary node), or RO_RELAXED for read-only connections (routes to a replica). Defaults to RW_STRICT

  • smartScale (boolean) : Enables the smart scale feature to read from up-to-date replicas (See Section 7.4.10, “Smartscale Routing” for more information). Setting sessionID will control the desired level of consistency. Defaults to false

  • sessionId (String) : Relevant only when smartScale is ON, specifies the session ID to use (See Section 7.4.10, “Smartscale Routing” for more information). Values can be CONNECTION, USER, DATABASE, or a free string. Defaults to DATABASE

  • dataService (String) : Sets the data service to connect to. Typically, in multi-site environments, the global, composite data service will be given. For specific needs, a local data service name can be specified so that connections will never cross the site. Affinity (see below) can also be specified to prefer one site or one host over the other

  • affinity (String) : Data service or data source name to select preferably.

  • maxAppliedLatency (Integer) : Maximum replica latency in seconds when selecting a node for reading.