MultiInstanceConnecting.md

Main page

Connecting to multiple Tarantool instances

This section shows examples of how to connect to multiple Cartridge routers.
We recommend to use load balancer in production applications rather than leaving this task to the connector.

Warning
In the case of using multiple instances of TarantoolClient we strongly recommend to apply a shuffle function to the list of addresses. By default, TarantoolClient uses the round-robin approach for selecting the next available connection to distribute the load between Tarantool servers. When several instances of TarantoolClient are used simultaneously, with the default connection selection strategy and without shuffling of the server addresses the first request from every instance will be sent to the same server.

Note
You do not have to worry about shuffling addresses if you are using a single TarantoolClient connected to multiple instances, or if you are using a custom connection selection strategy that takes into account the problem of simultaneous requests.

Setting addresses manually

Example of TarantoolClient set up with connecting to multiple routers

cartridge-java/src/test/java/io/tarantool/driver/integration/ReconnectIT.java

Lines 348 to 359 in d13e869

	TarantoolClientFactory.createClient()
	// You can connect to multiple routers
	// Do not forget to shuffle your addresses if you are using multiple clients
	.withAddresses(getShuffledTarantoolServerAddresses())
	// For connecting to a Cartridge application,
	// use the value of cluster_cookie parameter in the init.lua file
	.withCredentials(USER_NAME, PASSWORD)
	// Number of connections per Tarantool instance
	.withConnections(1)
	// Specify using the default CRUD proxy operations mapping configuration
	.withProxyMethodMapping()
	.build();

cartridge-java/src/test/java/io/tarantool/driver/integration/ReconnectIT.java

Lines 373 to 382 in d13e869

	private List<TarantoolServerAddress> getShuffledTarantoolServerAddresses() {
	List<TarantoolServerAddress> addresses = Arrays.asList(
	new TarantoolServerAddress(container.getRouterHost(), container.getMappedPort(3301)),
	new TarantoolServerAddress(container.getRouterHost(), container.getMappedPort(3302)),
	new TarantoolServerAddress(container.getRouterHost(), container.getMappedPort(3303))
	);
	Collections.shuffle(addresses);
	return addresses;
	}

Setting addresses with address provider

Example of TarantoolClient set up with address provider
You may use the provided code as a reference for your own implementation

cartridge-java/src/test/java/io/tarantool/driver/integration/ProxyTarantoolClientWithAddressProviderExampleIT.java

Lines 81 to 89 in d13e869

	client = TarantoolClientFactory.createClient()
	// You don't have to set the routers addresses yourself address provider will do it for you
	// Do not forget to shuffle your addresses if you are using multiple clients
	.withAddressProvider(getClusterShuffledAddressProvider())
	// For connecting to a Cartridge application, use the value of cluster_cookie parameter in the init.lua file
	.withCredentials(credentials)
	// Specify using the default CRUD proxy operations mapping configuration
	.withProxyMethodMapping()
	.build();

Example of TarantoolClusterAddressProvider setup

cartridge-java/src/test/java/io/tarantool/driver/integration/ProxyTarantoolClientWithAddressProviderExampleIT.java

Lines 44 to 74 in d13e869

	private static TarantoolClusterAddressProvider getClusterShuffledAddressProvider() {
	TarantoolClientConfig config = TarantoolClientConfig.builder()
	.withCredentials(credentials)
	.build();
	BinaryClusterDiscoveryEndpoint endpoint = new BinaryClusterDiscoveryEndpoint.Builder()
	// Config for connecting to instance with entry function
	.withClientConfig(config)
	// Name of a function that returns a pool of addresses to connect to
	.withEntryFunction("get_routers")
	// Setting first router URI as entry point
	.withEndpointProvider(() -> {
	List<TarantoolServerAddress> addresses = Collections.singletonList(
	new TarantoolServerAddress(container.getRouterHost(), container.getRouterPort()));
	// Shuffling addresses in address provider
	Collections.shuffle(addresses);
	return addresses;
	})
	.build();
	TarantoolClusterDiscoveryConfig clusterDiscoveryConfig = new TarantoolClusterDiscoveryConfig.Builder()
	.withEndpoint(endpoint)
	.withDelay(1)
	.build();
	// TestWrappedClusterAddressProvider changes ports provided by address providers to docker mapped ports
	// You need to use TestWrappedClusterAddressProvider only if you run Tarantool in TestContainers
	return new TestWrappedClusterAddressProvider(
	new BinaryDiscoveryClusterAddressProvider(clusterDiscoveryConfig),
	container);
	}

Do not forget to set tarantool function witch will return addresses
The function must be global, so that it can be called from the connector

cartridge-java/src/test/resources/cartridge/app/roles/custom.lua

Lines 3 to 30 in 09ec708

	function get_routers()
	local function table_contains(table, element)
	for _, value in pairs(table) do
	if value == element then
	return true
	end
	end
	return false
	end
	local servers, err = cartridge.admin_get_servers()
	local routers = {}
	for _, server in pairs(servers) do
	if server.replicaset ~= nil then
	if table_contains(server.replicaset.roles, 'app.roles.custom') then
	routers[server.uuid] = {
	status = server.status,
	uuid = server.uuid,
	uri = server.uri,
	priority = server.priority
	}
	end
	end
	end
	return routers
	end