mysqlnd_ms_set_user_pick_serverSets a callback for user-defined read/write splitting
&reftitle.description;
boolmysqlnd_ms_set_user_pick_serverstringfunction
Sets a callback for user-defined read/write splitting. The plugin will
call the callback only if pick[]=user is the default
rule for server picking in the relevant section of the plugins configuration
file.
The plugins built-in read/write query split mechanism decisions can be
overwritten in two ways. The easiest way is to prepend the query string
with the SQL hints MYSQLND_MS_MASTER_SWITCH,
MYSQLND_MS_SLAVE_SWITCH or
MYSQLND_MS_LAST_USED_SWITCH. Using SQL hints one can
control, for example, whether a query shall be send to the MySQL replication
master server or one of the slave servers. By help of SQL hints it is
not possible to pick a certain slave server for query execution.
Full control on server selection can be gained using a callback function.
Use of a callback is recommended to expert users only because the callback
has to cover all cases otherwise handled by the plugin.
The plugin will invoke the callback function for selecting a server from the
lists of configured master and slave servers. The callback function
inspects the query to run and picks a server for query execution by returning
the hosts URI, as found in the master and slave list.
If the lazy connections are enabled and the callback choses a slave server for
which no connection has been established so far and establishing the connection
to the slave fails, the plugin will return an error upon the next action
on the failed connection, for example, when running a query. It is the
responsibility of the application developer to handle the error. For example,
the application can re-run the query to trigger a new server selection and
callback invocation. If so, the callback must make sure to select
a different slave, or check slave availability, before returning to
the plugin to prevent an endless loop.
&reftitle.parameters;
function
The function to be called. Class methods may also be invoked
statically using this function by passing
array($classname, $methodname) to this parameter.
Additionally class methods of an object instance may be called by passing
array($objectinstance, $methodname) to this parameter.
&reftitle.returnvalues;
Host to run the query on. The host URI is to be taken from the
master and slave connection lists passed to the callback function.
If callback returns a value neither found in the master nor in the slave
connection lists the plugin will fallback to the second pick method configured
via the pick[] setting in the plugin configuration file.
If not second pick method is given, the plugin falls back to the build-in
default pick method for server selection.
&reftitle.notes;
mysqlnd_ms_set_user_pick_server is available
with PECL mysqlnd_ms < 1.1.0. It has been replaced by the
user filter. Please, check the
Change History
for upgrade notes.
&reftitle.examples;
<function>mysqlnd_ms_set_user_pick_server</function> example
query("SELECT 1 FROM DUAL")))
printf("[%d] %s\n", $mysqli->errno, $mysqli->error);
else
$res->close();
if (!($res = $mysqli->query("SELECT 2 FROM DUAL")))
printf("[%d] %s\n", $mysqli->errno, $mysqli->error);
else
$res->close();
if (!($res = $mysqli->query("SELECT * FROM table_on_slave_a_only")))
printf("[%d] %s\n", $mysqli->errno, $mysqli->error);
else
$res->close();
$mysqli->close();
?>
]]>
&example.outputs;
&reftitle.seealso;
mysqlnd_ms_query_is_select
Filter concept
user filter