Retrieve global information about a MaxScale instance. This includes various
file locations, configuration options and version information.
Response
Status: 200 OK
Update MaxScale parameters
Update MaxScale parameters. The request body must define updated values for thedata.attributes.parameters object. The parameters that can be modified are
listed in the /v1/maxscale/modules/maxscale endpoint and have the modifiable
value set to true.
Response
Parameters modified:
Status: 204 No Content
Invalid JSON body:
Status: 403 Forbidden
Get thread information
Get the information and statistics of a particular thread. The :id in
the URI must map to a valid thread number between 0 and the configured
value of threads.
Response
Status: 200 OK
Get information for all threads
Get the information for all threads. Returns a collection of threads resources.
Response
Status: 200 OK
Get logging information
Get information about the current state of logging, enabled log files and the
location where the log files are stored.
Note: The parameters in this endpoint are a subset of the parameters in the/v1/maxscale endpoint. Because of this, the parameters in this endpoint are
deprecated as of MaxScale 6.0.
Note: In MaxScale 2.5 the log_throttling and ms_timestamp parameters
were incorrectly named as throttling and highprecision. In MaxScale 6,
the parameter names are now correct which means the parameters declared here
aren't fully backwards compatible.
Response
Status: 200 OK
Get log data
Get the contents of the MaxScale logs. This endpoint was added in MaxScale 6.
To navigate the log, use the prev link to move backwards to older log
entries. The latest log entries can be read with the last link.
The entries are sorted in ascending order by the time they were logged. This
means that with the default parameters, the latest logged event is the last
element in the returned array.
Parameters
This endpoint supports the following parameters:
page[size]
Set number of rows of data to read. By default, 50 rows of data are read
from the log.
page[cursor]
Set position from where the log data is retrieved. The default position to
retrieve the log data is the end of the log.
This value should not be modified by the user and the values returned in thelinks object should be used instead. This way the navigation will provide
a consistent view of the log that does not overlap.
Optionally, the id values in the returned data can be used as the values
for this parameter to read data from a known point in the file.
priority
Include messages only from these log levels. The default is to include all
messages.
The value given should be a comma-separated list of log priorities. The
priorities are alert, error, warning, notice, info anddebug. Note that the debug log level is only used in debug builds of
MaxScale.
Response
Status: 200 OK
Stream log data
Stream the contents of the MaxScale logs. This endpoint was added in MaxScale 6.
This endpoint opens a WebSocket
connection and streams the contents of the log to it. Each WebSocket message
will contain the JSON representation of the log message. The JSON is formatted
in the same way as the values in the log array of the /v1/maxscale/logs/data
endpoint:
Limitations
If the client writes any data to the open socket, it will be treated as
an error and the stream is closed.
The WebSocket ping and close commands are not yet supported and will be
treated as errors.
When maxlog is used as source of log data, any log messages logged after log
rotation will not be sent if the file was moved or truncated. To fetch new
events after log rotation, reopen the WebSocket connection.
Parameters
This endpoint supports the following parameters:
page[cursor]
Set position from where the log data is retrieved. The default position to
retrieve the log data is the end of the log.
To stream data from a known point, first read the data via the/v1/maxscale/logs/data endpoint and then use the id value of the newest
log message (i.e. the first value in the log array) to start the stream.
priority
Include messages only from these log levels. The default is to include all
messages.
The value given should be a comma-separated list of log priorities. The
priorities are alert, error, warning, notice, info anddebug. Note that the debug log level is only used in debug builds of
MaxScale.
Response
Upgrade started:
Status: 101 Switching Protocols
Client didn't request a WebSocket upgrade:
Status: 426 Upgrade Required
Update logging parameters
Note: The modification of logging parameters via this endpoint has
deprecated in MaxScale 6.0. The parameters should be modified with the/v1/maxscale endpoint instead.
Any PATCH requests done to this endpoint will be redirected to the/v1/maxscale endpoint. Due to the mispelling of the ms_timestamp andlog_throttling parameters, this is not fully backwards compatible.
Update logging parameters. The request body must define updated values for thedata.attributes.parameters object. All logging parameters can be altered at runtime.
Response
Parameters modified:
Status: 204 No Content
Invalid JSON body:
Status: 403 Forbidden
Flush and rotate log files
Flushes any pending messages to disk and reopens the log files. The body of the
message is ignored.
Response
Status: 204 No Content
Get task schedule
Retrieve all pending tasks that are queued for execution.
Response
Status: 200 OK
Get a loaded module
Retrieve information about a loaded module. The :name must be the name of a
valid loaded module or either maxscale or servers.
The maxscale module will display the global configuration options
(i.e. everything under the [maxscale] section) as a module.
The servers module displays the server object type and the configuration
parameters it accepts as a module.
Any parameter with the modifiable value set to true can be modified
at runtime using a PATCH command on the corresponding object endpoint.
Response
Status: 200 OK
Get all loaded modules
Retrieve information about all loaded modules.
This endpoint supports the load=all parameter. When defined, all modules
located in the MaxScale module directory (libdir) will be loaded. This allows
one to see the parameters of a module before the object is created.
Response
Status: 200 OK
Call a module command
For read-only commands:
For commands that can modify data:
Modules can expose commands that can be called via the REST API. The module
resource lists all commands in the data.attributes.commands list. Each value
is a command sub-resource identified by its id field and the HTTP method the
command uses is defined by the attributes.method field.
The :module in the URI must be a valid name of a loaded module and :command
must be a valid command identifier that is exposed by that module. All
parameters to the module commands are passed as HTTP request parameters.
Here is an example POST requests to the dbfwfilter module command reload with
two parameters, the name of the filter instance and the path to a file:
Response
Command with output:
Status: 200 OK
The contents of the meta field will contain the output of the module
command. This output depends on the command that is being executed. It can
contain any valid JSON value.
Command with no output:
Status: 204 No Content
Classify a statement
Classify provided statement and return the result.
{
"id": "572",
"message": "MaxScale started with 8 worker threads, each with a stack size of 8388608 bytes.",
"priority": "notice",
"timestamp": "2020-09-25 10:01:29"
}
PATCH /v1/maxscale/logs
POST /v1/maxscale/logs/flush
GET /v1/maxscale/tasks
{
"links": {
"self": "http://localhost:8989/v1/maxscale/tasks/"
},
"data": [] // No tasks active
}
GET /v1/maxscale/modules/:name
{
"data": {
"attributes": {
"api": "router",
"commands": [],
"description": "A Read/Write splitting router for enhancement read scalability",
"maturity": "GA",
"module_type": "Router",
"parameters": [
{
"default_value": "false",
"description": "Causal reads mode",
"enum_values": [
"false",
"off",
"0",
"true",
"on",
"1",
"none",
"local",
"global",
"fast"
],
"mandatory": false,
"modifiable": true,
"name": "causal_reads",
"type": "enum"
},
{
"default_value": "10000ms",
"description": "Timeout for the slave synchronization",
"mandatory": false,
"modifiable": true,
"name": "causal_reads_timeout",
"type": "duration",
"unit": "ms"
},
{
"default_value": false,
"description": "Retry failed writes outside of transactions",
"mandatory": false,
"modifiable": true,
"name": "delayed_retry",
"type": "bool"
},
{
"default_value": "10000ms",
"description": "Timeout for delayed_retry",
"mandatory": false,
"modifiable": true,
"name": "delayed_retry_timeout",
"type": "duration",
"unit": "ms"
},
{
"default_value": false,
"description": "Create connections only when needed",
"mandatory": false,
"modifiable": true,
"name": "lazy_connect",
"type": "bool"
},
{
"default_value": false,
"description": "Use master for reads",
"mandatory": false,
"modifiable": true,
"name": "master_accept_reads",
"type": "bool"
},
{
"default_value": "fail_instantly",
"description": "Master failure mode behavior",
"enum_values": [
"fail_instantly",
"fail_on_write",
"error_on_write"
],
"mandatory": false,
"modifiable": true,
"name": "master_failure_mode",
"type": "enum"
},
{
"default_value": false,
"description": "Reconnect to master",
"mandatory": false,
"modifiable": true,
"name": "master_reconnection",
"type": "bool"
},
{
"default_value": 255,
"description": "Maximum number of slave connections",
"mandatory": false,
"modifiable": true,
"name": "max_slave_connections",
"type": "count"
},
{
"default_value": "0ms",
"description": "Maximum allowed slave replication lag",
"mandatory": false,
"modifiable": true,
"name": "max_slave_replication_lag",
"type": "duration",
"unit": "ms"
},
{
"default_value": false,
"description": "Optimistically offload transactions to slaves",
"mandatory": false,
"modifiable": true,
"name": "optimistic_trx",
"type": "bool"
},
{
"default_value": true,
"description": "Automatically retry failed reads outside of transactions",
"mandatory": false,
"modifiable": true,
"name": "retry_failed_reads",
"type": "bool"
},
{
"default_value": false,
"description": "Reuse identical prepared statements inside the same connection",
"mandatory": false,
"modifiable": true,
"name": "reuse_prepared_statements",
"type": "bool"
},
{
"default_value": 255,
"description": "Starting number of slave connections",
"mandatory": false,
"modifiable": true,
"name": "slave_connections",
"type": "count"
},
{
"default_value": "LEAST_CURRENT_OPERATIONS",
"description": "Slave selection criteria",
"enum_values": [
"LEAST_GLOBAL_CONNECTIONS",
"LEAST_ROUTER_CONNECTIONS",
"LEAST_BEHIND_MASTER",
"LEAST_CURRENT_OPERATIONS",
"ADAPTIVE_ROUTING"
],
"mandatory": false,
"modifiable": true,
"name": "slave_selection_criteria",
"type": "enum"
},
{
"default_value": false,
"description": "Lock connection to master after multi-statement query",
"mandatory": false,
"modifiable": true,
"name": "strict_multi_stmt",
"type": "bool"
},
{
"default_value": false,
"description": "Lock connection to master after a stored procedure is executed",
"mandatory": false,
"modifiable": true,
"name": "strict_sp_calls",
"type": "bool"
},
{
"default_value": false,
"description": "Retry failed transactions",
"mandatory": false,
"modifiable": true,
"name": "transaction_replay",
"type": "bool"
},
{
"default_value": 5,
"description": "Maximum number of times to retry a transaction",
"mandatory": false,
"modifiable": true,
"name": "transaction_replay_attempts",
"type": "count"
},
{
"default_value": "full",
"description": "Type of checksum to calculate for results",
"enum_values": [
"full",
"result_only",
"no_insert_id"
],
"mandatory": false,
"modifiable": true,
"name": "transaction_replay_checksum",
"type": "enum"
},
{
"default_value": 1048576,
"description": "Maximum size of transaction to retry",
"mandatory": false,
"modifiable": true,
"name": "transaction_replay_max_size",
"type": "size"
},
{
"default_value": false,
"description": "Retry transaction on deadlock",
"mandatory": false,
"modifiable": true,
"name": "transaction_replay_retry_on_deadlock",
"type": "bool"
},
{
"default_value": false,
"description": "Retry transaction on checksum mismatch",
"mandatory": false,
"modifiable": true,
"name": "transaction_replay_retry_on_mismatch",
"type": "bool"
},
{
"default_value": "0ms",
"description": "Timeout for transaction replay",
"mandatory": false,
"modifiable": true,
"name": "transaction_replay_timeout",
"type": "duration",
"unit": "ms"
},
{
"default_value": "all",
"description": "Whether to route SQL variable modifications to all servers or only to the master",
"enum_values": [
"all",
"master"
],
"mandatory": false,
"modifiable": true,
"name": "use_sql_variables_in",
"type": "enum"
},
{
"default_value": false,
"description": "Retrieve users from all backend servers instead of only one",
"mandatory": false,
"modifiable": true,
"name": "auth_all_servers",
"type": "bool"
},
{
"default_value": "300000ms",
"description": "How ofted idle connections are pinged",
"mandatory": false,
"modifiable": true,
"name": "connection_keepalive",
"type": "duration",
"unit": "ms"
},
{
"default_value": "0ms",
"description": "Connection idle timeout",
"mandatory": false,
"modifiable": true,
"name": "connection_timeout",
"type": "duration",
"unit": "ms"
},
{
"default_value": false,
"description": "Disable session command history",
"mandatory": false,
"modifiable": true,
"name": "disable_sescmd_history",
"type": "bool"
},
{
"default_value": false,
"description": "Allow the root user to connect to this service",
"mandatory": false,
"modifiable": true,
"name": "enable_root_user",
"type": "bool"
},
{
"default_value": "-1ms",
"description": "Put connections into pool after session has been idle for this long",
"mandatory": false,
"modifiable": true,
"name": "idle_session_pool_time",
"type": "duration",
"unit": "ms"
},
{
"default_value": true,
"description": "Match localhost to wildcard host",
"mandatory": false,
"modifiable": true,
"name": "localhost_match_wildcard_host",
"type": "bool"
},
{
"default_value": true,
"description": "Log a warning when client authentication fails",
"mandatory": false,
"modifiable": true,
"name": "log_auth_warnings",
"type": "bool"
},
{
"default_value": false,
"description": "Log debug messages for this service (debug builds only)",
"mandatory": false,
"modifiable": true,
"name": "log_debug",
"type": "bool"
},
{
"default_value": false,
"description": "Log info messages for this service",
"mandatory": false,
"modifiable": true,
"name": "log_info",
"type": "bool"
},
{
"default_value": false,
"description": "Log notice messages for this service",
"mandatory": false,
"modifiable": true,
"name": "log_notice",
"type": "bool"
},
{
"default_value": false,
"description": "Log warning messages for this service",
"mandatory": false,
"modifiable": true,
"name": "log_warning",
"type": "bool"
},
{
"default_value": 0,
"description": "Maximum number of connections",
"mandatory": false,
"modifiable": true,
"name": "max_connections",
"type": "count"
},
{
"default_value": 50,
"description": "Session command history size",
"mandatory": false,
"modifiable": true,
"name": "max_sescmd_history",
"type": "count"
},
{
"default_value": "60000ms",
"description": "How long a session can wait for a connection to become available",
"mandatory": false,
"modifiable": true,
"name": "multiplex_timeout",
"type": "duration",
"unit": "ms"
},
{
"default_value": "0ms",
"description": "Network write timeout",
"mandatory": false,
"modifiable": true,
"name": "net_write_timeout",
"type": "duration",
"unit": "ms"
},
{
"description": "Password for the user used to retrieve database users",
"mandatory": true,
"modifiable": true,
"name": "password",
"type": "string"
},
{
"default_value": true,
"description": "Prune old session command history if the limit is exceeded",
"mandatory": false,
"modifiable": true,
"name": "prune_sescmd_history",
"type": "bool"
},
{
"default_value": "primary",
"description": "Service rank",
"enum_values": [
"primary",
"secondary"
],
"mandatory": false,
"modifiable": true,
"name": "rank",
"type": "enum"
},
{
"default_value": -1,
"description": "Number of statements kept in memory",
"mandatory": false,
"modifiable": true,
"name": "retain_last_statements",
"type": "int"
},
{
"default_value": false,
"description": "Enable session tracing for this service",
"mandatory": false,
"modifiable": true,
"name": "session_trace",
"type": "bool"
},
{
"default_value": false,
"description": "Track session state using server responses",
"mandatory": false,
"modifiable": true,
"name": "session_track_trx_state",
"type": "bool"
},
{
"default_value": true,
"description": "Strip escape characters from database names",
"mandatory": false,
"modifiable": true,
"name": "strip_db_esc",
"type": "bool"
},
{
"description": "Username used to retrieve database users",
"mandatory": true,
"modifiable": true,
"name": "user",
"type": "string"
},
{
"description": "Load additional users from a file",
"mandatory": false,
"modifiable": false,
"name": "user_accounts_file",
"type": "path"
},
{
"default_value": "add_when_load_ok",
"description": "When and how the user accounts file is used",
"enum_values": [
"add_when_load_ok",
"file_only_always"
],
"mandatory": false,
"modifiable": false,
"name": "user_accounts_file_usage",
"type": "enum"
},
{
"description": "Custom version string to use",
"mandatory": false,
"modifiable": true,
"name": "version_string",
"type": "string"
}
],
"version": "V1.1.0"
},
"id": "readwritesplit",
"links": {
"self": "http://localhost:8989/v1/modules/readwritesplit/"
},
"type": "modules"
},
"links": {
"self": "http://localhost:8989/v1/maxscale/modules/"
}
}
