Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Access the complete reference for the MariaDB MaxScale REST API. Find documentation for all resources, authentication methods, and endpoints for programmatic management.
Configure database traffic filters programmatically. This resource enables you to retrieve, create, and modify filter instances and their runtime parameters.
A filter resource represents an instance of a filter inside MaxScale. Multiple services can use the same filter and a single service can use multiple filters.
The :name in all of the URIs must be the name of a filter in MaxScale.
Get a single filter.
Status: 200 OK
Get all filters.
Status: 200 OK
The :type in the URI must be services as filters only have service relationships.
Status: 200 OK
Create a new filter. The posted object must define at least the following fields.
data.id
Name of the filter
data.type
All of the filter parameters should be defined at creation time in the data.attributes.parameters object.
As the service to filter relationship is ordered (filters are applied in the order they are listed), filter to service relationships cannot be defined at creation time.
The following example defines a request body which creates a new filter.
Filter is created:
Status: 204 No Content
Filter parameters can be updated at runtime if the module supports it. Refer to the individual module documentation for more details on whether it supports runtime configuration and which parameters can be updated.
The following example modifies a filter by changing the match parameter to .*users.*.
Filter is modified:
Status: 204 No Content
The :filter in the URI must map to the name of the filter to be destroyed.
A filter can only be destroyed if no service uses it. This means that the data.relationships object for the filter must be empty. Note that the service → filter relationship cannot be modified from the filters resource and must be done via the services resource.
This endpoint also supports the force=yes parameter that will unconditionally delete the filter by first removing it from all services that it uses.
Filter is destroyed:
Status: 204 No Content
This page is licensed: CC BY-SA / Gnu FDL
Manage administrative access to MaxScale. Learn to create, update, and delete admin users and manage their credentials for the REST API and MaxCtrl.
Admin users represent administrative users that are able to query and change MaxScale's configuration.
Get a single network user. The :name in the URI must be a valid network user name.
Status: 200 OK
Get all network users.
Status: 200 OK
Get all administrative users.
Status: 200 OK
Create a new network user. The request body must define at least the following fields.
data.id
The username.
data.attributes.password
Here is an example request body defining the network user my-user with the password my-password that is allowed to execute only read-only operations.
The :name part of the URI must be a valid user name.
Update network user. The following fields can be modified:
data.attributes.password
Changes the password for this user.
data.attributes.role or data.attributes.account
Modifying a user requires administrative privileges.
Here is an example request body that updates the password.
This page is licensed: CC BY-SA / Gnu FDL
Manage network listeners via the REST API. Use this resource to define ports, protocols, and service associations for handling incoming client connections.
filtersdata.attributes.module
The filter module to use
data.attributes.role or data.attributes.account
The role that this user account uses. The set of available roles can be retrieved with GET /v1/roles. The old fixed set of roles that older versions of MaxScale used are also read from the account field, if used. If both the role and the account field are present, the value of the role field is used.
Changes the role for this user. If both fields are defined, the value of role is used.
Get a single listener. The :name in the URI must be the name of a listener in MaxScale.
Status: 200 OK
Get all listeners.
Status: 200 OK
The :type in the URI must be services as listeners only have service relationships.
Status: 200 OK
Creates a new listener. The request body must define the following fields.
data.id
Name of the listener
data.type
Type of the object, must be listeners
data.attributes.parameters.port OR data.attributes.parameters.socket
The TCP port or UNIX Domain Socket the listener listens on. Only one of the fields can be defined.
data.relationships.services.data
The service relationships data, must define a JSON object with an id value that defines the service to use and a type value set to services.
The following is the minimal required JSON object for defining a new listener.
Refer to the Configuration Guide for a full list of listener parameters.
Listener is created:
Status: 204 No Content
The request body must be a JSON object which represents a set of new definitions for the listener.
All parameters marked as modifiable at runtime can be modified. Currently, all TLS/SSL parameters and the connection_init_sql_file and sql_mode parameters can be modified at runtime.
Parameters that affect the network address or the port the listener listens on cannot be modified at runtime. To modify these parameters, recreate the listener.
Listener is modified:
Status: 204 No Content
The :name must be a valid listener name. When a listener is destroyed, the network port it listens on is available for reuse.
Listener is destroyed:
Status: 204 No Content
Listener cannot be deleted:
Status: 400 Bad Request
Stops a started listener. When a listener is stopped, new connections are no longer accepted and are queued until the listener is started again.
This endpoint supports the following parameters:
force=yes
Close all existing connections that were created through this listener.
Listener is stopped:
Status: 204 No Content
Starts a stopped listener.
Listener is started:
Status: 204 No Content
This page is licensed: CC BY-SA / Gnu FDL
GET /v1/filters/:name{
"data": {
"attributes": {
"module": "qlafilter",
"parameters": {
"append": false,
"duration_unit": "ms",
"exclude": null,
"filebase": "/tmp/qla.log",
"flush": true,
"log_data": "date,user,query",
"log_type": "unified",
"match": null,
"module": "qlafilter",
"newline_replacement": " ",
"options": "",
"separator": ",",
"source": null,
"source_exclude": null,
"source_match": null,
"use_canonical_form": false,
"user": null,
"user_exclude": null,
"user_match": null
},
"source": {
"file": "/etc/maxscale.cnf",
"type": "static"
}
},
"id": "QLA",
"links": {
"self": "http://localhost:8989/v1/filters/QLA/"
},
"relationships": {
"services": {
"data": [
{
"id": "Read-Connection-Router",
"type": "services"
}
],
"links": {
"related": "http://localhost:8989/v1/services/",
"self": "http://localhost:8989/v1/filters/QLA/relationships/services/"
}
}
},
"type": "filters"
},
"links": {
"self": "http://localhost:8989/v1/filters/QLA/"
}
}GET /v1/filters{
"data": [
{
"attributes": {
"module": "qlafilter",
"parameters": {
"append": false,
"duration_unit": "ms",
"exclude": null,
"filebase": "/tmp/qla.log",
"flush": true,
"log_data": "date,user,query",
"log_type": "unified",
"match": null,
"module": "qlafilter",
"newline_replacement": " ",
"options": "",
"separator": ",",
"source": null,
"source_exclude": null,
"source_match": null,
"use_canonical_form": false,
"user": null,
"user_exclude": null,
"user_match": null
},
"source": {
"file": "/etc/maxscale.cnf",
"type": "static"
}
},
"id": "QLA",
"links": {
"self": "http://localhost:8989/v1/filters/QLA/"
},
"relationships": {
"services": {
"data": [
{
"id": "Read-Connection-Router",
"type": "services"
}
],
"links": {
"related": "http://localhost:8989/v1/services/",
"self": "http://localhost:8989/v1/filters/QLA/relationships/services/"
}
}
},
"type": "filters"
},
{
"attributes": {
"module": "hintfilter",
"parameters": {
"module": "hintfilter"
},
"source": {
"file": "/etc/maxscale.cnf",
"type": "static"
}
},
"id": "Hint",
"links": {
"self": "http://localhost:8989/v1/filters/Hint/"
},
"relationships": {
"services": {
"data": [
{
"id": "Read-Connection-Router",
"type": "services"
}
],
"links": {
"related": "http://localhost:8989/v1/services/",
"self": "http://localhost:8989/v1/filters/Hint/relationships/services/"
}
}
},
"type": "filters"
}
],
"links": {
"self": "http://localhost:8989/v1/filters/"
}
}GET /v1/filters/:name/relationships/:type{
"data": [
{
"id": "Read-Connection-Router",
"type": "services"
}
],
"links": {
"related": "http://localhost:8989/v1/services/",
"self": "http://localhost:8989/v1/filters/QLA/relationships/services/"
}
}POST /v1/filters{
"data": {
"id": "test-filter", // Name of the filter
"type": "filters",
"attributes": {
"module": "qlafilter", // The filter uses the qlafilter module
"parameters": { // Filter parameters
"filebase": "/tmp/qla.log"
}
}
}
}PATCH /v1/filters/:name{
"data": {
"attributes": {
"parameters": {
"match": ".*users.*"
}
}
}
}DELETE /v1/filters/:filterGET /v1/users/:name
GET /v1/users/inet/:name{
"data": {
"attributes": {
"account": "admin",
"created": "Fri, 25 Jul 2025 15:43:46 GMT",
"last_login": "Fri, 25 Jul 2025 15:44:03 GMT",
"last_update": null,
"name": "admin",
"permissions": [
"admin",
"edit",
"view",
"sql"
]
},
"id": "admin",
"links": {
"self": "http://localhost:8989/v1/users/admin/"
},
"type": "users"
},
"links": {
"self": "http://localhost:8989/v1/users/admin/"
}
}GET /v1/users
GET /v1/users/inet{
"data": [
{
"attributes": {
"account": "admin",
"created": "Fri, 25 Jul 2025 15:43:46 GMT",
"last_login": "Fri, 25 Jul 2025 15:44:03 GMT",
"last_update": null,
"name": "admin",
"permissions": [
"admin",
"edit",
"view",
"sql"
]
},
"id": "admin",
"links": {
"self": "http://localhost:8989/v1/users/admin/"
},
"type": "users"
}
],
"links": {
"self": "http://localhost:8989/v1/users/"
}
}GET /v1/users{
"data": [
{
"attributes": {
"account": "admin",
"created": "Fri, 25 Jul 2025 15:43:46 GMT",
"last_login": "Fri, 25 Jul 2025 15:44:03 GMT",
"last_update": null,
"name": "admin",
"permissions": [
"admin",
"edit",
"view",
"sql"
]
},
"id": "admin",
"links": {
"self": "http://localhost:8989/v1/users/admin/"
},
"type": "users"
}
],
"links": {
"self": "http://localhost:8989/v1/users/"
}
}POST /v1/users
POST /v1/users/inet{
"data": {
"id": "my-user", // The user to create
"attributes": {
"password": "my-password", // The password to use for the user
"role": "admin" // The type of the account
}
}
}Status: 204 No ContentDELETE /v1/users/:name
DELETE /v1/users/inet/:nameStatus: 204 No ContentPATCH /v1/users/:name
PATCH /v1/users/inet/:name{
"data": {
"attributes": {
"password": "new-password"
}
}
}Status: 204 No ContentGET /v1/listeners/:name{
"data": {
"attributes": {
"module": "MariaDBProtocol",
"parameters": {
"MariaDBProtocol": {
"allow_replication": true,
"compression": "zlib,zstd",
"compression_threshold": 50
},
"address": "::",
"authenticator": null,
"authenticator_options": null,
"connection_init_sql_file": null,
"connection_metadata": [
"character_set_client=auto",
"character_set_connection=auto",
"character_set_results=auto",
"max_allowed_packet=auto",
"system_time_zone=auto",
"time_zone=auto",
"tx_isolation=auto",
"maxscale=auto"
],
"port": 4006,
"protocol": "MariaDBProtocol",
"proxy_protocol_networks": null,
"redirect_url": null,
"service": "RW-Split-Router",
"socket": null,
"sql_mode": "default",
"ssl": false,
"ssl_ca": null,
"ssl_cert": null,
"ssl_cert_verify_depth": 9,
"ssl_cipher": null,
"ssl_crl": null,
"ssl_key": null,
"ssl_passphrase": "",
"ssl_verify_peer_certificate": false,
"ssl_verify_peer_host": false,
"ssl_version": "MAX",
"type": "listener",
"user_mapping_file": null
},
"source": {
"file": "/etc/maxscale.cnf",
"type": "static"
},
"state": "Running"
},
"id": "RW-Split-Listener",
"relationships": {
"services": {
"data": [
{
"id": "RW-Split-Router",
"type": "services"
}
],
"links": {
"related": "http://localhost:8989/v1/services/",
"self": "http://localhost:8989/v1/listeners/RW-Split-Listener/relationships/services/"
}
}
},
"type": "listeners"
},
"links": {
"self": "http://localhost:8989/v1/listeners/RW-Split-Listener/"
}
}GET /v1/listeners{
"data": [
{
"attributes": {
"module": "MariaDBProtocol",
"parameters": {
"MariaDBProtocol": {
"allow_replication": true,
"compression": "zlib,zstd",
"compression_threshold": 50
},
"address": "::",
"authenticator": null,
"authenticator_options": null,
"connection_init_sql_file": null,
"connection_metadata": [
"character_set_client=auto",
"character_set_connection=auto",
"character_set_results=auto",
"max_allowed_packet=auto",
"system_time_zone=auto",
"time_zone=auto",
"tx_isolation=auto",
"maxscale=auto"
],
"port": 4006,
"protocol": "MariaDBProtocol",
"proxy_protocol_networks": null,
"redirect_url": null,
"service": "RW-Split-Router",
"socket": null,
"sql_mode": "default",
"ssl": false,
"ssl_ca": null,
"ssl_cert": null,
"ssl_cert_verify_depth": 9,
"ssl_cipher": null,
"ssl_crl": null,
"ssl_key": null,
"ssl_passphrase": "",
"ssl_verify_peer_certificate": false,
"ssl_verify_peer_host": false,
"ssl_version": "MAX",
"type": "listener",
"user_mapping_file": null
},
"source": {
"file": "/etc/maxscale.cnf",
"type": "static"
},
"state": "Running"
},
"id": "RW-Split-Listener",
"relationships": {
"services": {
"data": [
{
"id": "RW-Split-Router",
"type": "services"
}
],
"links": {
"related": "http://localhost:8989/v1/services/",
"self": "http://localhost:8989/v1/listeners/RW-Split-Listener/relationships/services/"
}
}
},
"type": "listeners"
},
{
"attributes": {
"module": "MariaDBProtocol",
"parameters": {
"MariaDBProtocol": {
"allow_replication": true,
"compression": "zlib,zstd",
"compression_threshold": 50
},
"address": "::",
"authenticator": null,
"authenticator_options": null,
"connection_init_sql_file": null,
"connection_metadata": [
"character_set_client=auto",
"character_set_connection=auto",
"character_set_results=auto",
"max_allowed_packet=auto",
"system_time_zone=auto",
"time_zone=auto",
"tx_isolation=auto",
"maxscale=auto"
],
"port": 4008,
"protocol": "MariaDBProtocol",
"proxy_protocol_networks": null,
"redirect_url": null,
"service": "Read-Connection-Router",
"socket": null,
"sql_mode": "default",
"ssl": false,
"ssl_ca": null,
"ssl_cert": null,
"ssl_cert_verify_depth": 9,
"ssl_cipher": null,
"ssl_crl": null,
"ssl_key": null,
"ssl_passphrase": "",
"ssl_verify_peer_certificate": false,
"ssl_verify_peer_host": false,
"ssl_version": "MAX",
"type": "listener",
"user_mapping_file": null
},
"source": {
"file": "/etc/maxscale.cnf",
"type": "static"
},
"state": "Running"
},
"id": "Read-Connection-Listener",
"relationships": {
"services": {
"data": [
{
"id": "Read-Connection-Router",
"type": "services"
}
],
"links": {
"related": "http://localhost:8989/v1/services/",
"self": "http://localhost:8989/v1/listeners/Read-Connection-Listener/relationships/services/"
}
}
},
"type": "listeners"
}
],
"links": {
"self": "http://localhost:8989/v1/listeners/"
}
}GET /v1/listeners/:name/relationships/:type{
"data": [
{
"id": "RW-Split-Router",
"type": "services"
}
],
"links": {
"related": "http://localhost:8989/v1/services/",
"self": "http://localhost:8989/v1/listeners/RW-Split-Listener/relationships/services/"
}
}POST /v1/listeners{
"data": {
"id": "my-listener",
"type": "listeners",
"attributes": {
"parameters": {
"port": 3306
}
},
"relationships": {
"services": {
"data": [
{"id": "RW-Split-Router", "type": "services"}
]
}
}
}
}PATCH /v1/listeners/:nameDELETE /v1/listeners/:namePUT /v1/listeners/:name/stopPUT /v1/listeners/:name/startDefine and assign access roles. This resource allows you to manage permissions for MaxScale administrative users, controlling their access to API resources.
Admin roles represent a set of permissions that define which operations are allowed on the REST-API.
Get a single role. The :name in the URI must be a valid role name.
Status: 200 OK
Get all roles.
Status: 200 OK
Create a new role. The request body must define the following fields.
data.id
The role name
data.attributes.permissions
The supported permissions are:
admin: Access to the administrative endpoints /users and /roles which are used to create new user accounts and roles.
edit: Write access to all endpoints that create objects except the administrative endpoints /users and /roles. This permission is required for creating, modifying or destroying objects via the REST-API.
Here is an example request that defines a new role my-role that can view and edit objects but cannot use the Query Editor.
Update a role. Only the data.attributes.permissions field can be modified. Modifying a role requires administrative privileges.
Here is an example request body that updates the permissions of a role.
The :name part of the URI must be a valid role name.
This page is licensed: CC BY-SA / Gnu FDL
GET /v1/role/:name/roles endpoint. These extra permissions can then be used by external systems or as a way to label account types.sql: Read-only access to the /maxscale, /servers, /services and /listeners endpoints as well as full permissions on the /sql endpoint. This permission is needed by the Query Editor feature.
view: Read-only access to all endpoints except the administrative endpoints /users and /roles. This permission is required for most read-only operations in the GUI.
{
"data": {
"attributes": {
"permissions": [
"admin",
"edit",
"view",
"sql"
]
},
"id": "admin",
"links": {
"self": "http://localhost:8989/v1/roles/admin/"
},
"type": "roles"
},
"links": {
"self": "http://localhost:8989/v1/roles/admin/"
}
}GET /v1/roles{
"data": [
{
"attributes": {
"permissions": [
"edit",
"view",
"sql"
]
},
"id": "editor",
"links": {
"self": "http://localhost:8989/v1/roles/editor/"
},
"type": "roles"
},
{
"attributes": {
"permissions": [
"admin",
"edit",
"view",
"sql"
]
},
"id": "admin",
"links": {
"self": "http://localhost:8989/v1/roles/admin/"
},
"type": "roles"
},
{
"attributes": {
"permissions": [
"sql"
]
},
"id": "sql",
"links": {
"self": "http://localhost:8989/v1/roles/sql/"
},
"type": "roles"
},
{
"attributes": {
"permissions": [
"view",
"sql"
]
},
"id": "basic",
"links": {
"self": "http://localhost:8989/v1/roles/basic/"
},
"type": "roles"
}
],
"links": {
"self": "http://localhost:8989/v1/roles/"
}
}POST /v1/roles{
"data": {
"id": "my-role",
"attributes": {
"permissions": ["view", "edit"]
}
}
}Status: 204 No ContentPATCH /v1/roles/:name{
"data": {
"attributes": {
"permissions": ["view, "edit"]
}
}
}Status: 204 No ContentDELETE /v1/roles/:nameStatus: 204 No ContentInspect and manage active client sessions. This resource allows you to view connected clients, check session details, and terminate specific connections.
A session is an abstraction of a client connection, any number of related backend connections, a router module session and possibly filter module sessions. Each session is created on a service and each service can have multiple sessions.
Get a single session. :id must be a valid session ID. The session ID is the same that is exposed to the client as the connection ID.
This endpoint also supports the rdns=true parameter, which instructs MaxScale to perform reverse DNS on the client IP address. As this requires communicating with an external server, the operation may be expensive.
Status: 200 OK
Get all sessions.
Status: 200 OK
The request body must be a JSON object which represents the new configuration of the session. The :id must be a valid session ID that is active.
The log_debug, log_info, log_notice, log_warning and log_error boolean parameters control whether the associated logging level is enabled:
The filters that a session uses can be updated by re-defining the filter relationship of the session. This causes new filter sessions to be opened immediately. The old filter session are closed and replaced with the new filter session the next time the session is idle. The order in which the filters are defined in the request body is the order in which the filters are installed, similar to how the filter relationship for services behaves.
Session is modified:
Status: 204 No Content
This endpoint causes the session to re-read the configuration from the service. As a result of this, all backend connections will be closed and then opened again. All router and filter sessions will be created again which means that for modules that perform something whenever a new module session is opened, this behaves as if a new session was started.
This endpoint can be used to apply configuration changes that were done after the session was started. This can be useful for situations where the client connections live for a long time and connections are not recycled often enough.
Session is was restarted:
Status: 204 No Content
This endpoint does the same thing as the /v1/sessions/:id/restart endpoint except that it applies to all sessions.
Session is was restarted:
Status: 204 No Content
This endpoint causes the session to be forcefully closed.
This endpoint supports the following request parameters.
ttl
The time after which the session is killed. If this parameter is not given, the session is killed immediately. This can be used to give the session time to finish the work it is performing before the connection is closed.
Session was killed:
Status: 204 No Content
This page is licensed: CC BY-SA / Gnu FDL
GET /v1/sessions/:id{
"data": {
"attributes": {
"client": {
"cipher": "",
"connection_attributes": {
"_client_name": "libmariadb",
"_client_version": "3.3.4",
"_os": "Linux",
"_pid": "502300",
"_platform": "x86_64",
"_server_host": "127.0.0.1"
},
"sescmd_history_len": 1,
"sescmd_history_stored_metadata": 0,
"sescmd_history_stored_responses": 1
},
"connected": "Fri, 05 Jan 2024 07:24:06 GMT",
"connections": [
{
"cipher": "",
"connection_id": 129,
"server": "server1"
}
],
"idle": 5.2000000000000002,
"io_activity": 16,
"log": [],
"memory": {
"connection_buffers": {
"backends": {
"server1": {
"misc": 662,
"readq": 0,
"total": 662,
"writeq": 0
}
},
"client": {
"misc": 654,
"readq": 65536,
"total": 66190,
"writeq": 0
},
"total": 66852
},
"exec_metadata": 0,
"last_queries": 0,
"sescmd_history": 485,
"total": 67337,
"variables": 0
},
"parameters": {
"log_debug": false,
"log_error": false,
"log_info": false,
"log_notice": false,
"log_warning": false
},
"port": 40664,
"queries": [],
"remote": "127.0.0.1",
"seconds_alive": 5.209291554,
"state": "Session started",
"thread": 2,
"user": "maxuser"
},
"id": "1",
"links": {
"self": "http://localhost:8989/v1/sessions/1/"
},
"relationships": {
"services": {
"data": [
{
"id": "RW-Split-Router",
"type": "services"
}
],
"links": {
"related": "http://localhost:8989/v1/services/",
"self": "http://localhost:8989/v1/sessions/1/relationships/services/"
}
}
},
"type": "sessions"
},
"links": {
"self": "http://localhost:8989/v1/sessions/1/"
}
}GET /v1/sessions{
"data": [
{
"attributes": {
"client": {
"cipher": "",
"connection_attributes": {
"_client_name": "libmariadb",
"_client_version": "3.3.4",
"_os": "Linux",
"_pid": "502300",
"_platform": "x86_64",
"_server_host": "127.0.0.1"
},
"sescmd_history_len": 1,
"sescmd_history_stored_metadata": 0,
"sescmd_history_stored_responses": 1
},
"connected": "Fri, 05 Jan 2024 07:24:06 GMT",
"connections": [
{
"cipher": "",
"connection_id": 129,
"server": "server1"
}
],
"idle": 5.2000000000000002,
"io_activity": 16,
"log": [],
"memory": {
"connection_buffers": {
"backends": {
"server1": {
"misc": 662,
"readq": 0,
"total": 662,
"writeq": 0
}
},
"client": {
"misc": 654,
"readq": 65536,
"total": 66190,
"writeq": 0
},
"total": 66852
},
"exec_metadata": 0,
"last_queries": 0,
"sescmd_history": 485,
"total": 67337,
"variables": 0
},
"parameters": {
"log_debug": false,
"log_error": false,
"log_info": false,
"log_notice": false,
"log_warning": false
},
"port": 40664,
"queries": [],
"remote": "127.0.0.1",
"seconds_alive": 5.2105843680000001,
"state": "Session started",
"thread": 2,
"user": "maxuser"
},
"id": "1",
"links": {
"self": "http://localhost:8989/v1/sessions/1/"
},
"relationships": {
"services": {
"data": [
{
"id": "RW-Split-Router",
"type": "services"
}
],
"links": {
"related": "http://localhost:8989/v1/services/",
"self": "http://localhost:8989/v1/sessions/1/relationships/services/"
}
}
},
"type": "sessions"
}
],
"links": {
"self": "http://localhost:8989/v1/sessions/"
}
}PATCH /v1/sessions/:id{
"data": {
"attributes": {
"parameters": {
"log_info": true
}
}
}
}{
"data": {
"attributes": {
"relationships": {
"filters": {
"data": [
{ "id": "my-cache-filter" },
{ "id": "my-log-filter" }
]
}
}
}
}
}POST /v1/sessions/:id/restartPOST /v1/sessions/restartDELETE /v1/sessions/:idControl server monitoring modules. This resource allows you to configure monitors, check cluster health status, and modify monitoring parameters dynamically.
A monitor resource represents a monitor inside MaxScale that monitors one or more servers.
The :name in all of the URIs must be the name of a monitor in MaxScale.
Get a single monitor.
Status: 200 OK
Get all monitors.
Status: 200 OK
The :type in the URI must be either services, for service relationships, or servers, for server relationships.
Status: 200 OK
Create a new monitor. The request body must define at least the following fields.
data.id
Name of the monitor
data.type
All monitor parameters can be defined at creation time.
The following example defines a request body which creates a new monitor and assigns two servers to be monitored by it. It also defines a custom value for the monitor_interval parameter.
Monitor is created:
Status: 204 No Content
The request body must be a valid JSON document representing the modified monitor.
The following standard server parameter can be modified. maxscale-monitors/common-monitor-parameters.md
In addition to these standard parameters, the monitor specific parameters can also be modified. Refer to the monitor module documentation for details on these parameters.
Monitor is modified:
Status: 204 No Content
Invalid request body:
Status: 400 Bad Request
The :type in the URI must be either services, for service relationships, or servers, for server relationships.
The request body must be a JSON object that defines only the data field. The value of the data field must be an array of relationship objects that define the id and type fields of the relationship. This object will replace the existing relationships of the monitor.
The following is an example request and request body that defines a single server relationship for a monitor.
All relationships for a monitor can be deleted by sending an empty array as the data field value. The following example removes all servers from a monitor.
Monitor relationships modified:
Status: 204 No Content
Invalid JSON body:
Status: 400 Bad Request
Destroy a created monitor. The monitor must not have relationships to any servers in order to be destroyed.
This endpoint also supports the force=yes parameter that will unconditionally delete the monitor by first unlinking it from all servers that it uses.
Monitor is deleted:
Status: 204 No Content
Monitor could not be deleted:
Status: 400 Bad Request
Stops a started monitor.
Monitor is stopped:
Status: 204 No Content
Starts a stopped monitor.
Monitor is started:
Status: 204 No Content
This page is licensed: CC BY-SA / Gnu FDL
monitorsdata.attributes.module
The monitor module to use
data.attributes.parameters.user
The user to use
data.attributes.parameters.password
The password to use
GET /v1/monitors/:name{
"data": {
"attributes": {
"module": "mariadbmon",
"monitor_diagnostics": {
"failback_master": null,
"master": "server1",
"master_gtid_domain_id": 0,
"primary": null,
"server_info": [
{
"gtid_binlog_pos": "0-3000-5",
"gtid_current_pos": "0-3000-5",
"lock_held": null,
"master_group": null,
"name": "server1",
"read_only": false,
"server_id": 3000,
"slave_connections": []
},
{
"gtid_binlog_pos": "0-3000-5",
"gtid_current_pos": "0-3000-5",
"lock_held": null,
"master_group": null,
"name": "server2",
"read_only": false,
"server_id": 3001,
"slave_connections": [
{
"connection_name": "",
"gtid_io_pos": "",
"last_io_error": "",
"last_sql_error": "",
"master_host": "127.0.0.1",
"master_port": 3000,
"master_server_id": 3000,
"master_server_name": "server1",
"seconds_behind_master": 0,
"slave_io_running": "Yes",
"slave_sql_running": "Yes",
"using_gtid": "No"
}
]
}
],
"state": "Idle"
},
"parameters": {
"assume_unique_hostnames": true,
"auto_failback_switchover": false,
"auto_failover": "false",
"auto_rejoin": false,
"backend_connect_attempts": 1,
"backend_timeout": "3000ms",
"backup_storage_address": null,
"backup_storage_path": null,
"cooperative_monitoring_locks": "none",
"cs_admin_api_key": null,
"cs_admin_base_path": "/cmapi/0.4.0",
"cs_admin_port": 8640,
"demotion_sql_file": null,
"disk_space_check_interval": "0ms",
"disk_space_threshold": null,
"enforce_read_only_servers": false,
"enforce_read_only_slaves": false,
"enforce_simple_topology": false,
"enforce_writable_master": false,
"events": "all,master_down,master_up,slave_down,slave_up,server_down,server_up,synced_down,synced_up,donor_down,donor_up,lost_master,lost_slave,lost_synced,lost_donor,new_master,new_slave,new_synced,new_donor",
"failcount": 5,
"failover_timeout": "90000ms",
"handle_events": true,
"journal_max_age": "28800000ms",
"maintenance_on_low_disk_space": true,
"mariabackup_parallel": 1,
"mariabackup_use_memory": "1G",
"master_conditions": "primary_monitor_master,disk_space_ok",
"master_failure_timeout": "10000ms",
"module": "mariadbmon",
"monitor_interval": "1000ms",
"password": "*****",
"primary_state_sql": null,
"promotion_sql_file": null,
"rebuild_port": 4444,
"replica_state_sql": null,
"replication_custom_options": null,
"replication_master_ssl": false,
"replication_password": "*****",
"replication_user": "maxuser",
"role": null,
"script": null,
"script_max_replication_lag": -1,
"script_timeout": "90000ms",
"servers_no_cooperative_monitoring_locks": null,
"servers_no_promotion": null,
"slave_conditions": "",
"ssh_check_host_key": true,
"ssh_keyfile": null,
"ssh_port": 22,
"ssh_timeout": "10000ms",
"ssh_user": null,
"switchover_on_low_disk_space": false,
"switchover_timeout": "90000ms",
"type": "monitor",
"user": "maxuser",
"verify_master_failure": true,
"write_test_fail_action": "log",
"write_test_interval": "0ms",
"write_test_table": "mxs.maxscale_write_test"
},
"source": {
"file": "/etc/maxscale.cnf",
"type": "static"
},
"state": "Running",
"ticks": 12
},
"id": "MariaDB-Monitor",
"links": {
"self": "http://localhost:8989/v1/monitors/MariaDB-Monitor/"
},
"relationships": {
"servers": {
"data": [
{
"id": "server1",
"type": "servers"
},
{
"id": "server2",
"type": "servers"
}
],
"links": {
"related": "http://localhost:8989/v1/servers/",
"self": "http://localhost:8989/v1/monitors/MariaDB-Monitor/relationships/servers/"
}
},
"services": {
"data": [
{
"id": "RW-Split-Router",
"type": "services"
}
],
"links": {
"related": "http://localhost:8989/v1/services/",
"self": "http://localhost:8989/v1/monitors/MariaDB-Monitor/relationships/services/"
}
}
},
"type": "monitors"
},
"links": {
"self": "http://localhost:8989/v1/monitors/MariaDB-Monitor/"
}
}GET /v1/monitors{
"data": [
{
"attributes": {
"module": "mariadbmon",
"monitor_diagnostics": {
"failback_master": null,
"master": "server1",
"master_gtid_domain_id": 0,
"primary": null,
"server_info": [
{
"gtid_binlog_pos": "0-3000-5",
"gtid_current_pos": "0-3000-5",
"lock_held": null,
"master_group": null,
"name": "server1",
"read_only": false,
"server_id": 3000,
"slave_connections": []
},
{
"gtid_binlog_pos": "0-3000-5",
"gtid_current_pos": "0-3000-5",
"lock_held": null,
"master_group": null,
"name": "server2",
"read_only": false,
"server_id": 3001,
"slave_connections": [
{
"connection_name": "",
"gtid_io_pos": "",
"last_io_error": "",
"last_sql_error": "",
"master_host": "127.0.0.1",
"master_port": 3000,
"master_server_id": 3000,
"master_server_name": "server1",
"seconds_behind_master": 0,
"slave_io_running": "Yes",
"slave_sql_running": "Yes",
"using_gtid": "No"
}
]
}
],
"state": "Idle"
},
"parameters": {
"assume_unique_hostnames": true,
"auto_failback_switchover": false,
"auto_failover": "false",
"auto_rejoin": false,
"backend_connect_attempts": 1,
"backend_timeout": "3000ms",
"backup_storage_address": null,
"backup_storage_path": null,
"cooperative_monitoring_locks": "none",
"cs_admin_api_key": null,
"cs_admin_base_path": "/cmapi/0.4.0",
"cs_admin_port": 8640,
"demotion_sql_file": null,
"disk_space_check_interval": "0ms",
"disk_space_threshold": null,
"enforce_read_only_servers": false,
"enforce_read_only_slaves": false,
"enforce_simple_topology": false,
"enforce_writable_master": false,
"events": "all,master_down,master_up,slave_down,slave_up,server_down,server_up,synced_down,synced_up,donor_down,donor_up,lost_master,lost_slave,lost_synced,lost_donor,new_master,new_slave,new_synced,new_donor",
"failcount": 5,
"failover_timeout": "90000ms",
"handle_events": true,
"journal_max_age": "28800000ms",
"maintenance_on_low_disk_space": true,
"mariabackup_parallel": 1,
"mariabackup_use_memory": "1G",
"master_conditions": "primary_monitor_master,disk_space_ok",
"master_failure_timeout": "10000ms",
"module": "mariadbmon",
"monitor_interval": "1000ms",
"password": "*****",
"primary_state_sql": null,
"promotion_sql_file": null,
"rebuild_port": 4444,
"replica_state_sql": null,
"replication_custom_options": null,
"replication_master_ssl": false,
"replication_password": "*****",
"replication_user": "maxuser",
"role": null,
"script": null,
"script_max_replication_lag": -1,
"script_timeout": "90000ms",
"servers_no_cooperative_monitoring_locks": null,
"servers_no_promotion": null,
"slave_conditions": "",
"ssh_check_host_key": true,
"ssh_keyfile": null,
"ssh_port": 22,
"ssh_timeout": "10000ms",
"ssh_user": null,
"switchover_on_low_disk_space": false,
"switchover_timeout": "90000ms",
"type": "monitor",
"user": "maxuser",
"verify_master_failure": true,
"write_test_fail_action": "log",
"write_test_interval": "0ms",
"write_test_table": "mxs.maxscale_write_test"
},
"source": {
"file": "/etc/maxscale.cnf",
"type": "static"
},
"state": "Running",
"ticks": 12
},
"id": "MariaDB-Monitor",
"links": {
"self": "http://localhost:8989/v1/monitors/MariaDB-Monitor/"
},
"relationships": {
"servers": {
"data": [
{
"id": "server1",
"type": "servers"
},
{
"id": "server2",
"type": "servers"
}
],
"links": {
"related": "http://localhost:8989/v1/servers/",
"self": "http://localhost:8989/v1/monitors/MariaDB-Monitor/relationships/servers/"
}
},
"services": {
"data": [
{
"id": "RW-Split-Router",
"type": "services"
}
],
"links": {
"related": "http://localhost:8989/v1/services/",
"self": "http://localhost:8989/v1/monitors/MariaDB-Monitor/relationships/services/"
}
}
},
"type": "monitors"
}
],
"links": {
"self": "http://localhost:8989/v1/monitors/"
}
}GET /v1/monitors/:name/relationships/servers{
"data": [
{
"id": "server1",
"type": "servers"
},
{
"id": "server2",
"type": "servers"
}
],
"links": {
"related": "http://localhost:8989/v1/servers/",
"self": "http://localhost:8989/v1/monitors/MariaDB-Monitor/relationships/servers/"
}
}POST /v1/monitors{
data: {
"id": "test-monitor", // Name of the monitor
"type": "monitors",
"attributes": {
"module": "mariadbmon", // The monitor uses the mariadbmon module
"parameters": { // Monitor parameters
"monitor_interval": 1000,
"user": "maxuser,
"password": "maxpwd"
}
},
"relationships": { // List of server relationships that this monitor uses
"servers": {
"data": [ // This monitor uses two servers
{
"id": "server1",
"type": "servers"
},
{
"id": "server2",
"type": "servers"
}
]
}
}
}
}PATCH /v1/monitors/:namePATCH /v1/monitors/:name/relationships/:typePATCH /v1/monitors/my-monitor/relationships/servers
{
data: [
{ "id": "my-server", "type": "servers" }
]
}PATCH /v1/monitors/my-monitor/relationships/servers
{
data: []
}DELETE /v1/monitors/:namePUT /v1/monitors/:name/stopPUT /v1/monitors/:name/startThis endpoint also supports executing SQL queries using an ODBC driver. The results returned by connections that use ODBC drivers can differ from the ones returned by normal SQL connections to objects in MaxScale.
This document uses the :id value in the URL to represent a connection ID and the :query_id to represent a query ID. These values do not need to be manually added as the relevant links are returned in the request body of each endpoint.
The endpoints use JSON Web Tokens to uniquely identify open SQL connections. A connection token can be acquired with a POST /v1/sql request and can be used with the POST /v1/sql/:id/query, GET /v1/sql/:id/results/:query_id andDELETE /v1/sql endpoints. All of these endpoints accept a connection token in the token parameter of the request:
In addition to request parameters, the token can be stored in cookies in which case they are automatically used by the REST API. For more information about token storage in cookies, see the documentation for POST /v1/sql.
All of the endpoints that operate on a single connection support the following request parameters. The GET /v1/sql and GET /v1/sql/:id endpoints are an exception as they ignore the current connection token.
token
The connection token to use for the request. If provided, the value is unconditionally used even if a cookie with a valid token exists.
Response contains the requested resource.
Status: 200 OK
Response contains a resource collection with all the open SQL connections.
Status: 200 OK
The request body must be a JSON object consisting of the following fields:
target
The object to connect to. This is a mandatory value and the given value must be the name of a valid server, service or listener in MaxScale or the value odbc if an ODBC connection is being made.
user
The username to use when creating the connection. This is a mandatory value when connecting to an object in MaxScale.
password
The password for the user. This is a mandatory value when connecting to an object in MaxScale.
db
The default database for the connection. By default the connection will have no default database. This is ignored by ODBC connections.
timeout
Connection timeout in seconds. The default connection timeout is 10 seconds. This controls how long the SQL connection creation can take before an error is returned. This is accepted by all connection types.
connection_string
Connection string that defines the ODBC connection. This is a required value for ODBC type connections and is ignored by all other connection types.
Here is an example request body:
And here is an example request that uses an ODBC driver to connect to a remote server:
The response will contain the new connection with the token stored atmeta.token. If the request uses the persist=yes request parameter, the token is stored in cookies instead of the metadata object and the response body will not contain the token.
The location of the newly created connection will be stored at links.self in the response body as well as in the Location header.
The token must be given to all subsequent requests that use the connection. It must be either given in the token parameter of a request or it must be stored in the cookies. If both a token parameter and a cookie exist at the same time, the token parameter will be used instead of the cookie.
Request Parameters
This endpoint supports the following request parameters.
persist
Store the connection token in cookies instead of returning it as the response body. This parameter expects only one value, yes, as its argument. Whenpersist=yes is set, the token is stored in the conn_id_sig_<id> cookie where the <id> part is replaced by the ID of the connection.
max-age
Sets the connection token maximum age in seconds. The default ismax-age=28800. Only positive values are accepted and if a non-positive or a non-integer value is found, the parameter is ignored. Once the token age exceeds the configured maximum value, the token can no longer be used and a new connection must be created.
Connection was opened:
Status: 201 Created
Missing or invalid payload:
Status: 400 Bad Request
Connection was closed:
Status: 204 No Content
Missing or invalid connection token:
Status: 400 Bad Request
Reconnects an existing connection. This can also be used if the connection to the backend server was lost due to a network error.
The connection will use the same credentials that were passed to the POST /v1/sql endpoint. The new connection will still have the same ID in the REST API but will be treated as a new connection by the database. A reconnection re-initializes the connection and resets the session state. Reconnections cannot take place while a transaction is open.
Reconnection was successful:
Status: 204 No Content
Reconnection failed or connection is already in use:
Status: 503 Service Unavailable
Missing or invalid connection token:
Status: 400 Bad Request
Clones an existing connection. This is done by opening a new connection using the credentials and configuration from the given connection.
Request Parameters
This endpoint supports the same request parameters as the POST /v1/sql endpoint.
The response is identical to the one in the POST /v1/sql endpoint. In addition, this endpoint can return the following responses.
Connection is already in use:
Status: 503 Service Unavailable
Missing or invalid connection token:
Status: 400 Bad Request
The request body must be a JSON object with the value of the sql field set to the SQL to be executed:
The request body must be a JSON object consisting of the following fields:
sql
The SQL to be executed. If the SQL contain multiple statements, multiple results are returned in the response body.
max_rows
The maximum number of rows returned in the response. By default this is 1000 rows. Setting the value to 0 means no limit. Any extra rows in the result will be discarded.
By default, the complete result is returned in the response body. If the SQL query returns more than one result, the results array will contain all the results. If the async=true request option is used, the query is queued for execution.
The results array can have three types of objects: resultsets, errors, and OK responses.
A resultset consists of the data field with the result data stored as a two dimensional array. The names of the fields are stored in an array in thefields field and the field types and other metadata are stored in themetadata field. These types of results will be returned for any operation that returns rows (i.e. SELECT statements)
An error consists of an object with the errno field set to the MariaDB error code, the message field set to the human-readable error message and thesqlstate field set to the current SQLSTATE of the connection.
An OK response is returned for any result that completes successfully but not return rows (e.g. an INSERT or UPDATE statement). The affected_rows field contains the number of rows affected by the operation, thelast_insert_id contains the auto-generated ID and the warnings field contains the number of warnings raised by the operation.
It is also possible for the fields of the error response to be present in the resultset response if the result ended with an error but still generated some data. Usually this happens when query execution is interrupted but a partial result was generated by the server.
Request Parameters
async
If set to true, the query is queued for asynchronous execution and the results must be retrieved later from the URL stored in links.self field of the response. The HTTP response code is set to HTTP 202 Accepted if the query was successfully queued for execution.
Query successfully executed:
Status: 201 Created
Query queued for execution:
Status: 202 Accepted
Invalid payload or missing connection token:
Status: 400 Bad Request
Fatal connection error:
Status: 503 Service Unavailable
If the API returns this response, the connection to the database server was lost. The only valid action to take at this point is to close it with theDELETE /v1/sql/:id endpoint.
The results are only available if a POST /v1/sql/:id/queries was executed with the async field set to true. The result of any asynchronous query can be read multiple times. Only the latest result is stored: executing a new query will cause the latest result to be erased. Results can be explicitly erased with a DELETE request.
Query successfully executed:
Status: 201 Created
Query not yet complete:
Status: 202 Accepted
No asynchronous results expected, invalid payload or missing connection token:
Status: 400 Bad Request
Fatal connection error:
Status: 503 Service Unavailable
If the API returns this response, the connection to the database server was lost. The only valid action to take at this point is to close it with theDELETE /v1/sql/:id endpoint.
Erases the latest result of an asynchronously executed query. All asynchronous results are erased when the connection that owns them is closed.
Result erased:
Status: 200 OK
Connection is busy or it was not found:
Status: 503 Service Unavailable
Missing connection token:
Status: 400 Bad Request
This endpoint cancels the current query being executed by this connection. If no query is being done and the connection is idle, no action is taken.
If the connection is busy but it is not executing a query, an attempt to cancel is still made: in this case the results of this operation are undefined for ODBC connections, for MariaDB connections this will cause a KILL QUERY command to be executed.
Query was canceled:
Status: 200 OK
Connection was not found:
Status: 503 Service Unavailable
Missing connection token:
Status: 400 Bad Request
Get the list of configured ODBC drivers found by the driver manager. The list of drivers includes all drivers known to the driver manager for which an installed library was found (i.e. Driver or Driver64 in /etc/odbcinst.ini points to a file).
The response contains a resource collection with all available drivers.
Status: 200 OK
The ETL operation requires two connections: an ODBC connection to a remote server (source connection) and a connection to a server in MaxScale (destination connection). All ETL operations must be done on the ODBC connection.
The ETL operations require that the MariaDB ODBC driver is installed on the MaxScale server. This driver is often available in the package manager of your operating system but it can also be downloaded from the MariaDB website.
The request body must be a JSON object consisting of the following fields:
target
The target connection ID that defines the destination server. This must be the ID of a connection (i.e. data.attributes.id ) to a server in MaxScale created via the POST /v1/sql/ endpoint.
type
The type of the ETL data source. The value must be a string with one of the following values:
tables
An array of objects, each of which must define a table and a schema field. The table field defines the name of the table to be imported and theschema field defines the schema it is in. If the objects contain a value forcreate, select or insert, the SQL generation for that part is skipped.
connection_string
Extra connection string that is appended to the destination server's connection string. This connection will always use the MariaDB ODBC driver. The list of supported options can be found here.
threads
The number of parallel connections used during the ETL operation. By default the ETL operation will use up to 16 connections.
timeout
The connection and query timeout in seconds. By default a timeout of 30 seconds is used.
create_mode
A string with either normal, ignore or replace which controls how tables are handled that already exist on the destination server.
If left undefined or set to normal, the tables are created using a normalCREATE TABLE statement. This will cause an error to be reported if the table already exist and will prevent the ETL from proceeding past the object creation stage.
If set to ignore the tables are created with CREATE TABLE IF NOT EXISTS which will ignore any existing tables and assume that they are compatible with the rest of the ETL operation. This mode can be used to continuously load data from an external source into MariaDB.
If set to replace, the tables are created with CREATE OR REPLACE TABLE which will cause existing tables to be dropped if they exist. This is not a reversible process so caution should be taken when this mode is used.
catalog
The catalog for the tables. This is only used when type is set togeneric. In all other cases this value is ignored.
Here is an example payload that prepares the table test.t1 for extraction from a MariaDB server.
The token for the source connection is provided the same way it is provided for all other /v1/sql endpoints: in the token request parameter or in the cookies. The destination connection token is provided either in the target_token request parameter or as a cookie.
This endpoints supports the following additional request parameters.
target_token
The connection token for the destination connection. If provided, the value is unconditionally used even if a cookie with a valid token exists for the destination connection.
ETL operation prepared:
Status: 202 Accepted
Once complete, the /v1/sql/:id/queries/:query_id endpoint will return the following result.
Invalid payload or missing connection token:
Status: 400 Bad Request
The behavior of this endpoint is identical to the preparation but instead of preparing the operation, this endpoint will execute the prepared ETL and load the data into MariaDB.
The intended way of doing an ETL operation is to first prepare it using the/v1/sql/:id/etl/prepare endpoint to retrieve the SQL statements that define the ETL operation. Then if the ETL preparation is successful, thedata.attributes.results.tables value from the response is used as the tables value for the ETL start operation, done on the /v1/sql/:id/etl/start endpoint.
If any of the create, select or insert fields for a table in the tables list have not been defined, the SQL will be automatically generated by querying the source server, similarly to how the preparation generates the SQL statements. This means that the preparation step is optional if there is no need to adjust the automatically generated SQL.
The ETL operation can be canceled using the /v1/sql/:id/cancel endpoint which will roll back the ETL operation. Any tables that were created during the ETL operation are not deleted on the destination server and must be manually cleaned up.
If the ETL fails to extract the SQL from the source server or an error was encountered during table creation, the response will have the "ok" field set to false. Both the top-level object as well as the individual tables can have the "error" field set to the error message. This field is filled during the ETL operation which means errors are visible even if the ETL is still ongoing.
During the ETL operation, tables that have been fully processed will have a"execution_time" field. This field has the total time in seconds it took to execute the data loading step.
ETL operation started:
Status: 202 Accepted
Once complete, the /v1/sql/:id/queries/:query_id endpoint will return the following result.
Invalid payload or missing connection token:
Status: 400 Bad Request
This page is licensed: CC BY-SA / Gnu FDL
POST /v1/sql/query?token=eyJhbGciOiJIUzI1NiJ9.eyJhdWQiOiJhZG1pbiIsImV4cCI6MTU4MzI1NDE1MSwiaWF0IjoxNTgzMjI1MzUxLCJpc3MiOiJtYXhzY2FsZSJ9.B1BqhjjKaCWKe3gVXLszpOPfeu8cLiwSb4CMIJAoyqwGET /v1/sql/:id{
"data": {
"attributes": {
"seconds_idle": 0.0013705639999999999,
"sql": null,
"target": "server1",
"thread_id": 10
},
"id": "96be0ffe-10fb-4ed1-8e66-a17ef1eea0fe",
"links": {
"related": "http://localhost:8989/v1/sql/96be0ffe-10fb-4ed1-8e66-a17ef1eea0fe/queries/",
"self": "http://localhost:8989/v1/sql/96be0ffe-10fb-4ed1-8e66-a17ef1eea0fe/"
},
"type": "sql"
},
"links": {
"self": "http://localhost:8989/v1/sql/96be0ffe-10fb-4ed1-8e66-a17ef1eea0fe/"
}
}GET /v1/sql{
"data": [
{
"attributes": {
"seconds_idle": 0.0010341230000000001,
"sql": null,
"target": "server1",
"thread_id": 12
},
"id": "90761656-3352-420b-83e7-0dcef691552a",
"links": {
"related": "http://localhost:8989/v1/sql/90761656-3352-420b-83e7-0dcef691552a/queries/",
"self": "http://localhost:8989/v1/sql/90761656-3352-420b-83e7-0dcef691552a/"
},
"type": "sql"
},
{
"attributes": {
"seconds_idle": 0.002397377,
"sql": null,
"target": "server1",
"thread_id": 11
},
"id": "98a8b5c5-3632-4f0f-98bb-0dc440a3409a",
"links": {
"related": "http://localhost:8989/v1/sql/98a8b5c5-3632-4f0f-98bb-0dc440a3409a/queries/",
"self": "http://localhost:8989/v1/sql/98a8b5c5-3632-4f0f-98bb-0dc440a3409a/"
},
"type": "sql"
}
],
"links": {
"self": "http://localhost:8989/v1/sql/"
}
}POST /v1/sql{
"user": "jdoe",
"password": "my-s3cret",
"target": "server1",
"db": "test",
"timeout": 15
}{
"target": "odbc",
"connection_string": "Driver=MariaDB;SERVER=127.0.0.1;UID=maxuser;PWD=maxpwd"
}{
"data": {
"attributes": {
"seconds_idle": 7.6394000000000001e-5,
"sql": null,
"target": "server1",
"thread_id": 13
},
"id": "f4e38d96-99b4-479e-ac36-5f3b437aff99",
"links": {
"related": "http://localhost:8989/v1/sql/f4e38d96-99b4-479e-ac36-5f3b437aff99/queries/",
"self": "http://localhost:8989/v1/sql/f4e38d96-99b4-479e-ac36-5f3b437aff99/"
},
"type": "sql"
},
"links": {
"self": "http://localhost:8989/v1/sql/f4e38d96-99b4-479e-ac36-5f3b437aff99/"
},
"meta": {
"token": "eyJhbGciOiJIUzI1NiJ9.eyJhdWQiOiJmNGUzOGQ5Ni05OWI0LTQ3OWUtYWMzNi01ZjNiNDM3YWZmOTkiLCJleHAiOjE2ODk5NTA4MDQsImlhdCI6MTY4OTkyMjAwNCwiaXNzIjoibXhzLXF1ZXJ5Iiwic3ViIjoiZjRlMzhkOTYtOTliNC00NzllLWFjMzYtNWYzYjQzN2FmZjk5In0.gCKYl7XwwnMLjJbQT6UShDuK8aJ6gessmredQ1i0On4"
}
}DELETE /v1/sql/:idPOST /v1/sql/:id/reconnectPOST /v1/sql/:id/clonePOST /v1/sql/:id/queries{
"sql": "SELECT * FROM test.t1",
"max_rows": 1000
}{
"data": {
"attributes": {
"execution_time": 0.00028492799999999999,
"results": [
{
"complete": true,
"data": [
[
1
],
[
2
],
[
3
]
],
"fields": [
"id"
],
"metadata": [
{
"catalog": "def",
"decimals": 0,
"length": 11,
"name": "id",
"schema": "test",
"table": "t1",
"type": "LONG"
}
]
}
],
"sql": "SELECT id FROM test.t1"
},
"id": "b7243d92-5bc6-4814-80fb-6772831ead4b.1",
"type": "queries"
},
"links": {
"self": "http://localhost:8989/v1/sql/b7243d92-5bc6-4814-80fb-6772831ead4b/queries/b7243d92-5bc6-4814-80fb-6772831ead4b.1/"
}
}{
"data": {
"attributes": {
"execution_time": 0.00012686699999999999,
"results": [
{
"errno": 1064,
"message": "You have an error in your SQL syntax; check the manual that corresponds to your MariaDB server version for the right syntax to use near 'TABLE test.t1' at line 1",
"sqlstate": "42000"
}
],
"sql": "SELECT syntax_error FROM TABLE test.t1"
},
"id": "621bacd9-48fd-436c-afda-b4e4d0d7b228.1",
"type": "queries"
},
"links": {
"self": "http://localhost:8989/v1/sql/621bacd9-48fd-436c-afda-b4e4d0d7b228/queries/621bacd9-48fd-436c-afda-b4e4d0d7b228.1/"
}
}{
"data": {
"attributes": {
"execution_time": 0.000474659,
"results": [
{
"affected_rows": 0,
"last_insert_id": 0,
"warnings": 0
}
],
"sql": "CREATE TABLE test.my_table(id INT)"
},
"id": "60005d40-c034-4aa3-94de-b15c14d9c91c.1",
"type": "queries"
},
"links": {
"self": "http://localhost:8989/v1/sql/60005d40-c034-4aa3-94de-b15c14d9c91c/queries/60005d40-c034-4aa3-94de-b15c14d9c91c.1/"
}
}{
"data": {
"attributes": {
"execution_time": 0.00014767200000000001,
"results": [
{
"complete": true,
"data": [
[
1
]
],
"fields": [
"1"
],
"metadata": [
{
"catalog": "def",
"decimals": 0,
"length": 1,
"name": "1",
"schema": "",
"table": "",
"type": "LONG"
}
]
}
],
"sql": "SELECT 1"
},
"id": "5999b711-d190-4f0e-8322-db3ce3bd97a2.1",
"type": "queries"
},
"links": {
"self": "http://localhost:8989/v1/sql/5999b711-d190-4f0e-8322-db3ce3bd97a2/queries/5999b711-d190-4f0e-8322-db3ce3bd97a2.1/"
}
}{
"data": {
"attributes": {
"execution_time": 0.0,
"sql": "SELECT 1"
},
"id": "3d23f7e0-6a83-4282-94a5-8a1089d56f72.1",
"type": "queries"
},
"links": {
"self": "http://localhost:8989/v1/sql/3d23f7e0-6a83-4282-94a5-8a1089d56f72/queries/3d23f7e0-6a83-4282-94a5-8a1089d56f72.1/"
}
}GET /v1/sql/:id/queries/:query_id{
"data": {
"attributes": {
"execution_time": 0.00011945,
"results": [
{
"complete": true,
"data": [
[
1
]
],
"fields": [
"1"
],
"metadata": [
{
"catalog": "def",
"decimals": 0,
"length": 1,
"name": "1",
"schema": "",
"table": "",
"type": "LONG"
}
]
}
],
"sql": "SELECT 1"
},
"id": "63ec5e96-2bfa-40a9-b631-425b4e3e993c.1",
"type": "queries"
},
"links": {
"self": "http://localhost:8989/v1/sql/63ec5e96-2bfa-40a9-b631-425b4e3e993c/queries/63ec5e96-2bfa-40a9-b631-425b4e3e993c.1/"
}
}DELETE /v1/sql/:id/queries/:query_idPOST /v1/sql/:id/cancelGET /v1/sql/odbc/drivers{
"data": [
{
"attributes": {
"description": "ODBC for MariaDB",
"driver": "/usr/lib/libmaodbc.so",
"driver64": "/usr/lib64/libmaodbc.so",
"fileusage": "1"
},
"id": "MariaDB",
"type": "drivers"
}
],
"links": {
"self": "http://localhost:8989/v1/sql/odbc/drivers/"
}
}POST /v1/sql/:id/etl/prepare- `mariadb`
Extract data from a MariaDB database.
- `postgresql`
Extract data from a PostgreSQL database. This requires that the PostgreSQL
ODBC driver is installed on the MaxScale server. This driver is often
available in the package manager of your operating system.
- `generic`
Extract data from a generic ODBC source. This uses the ODBC catalog
functions to determine the table layout. The results provided by this are
not as accurate as the specialized versions but it can serve as a good
starting point from which manual modifications to the SQL can be done.
This ETL type requires that the table catalog is provided at the top level
with the `catalog` field. The meaning of the catalog differs between
database implementations.{
"type": "mariadb",
"target": "e2a56d2f-6514-4926-8dba-dca0c4ae3a86",
"tables": [
{
"table": "t1",
"schema": "test"
}
]
}{
"data": {
"attributes": {
"execution_time": 0.0062226729999999997,
"results": {
"ok": true,
"stage": "prepare",
"tables": [
{
"create": "CREATE DATABASE IF NOT EXISTS `test`;\nUSE `test`;\nCREATE TABLE `t1` (\n `id` bigint(20) unsigned NOT NULL AUTO_INCREMENT,\n `data` varchar(255) DEFAULT NULL,\n UNIQUE KEY `id` (`id`)\n) ENGINE=InnoDB AUTO_INCREMENT=2 DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci",
"insert": "INSERT INTO `test`.`t1` (`id`,`data`) VALUES (?,?)",
"schema": "test",
"select": "SELECT `id`,`data` FROM `test`.`t1`",
"table": "t1"
}
]
},
"sql": "ETL"
},
"id": "31dc09b7-ec09-4e6d-b098-e925f706233c.1",
"type": "queries"
},
"links": {
"self": "http://localhost:8989/v1/sql/31dc09b7-ec09-4e6d-b098-e925f706233c/queries/31dc09b7-ec09-4e6d-b098-e925f706233c.1/"
}
}POST /v1/sql/:id/etl/start{
"data": {
"attributes": {
"execution_time": 0.0094386039999999997,
"results": {
"ok": true,
"stage": "load",
"tables": [
{
"create": "CREATE DATABASE IF NOT EXISTS `test`;\nUSE `test`;\nCREATE TABLE `t1` (\n `id` bigint(20) unsigned NOT NULL AUTO_INCREMENT,\n `data` varchar(255) DEFAULT NULL,\n UNIQUE KEY `id` (`id`)\n) ENGINE=InnoDB AUTO_INCREMENT=2 DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci",
"execution_time": 0.0033923809999999999,
"insert": "INSERT INTO `test`.`t1` (`id`,`data`) VALUES (?,?)",
"rows": 1,
"schema": "test",
"select": "SELECT `id`,`data` FROM `test`.`t1`",
"table": "t1"
}
]
},
"sql": "ETL"
},
"id": "1391b67e-58a7-4be3-b686-2498cb3a0e06.1",
"type": "queries"
},
"links": {
"self": "http://localhost:8989/v1/sql/1391b67e-58a7-4be3-b686-2498cb3a0e06/queries/1391b67e-58a7-4be3-b686-2498cb3a0e06.1/"
}
}Understand the fundamentals of the MaxScale REST API. This guide details API versioning, JSON Web Token authentication, and the standard JSON response format.
This document describes the version 1 of the MaxScale REST API.
Although JSON does not define a syntax for comments, some of the JSON examples have C-style inline comments in them. These comments use // to mark the start of the comment and extend to the end of the current line.
Read the section of the configuration guide for more details on how to configure the REST API.
The MaxScale REST API uses authentication with the MaxScale administrative interface users. The default user is admin:mariadb.
It is highly recommended to enable HTTPS on the MaxScale REST API to make the communication between the client and MaxScale secure. Without it, the passwords can be intercepted from the network traffic. Refer to the for more details on how to enable HTTPS for the MaxScale REST API.
For more details on how administrative interface users are created and managed, refer to the documentation as well as the documentation of the resource.
MaxScale supports authentication via .
The /v1/auth endpoint can be used to generate new tokens which are returned in the following form.
Note that by default the /auth endpoint requires the connection to be encrypted (HTTPS) and attempts to use it without encryption will be treated as an error. To allow use of the /auth endpoint without encryption, use admin_secure_gui=false.
If the token is used to authenticate users in a web browser, the token can be optionally stored in cookies. This can be enabled with the persist=yes parameter in the request:
When the token is stored in the cookies, it will be stored in the maxscale_token cookie using the SameSite=Strict and HttpOnly cookie options. This means the JavaScript context of the browser will not have access to it. This is done to prevent CSRF attacks.
To log out and clear the HttpOnly cookies from a browser, the same /v1/auth endpoint can be used with the logout=true parameter:
By default, the generated tokens are valid for 8 hours. The token validity period can be set with the max-age request parameter:
When max-age is combined with persist, the Max-Age cookie option is also set to the same value.
The maximum lifetime of the tokens is controlled by the admin_jwt_max_age parameter. If the configured value is less than 8 hours, the default token lifetime is also lowered to it. A request for a token with a lifetime longer than admin_jwt_max_age will be accepted but the token will have its lifetime set to admin_jwt_max_age.
To use the token for authentication, the generated token must be presented in the Authorization header with the Bearer authentication scheme. For example, the token above would be used in the following manner:
If MaxScale is restarted, all generated tokens are invalidated.
/auth Request ParametersThe /auth endpoint supports the following request parameters that must be given in the HTTP query string.
max-age
Sets the token maximum age in seconds. The default is max-age=28800. Only positive values between 1 and 2147483646 are accepted and if a non-positive or a non-integer value is found, the parameter is ignored.
persist
/whoami EndpointThe /whoami endpoint can be used to request the JSON description of the JWT payload contents. This is useful when used in the web browser which does not have access to the token itself but may still find the information in the payload to be useful.
MaxScale implements support for OpenID Connect for authentication of REST-API clients. MaxScale implements both the Code Flow and the Implicit Flows from OpenID Connect.
The OpenID Connect server is defined using the admin_oidc_url setting and the credentials used to access it are defined using admin_oidc_client_id and admin_oidc_client_secret.
MaxScale uses the admin_jwt_issuer as the client_id in all OpenID Connect requests unless admin_oidc_client_id has been defined.
The account and permissions values of the generated JWT for the REST-API client are extracted from the ID token and access tokens that are sent at the end of the OpenID Connect authentication process and the contents of the userinfo endpoint that's accessed using the access token.
To define the permissions of an externally authenticated user, the OpenID Connect identity provider must be able to define custom claims in the JWT. The exact method of doing this depends on the identity provider.
If the permissions field is present and it is an array of strings that defines at least one valid , the values are expected to be the permissions of the user and they are used directly. If the permissions field is not present but the account field is, it is expected to be the name of a which is then used to authorize the user.
For example, with the following JWT payload, the permissions of the user are read from the permissions field, which in this case are edit and view, and the account name is taken from the account field. The account in this case is only used for display purposes and if it's missing, the value external is used instead.
Whereas with the following JWT payload, the permissions of the user are from the admin role so changes to the role in MaxScale itself are reflected instantly in the user's permissions.
/loginIf MaxScale is configured with admin_oidc_url, the /login/ endpoint will redirect to the authorization_endpoint of the OpenID Connect server, otherwise it'll redirect to the /auth endpoint.
/logoutThe /logout endpoint redirects to the end_session_endpoint of the OpenID Connect server which is used to sign out the user from all services. If admin_oidc_url has not been configured, the endpoint simply clears all authentication cookies and returns a 200 OK response.
/.well-defined/openid-configurationThe /.well-defined/openid-configuration endpoint retrieves the OpenID Connect configuration which has links to the authorization endpoint /authorize, the end session endpoint /logout and the JWKS endpoint /jwks. The have_sso field in the response is a custom value that MaxScale exposes to indicate whether the /login and /logout endpoints cause a redirect, i.e. whether admin_oidc_url has been configured.
/authorizeThe /authorize endpoint implements the OAuth 2 endpoint for authorization.
The scope must contain the value open_id and the response_type must be either id_token for the Implicit Flow or code for the Code Flow. If a nonce value is provided, it is added to the generated JWT under the nonce claim.
In the redirect response for the Implicit Flow, id_token contains the generated JWT and token_type is always set to bearer. The expires_invalue contains the lifetime of the generated JWT. If astate` value was given, it is included in the redirect response.
/jwksThe /jwks endpoint returns the REST-API public keys in JWKS form, as specified by OpenID Connect.
The MaxScale REST API provides the following resources. All resources conform to the specification.
In addition to the named resources, the REST API will respond with a HTTP 200 OK response to GET requests on the root resource (/) as well as the namespace root resource (/v1/). These can be used for HTTP health checks to determine whether MaxScale is running.
All of the current resources are in the /v1/ namespace of the MaxScale REST API. Further additions to the namespace can be added that do not break backwards compatibility of any existing resources. What this means in practice is that:
No resources or URLs will be removed
The API will be JSON API compliant
Note that this means that the contents of individual resources can change. New fields can be added, old ones can be removed and the meaning of existing fields can change. The aim is to be as backwards compatible as reasonably possible without sacrificing the clarity and functionality of the API.
Since MaxScale 2.4.0, the use of the version prefix /v1/ is optional: if the prefix is not used, the latest API version is used.
All resources return complete JSON objects. The returned objects can have a relationships field that represents any relations the object has to other objects. This closely resembles the JSON API definition of links.
In the relationships objects, all resources have a self link that points to the resource itself. This allows easy access to the objects pointed by the relationships as the reply URL is included in the response itself.
To create a relationship between two objects, define it in the initial POST request. To modify the relationships of existing objects, perform a PATCH request with the new definition of the relevant relationship. To completely remove all relationships from an object, the data field of the corresponding relationship object must be set to an empty array.
The following lists the resources and the types of links each resource can have in addition to the self link. Examples of these relationships can be seen in the resource documentation.
services - Service resource
servers
List of servers used by the service
services
List of services used by the service
All parameters that use boolean values use the same rules that are used for the in the MaxScale configuration. For example, both pretty=off and pretty=false disable the pretty option.
All the resources that return JSON content also support the following parameters. Parameters are given in the HTTP query string: https://localhost:8989/v1/servers?pretty=true&fields[servers]=state.
pretty
Pretty-print output.
If this parameter is set to true then the returned objects are formatted in a more human readable format. If the parameter is set to false then the returned objects are formatted in a compact format. All resources support this parameter. The default value for this parameter is true.
MaxScale 24.02 added support for expressions in the filter request parameter. Each resource in a resource collection that evaluates to a true value will be kept in the returned result. All rows that evaluate to false are removed.
Equality and inequality is defined for all JSON types but ordering is defined only for numbers and strings. The logical operators allow one or more sub-expressions.
The following table lists the supported operations in the filter expressions. In it, the stored value is marked as S and the literal JSON value in the expression as V. For the logical operators, the sub-expression is marked as expr.
Ranges of values can be defined using an and() expression with the range limits defined with the ordering operators ge() and le(). To filter the sessions in MaxScale to ones that have an ID between 50 and 100, the following filtering expression can be used.
Limiting the result to only the given values can be done with an or() expression that uses eq() expressions to select the rows to return. To only return sessions with IDs 1, 5, 10 the following filtering expression can be used.
Similarly, excluding certain rows from the result can be done by simply replacing or() with not(). This expression would exclude sessions with the IDs 1, 5 and 10 from the result.
REST makes use of the HTTP protocols in its aim to provide a natural way to understand the workings of an API. The following request headers are understood by this API.
Credentials for authentication. This header should consist of a HTTP Basic Access authentication type payload which is the base64 encoded value of the username and password joined by a colon e.g. Base64("maxuser:maxpwd").
All PUT and POST requests must use the Content-Type: application/json media type and the request body must be a complete and valid JSON representation of a resource. All PATCH requests must use the Content-Type: application/json media type and the request body must be a JSON document containing a partial definition of the modified resource.
The address and port of the server.
The request is performed only if the provided ETag value matches the one on the server. This field should be used with PATCH requests to prevent concurrent updates to the same resource.
The value of this header must be a value from the ETag header retrieved from the same resource at an earlier point in time.
If the content has not changed the server responds with a 304 status code. If the content has changed the server responds with a 200 status code and the requested resource.
The value of this header must be a date value in the format.
If the content has not changed the server responds with a 304 status code. If the content has changed the server responds with a 200 status code and the requested resource.
The value of this header must be a value from the ETag header retrieved from the same resource at an earlier point in time.
The request is performed only if the requested resource has not been modified since the provided date.
The value of this header must be a date value in the format.
Some clients only support GET and PUT requests. By providing the string value of the intended method in the X-HTTP-Method-Override header, a client can, for example, perform a POST, PATCH or DELETE request with the PUT method (e.g. X-HTTP-Method-Override: PATCH).
If this header is defined in the request, the current method of the request is replaced with the one in the header. The HTTP method must be in uppercase and it must be one of the methods that the requested resource supports.
All resources return the Allow header with the supported HTTP methods. For example the resource /services will always return the Accept: GET, PATCH, PUT header.
All PATCH capable resources return the Accept-Patch: application/json-patch header.
Returns the RFC 1123 standard form date when the reply was sent. The date is in English and it uses the server's local timezone.
An identifier for a specific version of a resource. The value of this header changes whenever a resource is modified via the REST API. It will not change if an internal MaxScale event (e.g. server changing state or statistics being updated) causes a change.
When the client sends the If-Match or If-None-Match header, the provided value should be the value of the ETag header of an earlier GET.
The date when the resource was last modified in "HTTP-date" format.
If an out of date resource location is requested, a HTTP return code of 3XX with the Location header is returned. The value of the header contains the new location of the requested resource as a relative URI.
The requested authentication method. For example, WWW-Authenticate: Basic would require basic HTTP authentication.
This header is used for sending generic warnings to clients about actions that were successful and valid but could cause problems in the future. Currently these are used to indicate when a configuration change was made to a static object and an overriding configuration is created or when a static object is being deleted at runtime.
The content of the header is the human-readable warning that should be displayed to a user.
Every HTTP response starts with a line with a return code which indicates the outcome of the request. The API uses some of the standard HTTP values:
200 OK
Successful HTTP requests, response has a body.
201 Created
A new resource was created.
This class of status code indicates the client must take additional action to complete the request.
301 Moved Permanently
This and all future requests should be directed to the given URI.
302 Found
The response to the request can be found under another URI using the same method as in the original request.
The 4xx class of status code is when the client seems to have erred. Except when responding to a HEAD request, the body of the response MAY contains a JSON representation of the error.
The error field contains a short error description and the description field contains a more detailed version of the error message.
400 Bad Request
The server cannot or will not process the request due to client error.
401 Unauthorized
Authentication is required. The response includes a WWW-Authenticate header.
The server failed to fulfill an apparently valid request.
500 Internal Server Error
A generic error message, given when an unexpected condition was encountered and no more specific message is suitable.
501 Not Implemented
The server either does not recognize the request method, or it lacks the ability to fulfill the request.
The following response headers are not currently in use. Future versions of the API could return them.
206 Partial Content
The server is delivering only part of the resource (byte serving) due to a range header sent by the client.
300 Multiple Choices
Indicates multiple options for the resource from which the client may choose (via agent-driven content negotiation).
This page is licensed: CC BY-SA / Gnu FDL
Store the generated token in cookies instead of returning it as the response body.
This parameter expects only one value, yes, as its argument. When persist=yes is set, the token is stored in the maxscale_token cookie and the response is 204 No Content instead of 200 OK.
The maxscale_token cookie contains the JWT and is stored as a HttpOnly cookie which prevents access to from JavaScript. This is done to mitigate any attacks that might leak the token.
filters
List of filters used by the service
NOTE: This is an ordered relationship where the order of the filters defines the order in which they process queries.
listeners
List of listeners used by the service
monitors - Monitor resource
servers
List of servers used by the monitor
filters - Filter resource
services
List of services that use this filter
NOTE: This is a one-way relationship that can only be modified from the services resource.
servers - Server resource
services
List of services that use this server
monitors
List of monitors that use this server
listeners - Listener resource
services
The service that the listener points to
fields[TYPE]=field1,field2...
Return a Sparse Fieldset
This parameter controls which fields are returned in the REST API response. The TYPE value in the fields parameter must be the resource type that is being retrieved (i.e. the servers in /v1/servers and /v1/server/server1). The value of the parameter must be a comma-separated list of JSON Pointers that mark which fields of the object to return. Only fields in objects in the attributes and relationships objects are inspected. This means that if the path marked by the JSON Pointer contains an array in it, it will not advance past this array.
For example, to return only the server state output from the /servers endpoint, the fields[servers]=state parameter can be used. This would return only the data.attributes.state part of the resource. To return the nested value data.attributes.statistics.connections, the corresponding parameter would be fields[servers]=statistics/connections.
filter=json_ptr=expr
Filter the output of the result
This parameter controls which rows are returned in a REST API response that returns an array in the data member (i.e. a request to a resource collection). Requests to individual resources are not filtered.
The argument to the filter parameter must be a key-value pair with a valid JSON Pointer as the key and either a valid JSON type as the value or a filter-expression. The comparison is done for each individual object in the data array of the result. If given only a JSON value, the stored value is compared for equality. If an expression is used, the expression is evaluated and only rows that match are returned.
For example, if the object stored in data[0] has a value pointed by the given JSON pointer and that value compares equal to the given JSON value, the array row is kept in the result. Examples for filtering expression can be found .
A practical use for this parameter is to return only sessions for a particular service. For example, to return sessions for the RW-Split-Router service, the filter=/relationships/services/data/0/id="RW-Split-Router" parameter can be used. Note the double quotes around the "RW-Split-Router", they are required to correctly convert strings into JSON values.
filter[json_path]=expr
Filter based on a JSONPath and a filtering expression.
Similar to the filter parameter that takes a JSON Pointer, this version of the filter controls which rows are returned in a REST API response for a resource collection. Requests to individual resources are never filtered.
The value inside the brackets must be a valid JSONPath expression that MaxScale supports. The currently supported syntax is:
dot notation: $.store.book
bracket notation: $['store']['book']
array values: $.store.book[0]
multiple array values: $.store.book[0,1,2]
array wildcards: $.store.book[*].price
object wildcards: $.store.bicycle.*
optional root object: store.book
The root object being optional is an extension to the JSONPath specification that MaxScale implements.
The expr value must be a . Similarly to the other filter parameter, the comparison is done for each individual object in the data array of the result.
If the JSONPath expression returns multiple objects, the comparison is done for each element and if any of them matches, the object is considered to match. In other words, wildcard JSONPath expressions are ORed together.
If multiple filter[json_path]=expr parameters are found in the request, all returned values must match all of them. In other words, the filter parameters are all combined into an AND expression. For example, the following filter will only return all values whose id field is "srv1 and the attributes.parameters.port field is 3306: filter[id]=eq("srv1")&filter[attributes.parameters.port]=eq(3306)
page[size]
The number of elements that are returned for resource collections. By default all elements in the resource collection are returned. The value must be a valid positive integer, otherwise the parameter is ignored. If pagination is used, the links object will have pagination links to the next page if more elements are available.
page[number]
How many pages of results to skip. The first page of results starts from 0 and each page has no more than page[size] elements. If defined, page[size] must also be defined, otherwise this parameter is ignored. This should be considered pseudo-pagination as the results are not guaranteed to be consistent between requests.
sync
Control configuration synchronization.
If this parameter is set to false then the configuration synchronization is disabled for this request. This can be used to perform configuration changes when MaxScale is unable to reach the cluster used to synchronize the configuration. The modifications to the local configuration will be overwritten when the next modification to the cluster's configuration is done which means this should only be used to perform temporary fixes.
ge(json)
S >= V
Numbers and strings
gt(json)
S > V
Numbers and strings
and(expr...)
expr && expr
Expressions
or(expr...)
expr || expr
Expressions
not(expr...)
!expr
Expressions
202 Accepted
The request has been accepted for processing, but the processing has not been completed.
204 No Content
Successful HTTP requests, response has no body.
303 See Other
The response to the request can be found under another URI using a GET method.
304 Not Modified
Indicates that the resource has not been modified since the version specified by the request headers If-Modified-Since or If-None-Match.
307 Temporary Redirect
The request should be repeated with another URI but future requests should use the original URI.
308 Permanent Redirect
The request and all future requests should be repeated using another URI.
403 Forbidden
The request was a valid request, but the client does not have the necessary permissions for the resource.
404 Not Found
The requested resource could not be found.
405 Method Not Allowed
A request method is not supported for the requested resource.
406 Not Acceptable
The requested resource is capable of generating only content not acceptable according to the Accept headers sent in the request.
409 Conflict
Indicates that the request could not be processed because of conflict in the request, such as an edit conflict be tween multiple simultaneous updates.
411 Length Required
The request did not specify the length of its content, which is required by the requested resource.
412 Precondition Failed
The server does not meet one of the preconditions that the requester put on the request.
413 Payload Too Large
The request is larger than the server is willing or able to process.
414 URI Too Long
The URI provided was too long for the server to process.
415 Unsupported Media Type
The request entity has a media type which the server or resource does not support.
422 Unprocessable Entity
The request was well-formed but was unable to be followed due to semantic errors.
423 Locked
The resource that is being accessed is locked.
428 Precondition Required
The origin server requires the request to be conditional. This error code is returned when none of the Modified-Since or Match type headers are used.
431 Request Header Fields Too Large
The server is unwilling to process the request because either an individual header field, or all the header fields collectively, are too large.
502 Bad Gateway
The server was acting as a gateway or proxy and received an invalid response from the upstream server.
503 Service Unavailable
The server is currently unavailable (because it is overloaded or down for maintenance). Generally, this is a temporary state.
504 Gateway Timeout
The server was acting as a gateway or proxy and did not receive a timely response from the upstream server.
505 HTTP Version Not Supported
The server does not support the HTTP protocol version used in the request.
506 Variant Also Negotiates
Transparent content negotiation for the request results in a circular reference.
507 Insufficient Storage
The server is unable to store the representation needed to complete the request.
508 Loop Detected
The server detected an infinite loop while processing the request (sent in lieu of 208 Already Reported).
510 Not Extended
Further extensions to the request are required for the server to fulfil it.
407 Proxy Authentication Required
The client must first authenticate itself with the proxy.
408 Request Timeout
The server timed out waiting for the request. According to HTTP specifications: "The client did not produce a request within the time that the server was prepared to wait. The client MAY repeat the request without modifications at any later time."
410 Gone
Indicates that the resource requested is no longer available and will not be available again.
416 Range Not Satisfiable
The client has asked for a portion of the file (byte serving), but the server cannot supply that portion.
417 Expectation Failed
The server cannot meet the requirements of the Expect request-header field.
421 Misdirected Request
The request was directed at a server that is not able to produce a response.
424 Failed Dependency
The request failed due to failure of a previous request.
426 Upgrade Required
The client should switch to a different protocol such as TLS/1.0, given in the Upgrade header field.
429 Too Many Requests
The user has sent too many requests in a given amount of time. Intended for use with rate-limiting schemes.
eq(json)
S == V
All JSON types
ne(json)
S != V
All JSON types
lt(json)
S < V
Numbers and strings
le(json)
S <= V
Numbers and strings
GET /v1/auth{
"meta": {
"token": "eyJhbGciOiJIUzI1NiJ9.eyJhY2NvdW50IjoiYWRtaW4iLCJhdWQiOiJhZG1pbiIsImV4cCI6MTc1MzQ4NzAzNywiaWF0IjoxNzUzNDU4MjM3LCJpc3MiOiJtYXhzY2FsZSIsImp0aSI6ImJjMGEwNDBmLWU2NGUtNDVlNC1hZTY3LWJkNjZjZGUzYTU3OSIsInBlcm1pc3Npb25zIjpbImFkbWluIiwiZWRpdCIsInNxbCIsInZpZXciXSwic3ViIjoiYWRtaW4ifQ.B1NjRHduQENNpJLFozfgim7xWAbqTSAPztcZOS9oCeU"
}
}GET /v1/auth?persist=yesGET /v1/auth?logout=yesGET /v1/auth?max-age=28800Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJhdWQiOiJhZG1pbiIsImV4cCI6MTU4MzI1NDE1MSwiaWF0IjoxNTgzMjI1MzUxLCJpc3MiOiJtYXhzY2FsZSJ9.B1BqhjjKaCWKe3gVXLszpOPfeu8cLiwSb4CMIJAoyqw{
"account": "admin",
"aud": "admin",
"exp": 1753487037,
"iat": 1753458237,
"iss": "maxscale",
"jti": "d036a4dc-512d-4916-9ee7-12773e31eb87",
"permissions": [
"admin",
"edit",
"sql",
"view"
],
"sub": "admin"
}{
"account": "manager",
"permissions": [
"edit",
"view"
],
"aud": "maxscale",
"exp": 1753487037,
"iat": 1753458237,
"iss": "www.mariadb.com",
"sub": "foo"
}{
"account": "admin",
"aud": "maxscale",
"exp": 1753487037,
"iat": 1753458237,
"iss": "www.mariadb.com",
"sub": "foo"
}filter=id=and(ge(50),le(100))filter=id=or(eq(1),eq(5),eq(10))filter=id=not(eq(1),eq(5),eq(10)){
"error": {
"detail" : "The new `/servers/` resource is missing the `port` parameter"
}
}Administer backend database servers. Use this resource to add, remove, or modify server definitions and view their current runtime state and statistics.
A server resource represents a backend database server.
The :name in all of the URIs must be the name of a server in MaxScale.
Get a single server.
Status: 200 OK
Response contains a resource collection with all servers.
Status: 200 OK
The :type in the URI must be either services, for service relationships, or monitors, for monitor relationships.
Status: 200 OK
Create a new server by defining the resource. The posted object must define at least the following fields.
data.id
Name of the server
data.type
The following is the minimal required JSON object for defining a new server.
The relationships of a server can also be defined at creation time. This allows new servers to be created and immediately taken into use.
Refer to the for a full list of server parameters.
Server created:
Status: 204 No Content
Invalid JSON body:
Status: 400 Bad Request
The request body must be a valid JSON document representing the modified server.
In addition to the server , the services and monitors fields of the relationships object can be modified. Removal, addition and modification of the links will change which service and monitors use this server.
For example, removing the first value in the services list in the relationships object from the following JSON document will remove the server1 from the service RW-Split-Router.
Removing a service from a server is analogous to removing the server from the service. Both unlink the two objects from each other.
Request for PATCH /v1/servers/server1 that modifies the address of the server:
Request for PATCH /v1/servers/server1 that modifies the server relationships:
If parts of the resource are not defined (e.g. the attributes field in the above example), those parts of the resource are not modified. All parts that are defined are interpreted as the new definition of those part of the resource. In the above example, the relationships of the resource are completely redefined.
Server modified:
Status: 204 No Content
Invalid JSON body:
Status: 400 Bad Request
The :type in the URI must be either services, for service relationships, or monitors, for monitor relationships.
The request body must be a JSON object that defines only the data field. The value of the data field must be an array of relationship objects that define the id and type fields of the relationship. This object will replace the existing relationships of the particular type from the server.
The following is an example request and request body that defines a single service relationship for a server.
All relationships for a server can be deleted by sending an empty array as the data field value. The following example removes the server from all services.
Server relationships modified:
Status: 204 No Content
Invalid JSON body:
Status: 400 Bad Request
A server can only be deleted if it is not used by any services or monitors.
This endpoint also supports the force=yes parameter that will unconditionally delete the server by first unlinking it from all services and monitors that use it.
Server is destroyed:
Status: 204 No Content
Server is in use:
Status: 400 Bad Request
This endpoint requires that the state parameter is passed with the request. The value of state must be one of the following values.
For example, to set the server db-server-1 into maintenance mode, a request to the following URL must be made:
This endpoint also supports the force=yes parameter that will cause all connections to the server to be closed if state=maintenance is also set. By default setting a server into maintenance mode will cause connections to be closed only after the next request is sent.
The following example forcefully closes all connections to server db-server-1 and sets it into maintenance mode:
Server state modified:
Status: 204 No Content
Missing or invalid parameter:
Status: 400 Bad Request
This endpoint requires that the state parameter is passed with the request. The value of state must be one of the values defined in the set endpoint documentation.
Server state modified:
Status: 204 No Content
Missing or invalid parameter:
Status: 400 Bad Request
This page is licensed: CC BY-SA / Gnu FDL
serversdata.attributes.parameters.port
The port to use. Needs to be defined if the address field is defined.
master
Server is a Master
slave
Server is a Slave
maintenance
Server is put into maintenance
running
Server is up and running
synced
Server is a Galera node
drain
Server is drained of connections
GET /v1/servers/:name{
"data": {
"attributes": {
"gtid_binlog_pos": "0-3000-8",
"gtid_current_pos": "0-3000-8",
"last_event": "master_up",
"lock_held": null,
"master_group": null,
"master_id": -1,
"name": "server1",
"node_id": 3000,
"parameters": {
"address": "127.0.0.1",
"disk_space_threshold": "",
"extra_port": 0,
"initial_status": "down",
"max_routing_connections": 0,
"monitorpw": null,
"monitoruser": null,
"persistmaxtime": "0ms",
"persistpoolmax": 0,
"port": 3000,
"priority": 0,
"private_address": null,
"proxy_protocol": false,
"rank": "primary",
"replication_custom_options": null,
"socket": null,
"ssl": false,
"ssl_ca": null,
"ssl_cert": null,
"ssl_cert_verify_depth": 9,
"ssl_cipher": null,
"ssl_key": null,
"ssl_passphrase": "",
"ssl_verify_peer_certificate": false,
"ssl_verify_peer_host": false,
"ssl_version": "MAX",
"use_service_credentials": true
},
"read_only": false,
"replication_lag": 0,
"server_id": 3000,
"slave_connections": [],
"source": {
"file": "/etc/maxscale.cnf",
"type": "static"
},
"state": "Master, Running",
"statistics": {
"active_operations": 0,
"adaptive_avg_select_time": "0ns",
"connection_pool_empty": 0,
"connections": 1,
"failed_auths": 0,
"max_connections": 1,
"max_pool_size": 0,
"persistent_connections": 0,
"response_time_distribution": {
"read": {
"distribution": [
{
"count": 0,
"time": "0.000001",
"total": 0.0
},
{
"count": 0,
"time": "0.000010",
"total": 0.0
},
{
"count": 0,
"time": "0.000100",
"total": 0.0
},
{
"count": 0,
"time": "0.001000",
"total": 0.0
},
{
"count": 0,
"time": "0.010000",
"total": 0.0
},
{
"count": 0,
"time": "0.100000",
"total": 0.0
},
{
"count": 0,
"time": "1.000000",
"total": 0.0
},
{
"count": 0,
"time": "10.000000",
"total": 0.0
},
{
"count": 0,
"time": "100.000000",
"total": 0.0
},
{
"count": 0,
"time": "1000.000000",
"total": 0.0
},
{
"count": 0,
"time": "10000.000000",
"total": 0.0
},
{
"count": 0,
"time": "100000.000000",
"total": 0.0
}
],
"operation": "read",
"range_base": 10
},
"write": {
"distribution": [
{
"count": 0,
"time": "0.000001",
"total": 0.0
},
{
"count": 0,
"time": "0.000010",
"total": 0.0
},
{
"count": 0,
"time": "0.000100",
"total": 0.0
},
{
"count": 4,
"time": "0.001000",
"total": 0.001319181
},
{
"count": 0,
"time": "0.010000",
"total": 0.0
},
{
"count": 0,
"time": "0.100000",
"total": 0.0
},
{
"count": 0,
"time": "1.000000",
"total": 0.0
},
{
"count": 0,
"time": "10.000000",
"total": 0.0
},
{
"count": 0,
"time": "100.000000",
"total": 0.0
},
{
"count": 0,
"time": "1000.000000",
"total": 0.0
},
{
"count": 0,
"time": "10000.000000",
"total": 0.0
},
{
"count": 0,
"time": "100000.000000",
"total": 0.0
}
],
"operation": "write",
"range_base": 10
}
},
"reused_connections": 0,
"routed_packets": 4,
"routed_reads": 0,
"routed_writes": 4,
"total_connections": 1
},
"status": {
"extra": "",
"mode": "Normal",
"reason": [
"Primary"
],
"state": "Write"
},
"triggered_at": "Fri, 25 Jul 2025 15:43:48 GMT",
"uptime": 15,
"version_string": "10.11.9-MariaDB-ubu2204-log"
},
"id": "server1",
"links": {
"self": "http://localhost:8989/v1/servers/server1/"
},
"relationships": {
"monitors": {
"data": [
{
"id": "MariaDB-Monitor",
"type": "monitors"
}
],
"links": {
"related": "http://localhost:8989/v1/monitors/",
"self": "http://localhost:8989/v1/servers/server1/relationships/monitors/"
}
},
"services": {
"data": [
{
"id": "RW-Split-Router",
"type": "services"
},
{
"id": "Read-Connection-Router",
"type": "services"
}
],
"links": {
"related": "http://localhost:8989/v1/services/",
"self": "http://localhost:8989/v1/servers/server1/relationships/services/"
}
}
},
"type": "servers"
},
"links": {
"self": "http://localhost:8989/v1/servers/server1/"
}
}GET /v1/servers{
"data": [
{
"attributes": {
"gtid_binlog_pos": "0-3000-8",
"gtid_current_pos": "0-3000-8",
"last_event": "master_up",
"lock_held": null,
"master_group": null,
"master_id": -1,
"name": "server1",
"node_id": 3000,
"parameters": {
"address": "127.0.0.1",
"disk_space_threshold": "",
"extra_port": 0,
"initial_status": "down",
"max_routing_connections": 0,
"monitorpw": null,
"monitoruser": null,
"persistmaxtime": "0ms",
"persistpoolmax": 0,
"port": 3000,
"priority": 0,
"private_address": null,
"proxy_protocol": false,
"rank": "primary",
"replication_custom_options": null,
"socket": null,
"ssl": false,
"ssl_ca": null,
"ssl_cert": null,
"ssl_cert_verify_depth": 9,
"ssl_cipher": null,
"ssl_key": null,
"ssl_passphrase": "",
"ssl_verify_peer_certificate": false,
"ssl_verify_peer_host": false,
"ssl_version": "MAX",
"use_service_credentials": true
},
"read_only": false,
"replication_lag": 0,
"server_id": 3000,
"slave_connections": [],
"source": {
"file": "/etc/maxscale.cnf",
"type": "static"
},
"state": "Master, Running",
"statistics": {
"active_operations": 0,
"adaptive_avg_select_time": "0ns",
"connection_pool_empty": 0,
"connections": 1,
"failed_auths": 0,
"max_connections": 1,
"max_pool_size": 0,
"persistent_connections": 0,
"response_time_distribution": {
"read": {
"distribution": [
{
"count": 0,
"time": "0.000001",
"total": 0.0
},
{
"count": 0,
"time": "0.000010",
"total": 0.0
},
{
"count": 0,
"time": "0.000100",
"total": 0.0
},
{
"count": 0,
"time": "0.001000",
"total": 0.0
},
{
"count": 0,
"time": "0.010000",
"total": 0.0
},
{
"count": 0,
"time": "0.100000",
"total": 0.0
},
{
"count": 0,
"time": "1.000000",
"total": 0.0
},
{
"count": 0,
"time": "10.000000",
"total": 0.0
},
{
"count": 0,
"time": "100.000000",
"total": 0.0
},
{
"count": 0,
"time": "1000.000000",
"total": 0.0
},
{
"count": 0,
"time": "10000.000000",
"total": 0.0
},
{
"count": 0,
"time": "100000.000000",
"total": 0.0
}
],
"operation": "read",
"range_base": 10
},
"write": {
"distribution": [
{
"count": 0,
"time": "0.000001",
"total": 0.0
},
{
"count": 0,
"time": "0.000010",
"total": 0.0
},
{
"count": 0,
"time": "0.000100",
"total": 0.0
},
{
"count": 4,
"time": "0.001000",
"total": 0.001319181
},
{
"count": 0,
"time": "0.010000",
"total": 0.0
},
{
"count": 0,
"time": "0.100000",
"total": 0.0
},
{
"count": 0,
"time": "1.000000",
"total": 0.0
},
{
"count": 0,
"time": "10.000000",
"total": 0.0
},
{
"count": 0,
"time": "100.000000",
"total": 0.0
},
{
"count": 0,
"time": "1000.000000",
"total": 0.0
},
{
"count": 0,
"time": "10000.000000",
"total": 0.0
},
{
"count": 0,
"time": "100000.000000",
"total": 0.0
}
],
"operation": "write",
"range_base": 10
}
},
"reused_connections": 0,
"routed_packets": 4,
"routed_reads": 0,
"routed_writes": 4,
"total_connections": 1
},
"status": {
"extra": "",
"mode": "Normal",
"reason": [
"Primary"
],
"state": "Write"
},
"triggered_at": "Fri, 25 Jul 2025 15:43:48 GMT",
"uptime": 15,
"version_string": "10.11.9-MariaDB-ubu2204-log"
},
"id": "server1",
"links": {
"self": "http://localhost:8989/v1/servers/server1/"
},
"relationships": {
"monitors": {
"data": [
{
"id": "MariaDB-Monitor",
"type": "monitors"
}
],
"links": {
"related": "http://localhost:8989/v1/monitors/",
"self": "http://localhost:8989/v1/servers/server1/relationships/monitors/"
}
},
"services": {
"data": [
{
"id": "RW-Split-Router",
"type": "services"
},
{
"id": "Read-Connection-Router",
"type": "services"
}
],
"links": {
"related": "http://localhost:8989/v1/services/",
"self": "http://localhost:8989/v1/servers/server1/relationships/services/"
}
}
},
"type": "servers"
},
{
"attributes": {
"gtid_binlog_pos": "0-3001-12",
"gtid_current_pos": "0-3001-12",
"last_event": "lost_slave",
"lock_held": null,
"master_group": null,
"master_id": 3000,
"name": "server2",
"node_id": 3001,
"parameters": {
"address": "127.0.0.1",
"disk_space_threshold": "",
"extra_port": 0,
"initial_status": "down",
"max_routing_connections": 0,
"monitorpw": null,
"monitoruser": null,
"persistmaxtime": "0ms",
"persistpoolmax": 0,
"port": 3001,
"priority": 0,
"private_address": null,
"proxy_protocol": false,
"rank": "primary",
"replication_custom_options": null,
"socket": null,
"ssl": false,
"ssl_ca": null,
"ssl_cert": null,
"ssl_cert_verify_depth": 9,
"ssl_cipher": null,
"ssl_key": null,
"ssl_passphrase": "",
"ssl_verify_peer_certificate": false,
"ssl_verify_peer_host": false,
"ssl_version": "MAX",
"use_service_credentials": true
},
"read_only": false,
"replication_lag": -1,
"server_id": 3001,
"slave_connections": [
{
"connection_name": "",
"gtid_io_pos": "",
"last_io_error": "",
"last_sql_error": "",
"master_host": "127.0.0.1",
"master_port": 3000,
"master_server_id": 3000,
"seconds_behind_master": null,
"slave_io_running": "No",
"slave_sql_running": "No",
"using_gtid": "No"
}
],
"source": {
"file": "/etc/maxscale.cnf",
"type": "static"
},
"state": "Running",
"statistics": {
"active_operations": 0,
"adaptive_avg_select_time": "0ns",
"connection_pool_empty": 0,
"connections": 0,
"failed_auths": 0,
"max_connections": 1,
"max_pool_size": 0,
"persistent_connections": 0,
"response_time_distribution": {
"read": {
"distribution": [
{
"count": 0,
"time": "0.000001",
"total": 0.0
},
{
"count": 0,
"time": "0.000010",
"total": 0.0
},
{
"count": 0,
"time": "0.000100",
"total": 0.0
},
{
"count": 1,
"time": "0.001000",
"total": 0.00066959099999999998
},
{
"count": 0,
"time": "0.010000",
"total": 0.0
},
{
"count": 0,
"time": "0.100000",
"total": 0.0
},
{
"count": 0,
"time": "1.000000",
"total": 0.0
},
{
"count": 0,
"time": "10.000000",
"total": 0.0
},
{
"count": 0,
"time": "100.000000",
"total": 0.0
},
{
"count": 0,
"time": "1000.000000",
"total": 0.0
},
{
"count": 0,
"time": "10000.000000",
"total": 0.0
},
{
"count": 0,
"time": "100000.000000",
"total": 0.0
}
],
"operation": "read",
"range_base": 10
},
"write": {
"distribution": [
{
"count": 0,
"time": "0.000001",
"total": 0.0
},
{
"count": 0,
"time": "0.000010",
"total": 0.0
},
{
"count": 0,
"time": "0.000100",
"total": 0.0
},
{
"count": 0,
"time": "0.001000",
"total": 0.0
},
{
"count": 0,
"time": "0.010000",
"total": 0.0
},
{
"count": 0,
"time": "0.100000",
"total": 0.0
},
{
"count": 0,
"time": "1.000000",
"total": 0.0
},
{
"count": 0,
"time": "10.000000",
"total": 0.0
},
{
"count": 0,
"time": "100.000000",
"total": 0.0
},
{
"count": 0,
"time": "1000.000000",
"total": 0.0
},
{
"count": 0,
"time": "10000.000000",
"total": 0.0
},
{
"count": 0,
"time": "100000.000000",
"total": 0.0
}
],
"operation": "write",
"range_base": 10
}
},
"reused_connections": 0,
"routed_packets": 1,
"routed_reads": 1,
"routed_writes": 0,
"total_connections": 1
},
"status": {
"extra": "",
"mode": "Normal",
"reason": [],
"state": "Up"
},
"triggered_at": "Fri, 25 Jul 2025 15:43:59 GMT",
"uptime": 14,
"version_string": "10.11.9-MariaDB-ubu2204-log"
},
"id": "server2",
"links": {
"self": "http://localhost:8989/v1/servers/server2/"
},
"relationships": {
"monitors": {
"data": [
{
"id": "MariaDB-Monitor",
"type": "monitors"
}
],
"links": {
"related": "http://localhost:8989/v1/monitors/",
"self": "http://localhost:8989/v1/servers/server2/relationships/monitors/"
}
},
"services": {
"data": [
{
"id": "RW-Split-Router",
"type": "services"
},
{
"id": "Read-Connection-Router",
"type": "services"
}
],
"links": {
"related": "http://localhost:8989/v1/services/",
"self": "http://localhost:8989/v1/servers/server2/relationships/services/"
}
}
},
"type": "servers"
}
],
"links": {
"self": "http://localhost:8989/v1/servers/"
}
}GET /v1/servers/:name/relationships/:type{
"data": [
{
"id": "MariaDB-Monitor",
"type": "monitors"
}
],
"links": {
"related": "http://localhost:8989/v1/monitors/",
"self": "http://localhost:8989/v1/servers/server1/relationships/monitors/"
}
}POST /v1/servers{
"data": {
"id": "server3",
"type": "servers",
"attributes": {
"parameters": {
"address": "127.0.0.1",
"port": 3003
}
}
}
}{
"data": {
"id": "server4",
"type": "servers",
"attributes": {
"parameters": {
"address": "127.0.0.1",
"port": 3002
}
},
"relationships": {
"services": {
"data": [
{
"id": "RW-Split-Router",
"type": "services"
},
{
"id": "Read-Connection-Router",
"type": "services"
}
]
},
"monitors": {
"data": [
{
"id": "MySQL-Monitor",
"type": "monitors"
}
]
}
}
}
}PATCH /v1/servers/:name{
"data": {
"attributes": {
"parameters": {
"address": "192.168.0.123"
}
}
}
}{
"data": {
"relationships": {
"services": {
"data": [
{ "id": "Read-Connection-Router", "type": "services" }
]
},
"monitors": {
"data": [
{ "id": "MySQL-Monitor", "type": "monitors" }
]
}
}
}
}PATCH /v1/servers/:name/relationships/:typePATCH /v1/servers/my-db-server/relationships/services
{
data: [
{ "id": "my-rwsplit-service", "type": "services" }
]
}PATCH /v1/servers/my-db-server/relationships/services
{
data: []
}DELETE /v1/servers/:namePUT /v1/servers/:name/setPUT /v1/servers/db-server-1/set?state=maintenancePUT /v1/servers/db-server-1/set?state=maintenance&force=yesPUT /v1/servers/:name/clearConfigure routing services. This resource manages the core services that define how MaxScale routes and balances traffic between clients and backend servers.
A service resource represents a service inside MaxScale. A service is a collection of network listeners, filters, a router and a set of backend servers.
The :name in all of the URIs must be the name of a service in MaxScale.
Get a single service.
Status: 200 OK
Get all services.
Status: 200 OK
The :type in the URI must be either servers, services or filters, depending on which relationship is being retrieved.
Status: 200 OK
Create a new service by defining the resource. The posted object must define at least the following fields.
data.id
Name of the service
data.type
The data.attributes.parameters object is used to define router and service parameters. All configuration parameters that can be defined in the configuration file can also be added to the parameters object. The exceptions to this are the type, router, servers and filters parameters which must not be defined.
As with other REST API resources, the data.relationships field defines the relationships of the service to other resources. Services can have two types of relationships: servers and filters relationships.
If the request body defines a valid relationships object, the service is linked to those resources. For servers, this is equivalent to adding the list of server names into the parameter. For filters, this is equivalent to adding the filters in the data.relationships.filters.data array to the parameter in the order they appear. For other services, this is equivalent to adding the list of server names into the parameter.
The following example defines a new service with both a server and a filter relationship.
Service is created:
Status: 204 No Content
A service can only be destroyed if the service uses no servers or filters and all the listeners pointing to the service have been destroyed. This means that the data.relationships must be an empty object and data.attributes.listeners must be an empty array in order for the service to qualify for destruction.
If there are open client connections that use the service when it is destroyed, they are allowed to gracefully close before the service is destroyed. This means that the destruction of a service can be acknowledged via the REST API before the destruction process has fully completed.
To find out whether a service is still in use after it has been destroyed, the resource should be used. If a session for the service is still open, it has not yet been destroyed.
This endpoint also supports the force=yes parameter that will unconditionally delete the service by first unlinking it from all servers and filters that it uses.
Service is destroyed:
Status: 204 No Content
The request body must be a JSON object which represents a set of new definitions for the service.
All standard service parameters can be modified. Refer to the documentation on the details of these parameters.
In addition to the standard service parameters, router parameters can be updated at runtime if the router module supports it. Refer to the individual router documentation for more details on whether the router supports it and which parameters can be updated at runtime.
The following example modifies a service by changing the user parameter to admin.
Service is modified:
Status: 204 No Content
The :type in the URI must be either servers, services or filters, depending on which relationship is being modified.
The request body must be a JSON object that defines only the data field. The value of the data field must be an array of relationship objects that define the id and type fields of the relationship. This object will replace the existing relationships of this type for the service.
Note: The order of the values in the filters relationship will define the order the filters are set up in. The order in which the filters appear in the array will be the order in which the filters are applied to each query. Refer to the parameter for more details.
The following is an example request and request body that defines a single server relationship for a service that is equivalent to a servers=my-server parameter.
All relationships for a service can be deleted by sending an empty array as the data field value. The following example removes all servers from a service.
Service relationships modified:
Status: 204 No Content
Invalid JSON body:
Status: 400 Bad Request
Stops a started service.
This endpoint supports the following parameters:
force=yes
Close all existing connections that were created through this listener.
Service is stopped:
Status: 204 No Content
Starts a stopped service.
Service is started:
Status: 204 No Content
Reloads the list of database users used for authentication.
Users are reloaded:
Status: 204 No Content
This endpoint is deprecated, use the listeners endpoint instead.
This endpoint is deprecated, use the listeners endpoint instead.
This endpoint is deprecated, use the listeners endpoint instead.
This endpoint is deprecated, use the listeners endpoint instead.
This page is licensed: CC BY-SA / Gnu FDL
servicesdata.attributes.router
The router module to use
data.attributes.parameters.user
The user to use
data.attributes.parameters.password
The password to use
GET /v1/services/:name{
"data": {
"attributes": {
"connections": 0,
"listeners": [
{
"attributes": {
"module": "MariaDBProtocol",
"parameters": {
"MariaDBProtocol": {
"allow_replication": true,
"compression": "zlib,zstd",
"compression_threshold": 50
},
"address": "::",
"authenticator": null,
"authenticator_options": null,
"connection_init_sql_file": null,
"connection_metadata": [
"character_set_client=auto",
"character_set_connection=auto",
"character_set_results=auto",
"max_allowed_packet=auto",
"system_time_zone=auto",
"time_zone=auto",
"tx_isolation=auto",
"maxscale=auto"
],
"port": 4008,
"protocol": "MariaDBProtocol",
"proxy_protocol_networks": null,
"redirect_url": null,
"service": "Read-Connection-Router",
"socket": null,
"sql_mode": "default",
"ssl": false,
"ssl_ca": null,
"ssl_cert": null,
"ssl_cert_verify_depth": 9,
"ssl_cipher": null,
"ssl_crl": null,
"ssl_key": null,
"ssl_passphrase": "",
"ssl_verify_peer_certificate": false,
"ssl_verify_peer_host": false,
"ssl_version": "MAX",
"type": "listener",
"user_mapping_file": null
},
"source": {
"file": "/etc/maxscale.cnf",
"type": "static"
},
"state": "Running"
},
"id": "Read-Connection-Listener",
"relationships": {
"services": {
"data": [
{
"id": "Read-Connection-Router",
"type": "services"
}
],
"links": {
"related": "http://localhost:8989/v1/services/",
"self": "http://localhost:8989/v1/listeners/Read-Connection-Listener/relationships/services/"
}
}
},
"type": "listeners"
}
],
"module": "readconnroute",
"parameters": {
"auth_all_servers": false,
"connection_keepalive": "300000ms",
"disable_sescmd_history": false,
"enable_root_user": false,
"force_connection_keepalive": false,
"idle_session_pool_time": "-1ms",
"localhost_match_wildcard_host": true,
"log_auth_warnings": true,
"log_debug": false,
"log_info": false,
"log_notice": false,
"log_warning": false,
"master_accept_reads": true,
"max_connections": 0,
"max_replication_lag": "0ms",
"max_sescmd_history": 50,
"multiplex_timeout": "60000ms",
"net_write_timeout": "0ms",
"password": "*****",
"prune_sescmd_history": true,
"rank": "primary",
"retain_last_statements": -1,
"role": null,
"router": "readconnroute",
"router_options": "master",
"strip_db_esc": true,
"type": "service",
"user": "maxuser",
"user_accounts_file": null,
"user_accounts_file_usage": "add_when_load_ok",
"version_string": null,
"wait_timeout": "28800000ms"
},
"router": "readconnroute",
"source": {
"file": "/etc/maxscale.cnf",
"type": "static"
},
"started": "Fri, 25 Jul 2025 15:43:46 GMT",
"state": "Started",
"statistics": {
"active_operations": 0,
"avg_sescmd_history_length": 0.0,
"avg_session_active_pct": 0.0,
"avg_session_lifetime": 0.0,
"avg_session_queries": 0.0,
"connections": 0,
"failed_auths": 0,
"max_connections": 0,
"max_sescmd_history_length": 0,
"max_session_active_pct": 0.0,
"max_session_lifetime": 0.0,
"max_session_queries": 0,
"routed_packets": 0,
"routed_reads": 0,
"routed_writes": 0,
"total_connections": 0
},
"total_connections": 0,
"users": [
{
"default_role": "",
"global_priv": false,
"host": "127.0.0.1",
"plugins": [
{
"auth_string": "976B96FB3F7898CCFFCABC014300C311FB7607FD",
"plugin": "mysql_native_password"
}
],
"proxy_priv": false,
"ssl": false,
"super_priv": false,
"user": "healthcheck"
},
{
"default_role": "",
"global_priv": false,
"host": "::1",
"plugins": [
{
"auth_string": "976B96FB3F7898CCFFCABC014300C311FB7607FD",
"plugin": "mysql_native_password"
}
],
"proxy_priv": false,
"ssl": false,
"super_priv": false,
"user": "healthcheck"
},
{
"default_role": "",
"global_priv": false,
"host": "localhost",
"plugins": [
{
"auth_string": "976B96FB3F7898CCFFCABC014300C311FB7607FD",
"plugin": "mysql_native_password"
}
],
"proxy_priv": false,
"ssl": false,
"super_priv": false,
"user": "healthcheck"
},
{
"default_role": "",
"global_priv": false,
"host": "localhost",
"plugins": [
{
"auth_string": "",
"plugin": "mysql_native_password"
}
],
"proxy_priv": false,
"ssl": false,
"super_priv": false,
"user": "mariadb.sys"
},
{
"default_role": "",
"global_priv": true,
"host": "127.0.0.1",
"plugins": [
{
"auth_string": "5EDBD32E469DAE0CE10E6999C3899DEFCB9F12E0",
"plugin": "mysql_native_password"
}
],
"proxy_priv": false,
"ssl": false,
"super_priv": true,
"user": "maxuser"
},
{
"default_role": "",
"global_priv": true,
"host": "%",
"plugins": [
{
"auth_string": "5EDBD32E469DAE0CE10E6999C3899DEFCB9F12E0",
"plugin": "mysql_native_password"
}
],
"proxy_priv": false,
"ssl": false,
"super_priv": true,
"user": "maxuser"
},
{
"default_role": "",
"global_priv": true,
"host": "localhost",
"plugins": [
{
"auth_string": "",
"plugin": "mysql_native_password"
}
],
"proxy_priv": false,
"ssl": false,
"super_priv": true,
"user": "root"
},
{
"default_role": "",
"global_priv": true,
"host": "%",
"plugins": [
{
"auth_string": "",
"plugin": "mysql_native_password"
}
],
"proxy_priv": false,
"ssl": false,
"super_priv": true,
"user": "root"
}
],
"users_last_update": "Fri, 25 Jul 2025 15:43:49 GMT"
},
"id": "Read-Connection-Router",
"links": {
"self": "http://localhost:8989/v1/services/Read-Connection-Router/"
},
"relationships": {
"filters": {
"data": [
{
"id": "QLA",
"type": "filters"
},
{
"id": "Hint",
"type": "filters"
}
],
"links": {
"related": "http://localhost:8989/v1/filters/",
"self": "http://localhost:8989/v1/services/Read-Connection-Router/relationships/filters/"
}
},
"listeners": {
"data": [
{
"id": "Read-Connection-Listener",
"type": "listeners"
}
],
"links": {
"related": "http://localhost:8989/v1/listeners/",
"self": "http://localhost:8989/v1/services/Read-Connection-Router/relationships/listeners/"
}
},
"servers": {
"data": [
{
"id": "server1",
"type": "servers"
},
{
"id": "server2",
"type": "servers"
}
],
"links": {
"related": "http://localhost:8989/v1/servers/",
"self": "http://localhost:8989/v1/services/Read-Connection-Router/relationships/servers/"
}
}
},
"type": "services"
},
"links": {
"self": "http://localhost:8989/v1/services/Read-Connection-Router/"
}
}GET /v1/services{
"data": [
{
"attributes": {
"connections": 1,
"listeners": [
{
"attributes": {
"module": "MariaDBProtocol",
"parameters": {
"MariaDBProtocol": {
"allow_replication": true,
"compression": "zlib,zstd",
"compression_threshold": 50
},
"address": "::",
"authenticator": null,
"authenticator_options": null,
"connection_init_sql_file": null,
"connection_metadata": [
"character_set_client=auto",
"character_set_connection=auto",
"character_set_results=auto",
"max_allowed_packet=auto",
"system_time_zone=auto",
"time_zone=auto",
"tx_isolation=auto",
"maxscale=auto"
],
"port": 4006,
"protocol": "MariaDBProtocol",
"proxy_protocol_networks": null,
"redirect_url": null,
"service": "RW-Split-Router",
"socket": null,
"sql_mode": "default",
"ssl": false,
"ssl_ca": null,
"ssl_cert": null,
"ssl_cert_verify_depth": 9,
"ssl_cipher": null,
"ssl_crl": null,
"ssl_key": null,
"ssl_passphrase": "",
"ssl_verify_peer_certificate": false,
"ssl_verify_peer_host": false,
"ssl_version": "MAX",
"type": "listener",
"user_mapping_file": null
},
"source": {
"file": "/etc/maxscale.cnf",
"type": "static"
},
"state": "Running"
},
"id": "RW-Split-Listener",
"relationships": {
"services": {
"data": [
{
"id": "RW-Split-Router",
"type": "services"
}
],
"links": {
"related": "http://localhost:8989/v1/services/",
"self": "http://localhost:8989/v1/listeners/RW-Split-Listener/relationships/services/"
}
}
},
"type": "listeners"
}
],
"module": "readwritesplit",
"parameters": {
"auth_all_servers": false,
"causal_reads": "none",
"causal_reads_timeout": "10000ms",
"connection_keepalive": "300000ms",
"delayed_retry": false,
"delayed_retry_timeout": "10000ms",
"disable_sescmd_history": false,
"enable_root_user": false,
"force_connection_keepalive": false,
"idle_session_pool_time": "-1ms",
"lazy_connect": false,
"localhost_match_wildcard_host": true,
"log_auth_warnings": true,
"log_debug": false,
"log_info": false,
"log_notice": false,
"log_warning": false,
"master_accept_reads": false,
"master_failure_mode": "fail_on_write",
"master_reconnection": true,
"max_connections": 0,
"max_replication_lag": "0ms",
"max_sescmd_history": 50,
"max_slave_connections": 255,
"multiplex_timeout": "60000ms",
"net_write_timeout": "0ms",
"password": "*****",
"prune_sescmd_history": true,
"rank": "primary",
"retain_last_statements": -1,
"retry_failed_reads": true,
"role": null,
"router": "readwritesplit",
"slave_connections": 255,
"slave_selection_criteria": "least_current_operations",
"strict_multi_stmt": false,
"strict_sp_calls": false,
"strict_tmp_tables": true,
"strip_db_esc": true,
"sync_transaction": "none",
"sync_transaction_count": 1,
"sync_transaction_max_lag": "0ms",
"sync_transaction_timeout": "10000ms",
"transaction_replay": false,
"transaction_replay_attempts": 5,
"transaction_replay_checksum": "full",
"transaction_replay_max_size": 1048576,
"transaction_replay_retry_on_deadlock": false,
"transaction_replay_retry_on_mismatch": false,
"transaction_replay_safe_commit": true,
"transaction_replay_timeout": "30000ms",
"type": "service",
"use_sql_variables_in": "all",
"user": "maxuser",
"user_accounts_file": null,
"user_accounts_file_usage": "add_when_load_ok",
"version_string": null,
"wait_timeout": "28800000ms"
},
"router": "readwritesplit",
"router_diagnostics": {
"queries": 4,
"replayed_transactions": 0,
"ro_transactions": 0,
"route_all": 1,
"route_master": 3,
"route_slave": 0,
"rw_transactions": 1,
"sync_transaction_in_progress": 0,
"sync_transaction_lag": 0.0,
"sync_transaction_ok": 0,
"sync_transaction_timeout": 0,
"trx_max_size_exceeded": 0
},
"source": {
"file": "/etc/maxscale.cnf",
"type": "static"
},
"started": "Fri, 25 Jul 2025 15:43:46 GMT",
"state": "Started",
"statistics": {
"active_operations": 0,
"avg_sescmd_history_length": 0.0,
"avg_session_active_pct": 0.0,
"avg_session_lifetime": 0.0,
"avg_session_queries": 0.0,
"connections": 1,
"failed_auths": 0,
"max_connections": 1,
"max_sescmd_history_length": 0,
"max_session_active_pct": 0.0,
"max_session_lifetime": 0.0,
"max_session_queries": 0,
"routed_packets": 4,
"routed_reads": 0,
"routed_writes": 4,
"total_connections": 1
},
"total_connections": 1,
"users": [
{
"default_role": "",
"global_priv": false,
"host": "127.0.0.1",
"plugins": [
{
"auth_string": "976B96FB3F7898CCFFCABC014300C311FB7607FD",
"plugin": "mysql_native_password"
}
],
"proxy_priv": false,
"ssl": false,
"super_priv": false,
"user": "healthcheck"
},
{
"default_role": "",
"global_priv": false,
"host": "::1",
"plugins": [
{
"auth_string": "976B96FB3F7898CCFFCABC014300C311FB7607FD",
"plugin": "mysql_native_password"
}
],
"proxy_priv": false,
"ssl": false,
"super_priv": false,
"user": "healthcheck"
},
{
"default_role": "",
"global_priv": false,
"host": "localhost",
"plugins": [
{
"auth_string": "976B96FB3F7898CCFFCABC014300C311FB7607FD",
"plugin": "mysql_native_password"
}
],
"proxy_priv": false,
"ssl": false,
"super_priv": false,
"user": "healthcheck"
},
{
"default_role": "",
"global_priv": false,
"host": "localhost",
"plugins": [
{
"auth_string": "",
"plugin": "mysql_native_password"
}
],
"proxy_priv": false,
"ssl": false,
"super_priv": false,
"user": "mariadb.sys"
},
{
"default_role": "",
"global_priv": true,
"host": "127.0.0.1",
"plugins": [
{
"auth_string": "5EDBD32E469DAE0CE10E6999C3899DEFCB9F12E0",
"plugin": "mysql_native_password"
}
],
"proxy_priv": false,
"ssl": false,
"super_priv": true,
"user": "maxuser"
},
{
"default_role": "",
"global_priv": true,
"host": "%",
"plugins": [
{
"auth_string": "5EDBD32E469DAE0CE10E6999C3899DEFCB9F12E0",
"plugin": "mysql_native_password"
}
],
"proxy_priv": false,
"ssl": false,
"super_priv": true,
"user": "maxuser"
},
{
"default_role": "",
"global_priv": true,
"host": "localhost",
"plugins": [
{
"auth_string": "",
"plugin": "mysql_native_password"
}
],
"proxy_priv": false,
"ssl": false,
"super_priv": true,
"user": "root"
},
{
"default_role": "",
"global_priv": true,
"host": "%",
"plugins": [
{
"auth_string": "",
"plugin": "mysql_native_password"
}
],
"proxy_priv": false,
"ssl": false,
"super_priv": true,
"user": "root"
}
],
"users_last_update": "Fri, 25 Jul 2025 15:43:49 GMT"
},
"id": "RW-Split-Router",
"links": {
"self": "http://localhost:8989/v1/services/RW-Split-Router/"
},
"relationships": {
"listeners": {
"data": [
{
"id": "RW-Split-Listener",
"type": "listeners"
}
],
"links": {
"related": "http://localhost:8989/v1/listeners/",
"self": "http://localhost:8989/v1/services/RW-Split-Router/relationships/listeners/"
}
},
"monitors": {
"data": [
{
"id": "MariaDB-Monitor",
"type": "monitors"
}
],
"links": {
"related": "http://localhost:8989/v1/monitors/",
"self": "http://localhost:8989/v1/services/RW-Split-Router/relationships/monitors/"
}
}
},
"type": "services"
},
{
"attributes": {
"connections": 0,
"listeners": [
{
"attributes": {
"module": "MariaDBProtocol",
"parameters": {
"MariaDBProtocol": {
"allow_replication": true,
"compression": "zlib,zstd",
"compression_threshold": 50
},
"address": "::",
"authenticator": null,
"authenticator_options": null,
"connection_init_sql_file": null,
"connection_metadata": [
"character_set_client=auto",
"character_set_connection=auto",
"character_set_results=auto",
"max_allowed_packet=auto",
"system_time_zone=auto",
"time_zone=auto",
"tx_isolation=auto",
"maxscale=auto"
],
"port": 4008,
"protocol": "MariaDBProtocol",
"proxy_protocol_networks": null,
"redirect_url": null,
"service": "Read-Connection-Router",
"socket": null,
"sql_mode": "default",
"ssl": false,
"ssl_ca": null,
"ssl_cert": null,
"ssl_cert_verify_depth": 9,
"ssl_cipher": null,
"ssl_crl": null,
"ssl_key": null,
"ssl_passphrase": "",
"ssl_verify_peer_certificate": false,
"ssl_verify_peer_host": false,
"ssl_version": "MAX",
"type": "listener",
"user_mapping_file": null
},
"source": {
"file": "/etc/maxscale.cnf",
"type": "static"
},
"state": "Running"
},
"id": "Read-Connection-Listener",
"relationships": {
"services": {
"data": [
{
"id": "Read-Connection-Router",
"type": "services"
}
],
"links": {
"related": "http://localhost:8989/v1/services/",
"self": "http://localhost:8989/v1/listeners/Read-Connection-Listener/relationships/services/"
}
}
},
"type": "listeners"
}
],
"module": "readconnroute",
"parameters": {
"auth_all_servers": false,
"connection_keepalive": "300000ms",
"disable_sescmd_history": false,
"enable_root_user": false,
"force_connection_keepalive": false,
"idle_session_pool_time": "-1ms",
"localhost_match_wildcard_host": true,
"log_auth_warnings": true,
"log_debug": false,
"log_info": false,
"log_notice": false,
"log_warning": false,
"master_accept_reads": true,
"max_connections": 0,
"max_replication_lag": "0ms",
"max_sescmd_history": 50,
"multiplex_timeout": "60000ms",
"net_write_timeout": "0ms",
"password": "*****",
"prune_sescmd_history": true,
"rank": "primary",
"retain_last_statements": -1,
"role": null,
"router": "readconnroute",
"router_options": "master",
"strip_db_esc": true,
"type": "service",
"user": "maxuser",
"user_accounts_file": null,
"user_accounts_file_usage": "add_when_load_ok",
"version_string": null,
"wait_timeout": "28800000ms"
},
"router": "readconnroute",
"source": {
"file": "/etc/maxscale.cnf",
"type": "static"
},
"started": "Fri, 25 Jul 2025 15:43:46 GMT",
"state": "Started",
"statistics": {
"active_operations": 0,
"avg_sescmd_history_length": 0.0,
"avg_session_active_pct": 0.0,
"avg_session_lifetime": 0.0,
"avg_session_queries": 0.0,
"connections": 0,
"failed_auths": 0,
"max_connections": 0,
"max_sescmd_history_length": 0,
"max_session_active_pct": 0.0,
"max_session_lifetime": 0.0,
"max_session_queries": 0,
"routed_packets": 0,
"routed_reads": 0,
"routed_writes": 0,
"total_connections": 0
},
"total_connections": 0,
"users": [
{
"default_role": "",
"global_priv": false,
"host": "127.0.0.1",
"plugins": [
{
"auth_string": "976B96FB3F7898CCFFCABC014300C311FB7607FD",
"plugin": "mysql_native_password"
}
],
"proxy_priv": false,
"ssl": false,
"super_priv": false,
"user": "healthcheck"
},
{
"default_role": "",
"global_priv": false,
"host": "::1",
"plugins": [
{
"auth_string": "976B96FB3F7898CCFFCABC014300C311FB7607FD",
"plugin": "mysql_native_password"
}
],
"proxy_priv": false,
"ssl": false,
"super_priv": false,
"user": "healthcheck"
},
{
"default_role": "",
"global_priv": false,
"host": "localhost",
"plugins": [
{
"auth_string": "976B96FB3F7898CCFFCABC014300C311FB7607FD",
"plugin": "mysql_native_password"
}
],
"proxy_priv": false,
"ssl": false,
"super_priv": false,
"user": "healthcheck"
},
{
"default_role": "",
"global_priv": false,
"host": "localhost",
"plugins": [
{
"auth_string": "",
"plugin": "mysql_native_password"
}
],
"proxy_priv": false,
"ssl": false,
"super_priv": false,
"user": "mariadb.sys"
},
{
"default_role": "",
"global_priv": true,
"host": "127.0.0.1",
"plugins": [
{
"auth_string": "5EDBD32E469DAE0CE10E6999C3899DEFCB9F12E0",
"plugin": "mysql_native_password"
}
],
"proxy_priv": false,
"ssl": false,
"super_priv": true,
"user": "maxuser"
},
{
"default_role": "",
"global_priv": true,
"host": "%",
"plugins": [
{
"auth_string": "5EDBD32E469DAE0CE10E6999C3899DEFCB9F12E0",
"plugin": "mysql_native_password"
}
],
"proxy_priv": false,
"ssl": false,
"super_priv": true,
"user": "maxuser"
},
{
"default_role": "",
"global_priv": true,
"host": "localhost",
"plugins": [
{
"auth_string": "",
"plugin": "mysql_native_password"
}
],
"proxy_priv": false,
"ssl": false,
"super_priv": true,
"user": "root"
},
{
"default_role": "",
"global_priv": true,
"host": "%",
"plugins": [
{
"auth_string": "",
"plugin": "mysql_native_password"
}
],
"proxy_priv": false,
"ssl": false,
"super_priv": true,
"user": "root"
}
],
"users_last_update": "Fri, 25 Jul 2025 15:43:49 GMT"
},
"id": "Read-Connection-Router",
"links": {
"self": "http://localhost:8989/v1/services/Read-Connection-Router/"
},
"relationships": {
"filters": {
"data": [
{
"id": "QLA",
"type": "filters"
},
{
"id": "Hint",
"type": "filters"
}
],
"links": {
"related": "http://localhost:8989/v1/filters/",
"self": "http://localhost:8989/v1/services/Read-Connection-Router/relationships/filters/"
}
},
"listeners": {
"data": [
{
"id": "Read-Connection-Listener",
"type": "listeners"
}
],
"links": {
"related": "http://localhost:8989/v1/listeners/",
"self": "http://localhost:8989/v1/services/Read-Connection-Router/relationships/listeners/"
}
},
"servers": {
"data": [
{
"id": "server1",
"type": "servers"
},
{
"id": "server2",
"type": "servers"
}
],
"links": {
"related": "http://localhost:8989/v1/servers/",
"self": "http://localhost:8989/v1/services/Read-Connection-Router/relationships/servers/"
}
}
},
"type": "services"
}
],
"links": {
"self": "http://localhost:8989/v1/services/"
}
}GET /v1/services/:name/relationships/:type{
"data": [
{
"id": "server1",
"type": "servers"
},
{
"id": "server2",
"type": "servers"
}
],
"links": {
"related": "http://localhost:8989/v1/servers/",
"self": "http://localhost:8989/v1/services/Read-Connection-Router/relationships/servers/"
}
}POST /v1/services{
"data": {
"id": "my-service",
"type": "services",
"attributes": {
"router": "readwritesplit",
"parameters": {
"user": "maxuser",
"password": "maxpwd"
}
},
"relationships": {
"filters": {
"data": [
{
"id": "QLA",
"type": "filters"
}
]
},
"servers": {
"data": [
{
"id": "server1",
"type": "servers"
}
]
}
}
}
}DELETE /v1/services/:namePATCH /v1/services/:name{
"data": {
"attributes": {
"parameters": {
"user": "admin"
}
}
}
}PATCH /v1/services/:name/relationships/:typePATCH /v1/services/my-rw-service/relationships/servers
{
data: [
{ "id": "my-server", "type": "servers" }
]
}PATCH /v1/services/my-rw-service/relationships/servers
{
data: []
}PUT /v1/services/:name/stopPUT /v1/services/:name/startPOST /v1/services/:name/reloadGET /v1/services/:name/listenersGET /v1/services/:name/listeners/:listenerPOST /v1/services/:name/listenersDELETE /v1/services/:service/listeners/:nameInteract with generic MaxScale objects. This endpoint provides a unified interface for retrieving and managing configuration objects across the instance.
The objects resource collection contains all of the objects that are in MaxScale: listeners, services, filters, servers and monitors. This is a "view" on top of the other resource collection endpoints.
The :name in all of the URIs must be the name of an object in MaxScale.
Get a single object.
Status: 200 OK
Get all services.
Status: 200 OK
This page is licensed: CC BY-SA / Gnu FDL
GET /v1/objects/:name{
"data": {
"attributes": {
"connections": 0,
"listeners": [
{
"attributes": {
"module": "MariaDBProtocol",
"parameters": {
"MariaDBProtocol": {
"allow_replication": true,
"compression": "zlib,zstd",
"compression_threshold": 50
},
"address": "::",
"authenticator": null,
"authenticator_options": null,
"connection_init_sql_file": null,
"connection_metadata": [
"character_set_client=auto",
"character_set_connection=auto",
"character_set_results=auto",
"max_allowed_packet=auto",
"system_time_zone=auto",
"time_zone=auto",
"tx_isolation=auto",
"maxscale=auto"
],
"port": 4008,
"protocol": "MariaDBProtocol",
"proxy_protocol_networks": null,
"redirect_url": null,
"service": "Read-Connection-Router",
"socket": null,
"sql_mode": "default",
"ssl": false,
"ssl_ca": null,
"ssl_cert": null,
"ssl_cert_verify_depth": 9,
"ssl_cipher": null,
"ssl_crl": null,
"ssl_key": null,
"ssl_passphrase": "",
"ssl_verify_peer_certificate": false,
"ssl_verify_peer_host": false,
"ssl_version": "MAX",
"type": "listener",
"user_mapping_file": null
},
"source": {
"file": "/etc/maxscale.cnf",
"type": "static"
},
"state": "Running"
},
"id": "Read-Connection-Listener",
"relationships": {
"services": {
"data": [
{
"id": "Read-Connection-Router",
"type": "services"
}
],
"links": {
"related": "http://localhost:8989/v1/services/",
"self": "http://localhost:8989/v1/listeners/Read-Connection-Listener/relationships/services/"
}
}
},
"type": "listeners"
}
],
"module": "readconnroute",
"parameters": {
"auth_all_servers": false,
"connection_keepalive": "300000ms",
"disable_sescmd_history": false,
"enable_root_user": false,
"force_connection_keepalive": false,
"idle_session_pool_time": "-1ms",
"localhost_match_wildcard_host": true,
"log_auth_warnings": true,
"log_debug": false,
"log_info": false,
"log_notice": false,
"log_warning": false,
"master_accept_reads": true,
"max_connections": 0,
"max_replication_lag": "0ms",
"max_sescmd_history": 50,
"multiplex_timeout": "60000ms",
"net_write_timeout": "0ms",
"password": "*****",
"prune_sescmd_history": true,
"rank": "primary",
"retain_last_statements": -1,
"role": null,
"router": "readconnroute",
"router_options": "master",
"strip_db_esc": true,
"type": "service",
"user": "maxuser",
"user_accounts_file": null,
"user_accounts_file_usage": "add_when_load_ok",
"version_string": null,
"wait_timeout": "28800000ms"
},
"router": "readconnroute",
"source": {
"file": "/etc/maxscale.cnf",
"type": "static"
},
"started": "Fri, 25 Jul 2025 15:43:46 GMT",
"state": "Started",
"statistics": {
"active_operations": 0,
"avg_sescmd_history_length": 0.0,
"avg_session_active_pct": 0.0,
"avg_session_lifetime": 0.0,
"avg_session_queries": 0.0,
"connections": 0,
"failed_auths": 0,
"max_connections": 0,
"max_sescmd_history_length": 0,
"max_session_active_pct": 0.0,
"max_session_lifetime": 0.0,
"max_session_queries": 0,
"routed_packets": 0,
"routed_reads": 0,
"routed_writes": 0,
"total_connections": 0
},
"total_connections": 0,
"users": [
{
"default_role": "",
"global_priv": false,
"host": "127.0.0.1",
"plugins": [
{
"auth_string": "976B96FB3F7898CCFFCABC014300C311FB7607FD",
"plugin": "mysql_native_password"
}
],
"proxy_priv": false,
"ssl": false,
"super_priv": false,
"user": "healthcheck"
},
{
"default_role": "",
"global_priv": false,
"host": "::1",
"plugins": [
{
"auth_string": "976B96FB3F7898CCFFCABC014300C311FB7607FD",
"plugin": "mysql_native_password"
}
],
"proxy_priv": false,
"ssl": false,
"super_priv": false,
"user": "healthcheck"
},
{
"default_role": "",
"global_priv": false,
"host": "localhost",
"plugins": [
{
"auth_string": "976B96FB3F7898CCFFCABC014300C311FB7607FD",
"plugin": "mysql_native_password"
}
],
"proxy_priv": false,
"ssl": false,
"super_priv": false,
"user": "healthcheck"
},
{
"default_role": "",
"global_priv": false,
"host": "localhost",
"plugins": [
{
"auth_string": "",
"plugin": "mysql_native_password"
}
],
"proxy_priv": false,
"ssl": false,
"super_priv": false,
"user": "mariadb.sys"
},
{
"default_role": "",
"global_priv": true,
"host": "127.0.0.1",
"plugins": [
{
"auth_string": "5EDBD32E469DAE0CE10E6999C3899DEFCB9F12E0",
"plugin": "mysql_native_password"
}
],
"proxy_priv": false,
"ssl": false,
"super_priv": true,
"user": "maxuser"
},
{
"default_role": "",
"global_priv": true,
"host": "%",
"plugins": [
{
"auth_string": "5EDBD32E469DAE0CE10E6999C3899DEFCB9F12E0",
"plugin": "mysql_native_password"
}
],
"proxy_priv": false,
"ssl": false,
"super_priv": true,
"user": "maxuser"
},
{
"default_role": "",
"global_priv": true,
"host": "localhost",
"plugins": [
{
"auth_string": "",
"plugin": "mysql_native_password"
}
],
"proxy_priv": false,
"ssl": false,
"super_priv": true,
"user": "root"
},
{
"default_role": "",
"global_priv": true,
"host": "%",
"plugins": [
{
"auth_string": "",
"plugin": "mysql_native_password"
}
],
"proxy_priv": false,
"ssl": false,
"super_priv": true,
"user": "root"
}
],
"users_last_update": "Fri, 25 Jul 2025 15:43:49 GMT"
},
"id": "Read-Connection-Router",
"links": {
"self": "http://localhost:8989/v1/services/Read-Connection-Router/"
},
"relationships": {
"filters": {
"data": [
{
"id": "QLA",
"type": "filters"
},
{
"id": "Hint",
"type": "filters"
}
],
"links": {
"related": "http://localhost:8989/v1/filters/",
"self": "http://localhost:8989/v1/services/Read-Connection-Router/relationships/filters/"
}
},
"listeners": {
"data": [
{
"id": "Read-Connection-Listener",
"type": "listeners"
}
],
"links": {
"related": "http://localhost:8989/v1/listeners/",
"self": "http://localhost:8989/v1/services/Read-Connection-Router/relationships/listeners/"
}
},
"servers": {
"data": [
{
"id": "server1",
"type": "servers"
},
{
"id": "server2",
"type": "servers"
}
],
"links": {
"related": "http://localhost:8989/v1/servers/",
"self": "http://localhost:8989/v1/services/Read-Connection-Router/relationships/servers/"
}
}
},
"type": "services"
},
"links": {
"self": "http://localhost:8989/v1/services/Read-Connection-Router/"
}
}GET /v1/objects{
"data": [
{
"attributes": {
"connections": 1,
"listeners": [
{
"attributes": {
"module": "MariaDBProtocol",
"parameters": {
"MariaDBProtocol": {
"allow_replication": true,
"compression": "zlib,zstd",
"compression_threshold": 50
},
"address": "::",
"authenticator": null,
"authenticator_options": null,
"connection_init_sql_file": null,
"connection_metadata": [
"character_set_client=auto",
"character_set_connection=auto",
"character_set_results=auto",
"max_allowed_packet=auto",
"system_time_zone=auto",
"time_zone=auto",
"tx_isolation=auto",
"maxscale=auto"
],
"port": 4006,
"protocol": "MariaDBProtocol",
"proxy_protocol_networks": null,
"redirect_url": null,
"service": "RW-Split-Router",
"socket": null,
"sql_mode": "default",
"ssl": false,
"ssl_ca": null,
"ssl_cert": null,
"ssl_cert_verify_depth": 9,
"ssl_cipher": null,
"ssl_crl": null,
"ssl_key": null,
"ssl_passphrase": "",
"ssl_verify_peer_certificate": false,
"ssl_verify_peer_host": false,
"ssl_version": "MAX",
"type": "listener",
"user_mapping_file": null
},
"source": {
"file": "/etc/maxscale.cnf",
"type": "static"
},
"state": "Running"
},
"id": "RW-Split-Listener",
"relationships": {
"services": {
"data": [
{
"id": "RW-Split-Router",
"type": "services"
}
],
"links": {
"related": "http://localhost:8989/v1/services/",
"self": "http://localhost:8989/v1/listeners/RW-Split-Listener/relationships/services/"
}
}
},
"type": "listeners"
}
],
"module": "readwritesplit",
"parameters": {
"auth_all_servers": false,
"causal_reads": "none",
"causal_reads_timeout": "10000ms",
"connection_keepalive": "300000ms",
"delayed_retry": false,
"delayed_retry_timeout": "10000ms",
"disable_sescmd_history": false,
"enable_root_user": false,
"force_connection_keepalive": false,
"idle_session_pool_time": "-1ms",
"lazy_connect": false,
"localhost_match_wildcard_host": true,
"log_auth_warnings": true,
"log_debug": false,
"log_info": false,
"log_notice": false,
"log_warning": false,
"master_accept_reads": false,
"master_failure_mode": "fail_on_write",
"master_reconnection": true,
"max_connections": 0,
"max_replication_lag": "0ms",
"max_sescmd_history": 50,
"max_slave_connections": 255,
"multiplex_timeout": "60000ms",
"net_write_timeout": "0ms",
"password": "*****",
"prune_sescmd_history": true,
"rank": "primary",
"retain_last_statements": -1,
"retry_failed_reads": true,
"role": null,
"router": "readwritesplit",
"slave_connections": 255,
"slave_selection_criteria": "least_current_operations",
"strict_multi_stmt": false,
"strict_sp_calls": false,
"strict_tmp_tables": true,
"strip_db_esc": true,
"sync_transaction": "none",
"sync_transaction_count": 1,
"sync_transaction_max_lag": "0ms",
"sync_transaction_timeout": "10000ms",
"transaction_replay": false,
"transaction_replay_attempts": 5,
"transaction_replay_checksum": "full",
"transaction_replay_max_size": 1048576,
"transaction_replay_retry_on_deadlock": false,
"transaction_replay_retry_on_mismatch": false,
"transaction_replay_safe_commit": true,
"transaction_replay_timeout": "30000ms",
"type": "service",
"use_sql_variables_in": "all",
"user": "maxuser",
"user_accounts_file": null,
"user_accounts_file_usage": "add_when_load_ok",
"version_string": null,
"wait_timeout": "28800000ms"
},
"router": "readwritesplit",
"router_diagnostics": {
"queries": 4,
"replayed_transactions": 0,
"ro_transactions": 0,
"route_all": 1,
"route_master": 3,
"route_slave": 0,
"rw_transactions": 1,
"sync_transaction_in_progress": 0,
"sync_transaction_lag": 0.0,
"sync_transaction_ok": 0,
"sync_transaction_timeout": 0,
"trx_max_size_exceeded": 0
},
"source": {
"file": "/etc/maxscale.cnf",
"type": "static"
},
"started": "Fri, 25 Jul 2025 15:43:46 GMT",
"state": "Started",
"statistics": {
"active_operations": 0,
"avg_sescmd_history_length": 0.0,
"avg_session_active_pct": 0.0,
"avg_session_lifetime": 0.0,
"avg_session_queries": 0.0,
"connections": 1,
"failed_auths": 0,
"max_connections": 1,
"max_sescmd_history_length": 0,
"max_session_active_pct": 0.0,
"max_session_lifetime": 0.0,
"max_session_queries": 0,
"routed_packets": 4,
"routed_reads": 0,
"routed_writes": 4,
"total_connections": 1
},
"total_connections": 1,
"users": [
{
"default_role": "",
"global_priv": false,
"host": "127.0.0.1",
"plugins": [
{
"auth_string": "976B96FB3F7898CCFFCABC014300C311FB7607FD",
"plugin": "mysql_native_password"
}
],
"proxy_priv": false,
"ssl": false,
"super_priv": false,
"user": "healthcheck"
},
{
"default_role": "",
"global_priv": false,
"host": "::1",
"plugins": [
{
"auth_string": "976B96FB3F7898CCFFCABC014300C311FB7607FD",
"plugin": "mysql_native_password"
}
],
"proxy_priv": false,
"ssl": false,
"super_priv": false,
"user": "healthcheck"
},
{
"default_role": "",
"global_priv": false,
"host": "localhost",
"plugins": [
{
"auth_string": "976B96FB3F7898CCFFCABC014300C311FB7607FD",
"plugin": "mysql_native_password"
}
],
"proxy_priv": false,
"ssl": false,
"super_priv": false,
"user": "healthcheck"
},
{
"default_role": "",
"global_priv": false,
"host": "localhost",
"plugins": [
{
"auth_string": "",
"plugin": "mysql_native_password"
}
],
"proxy_priv": false,
"ssl": false,
"super_priv": false,
"user": "mariadb.sys"
},
{
"default_role": "",
"global_priv": true,
"host": "127.0.0.1",
"plugins": [
{
"auth_string": "5EDBD32E469DAE0CE10E6999C3899DEFCB9F12E0",
"plugin": "mysql_native_password"
}
],
"proxy_priv": false,
"ssl": false,
"super_priv": true,
"user": "maxuser"
},
{
"default_role": "",
"global_priv": true,
"host": "%",
"plugins": [
{
"auth_string": "5EDBD32E469DAE0CE10E6999C3899DEFCB9F12E0",
"plugin": "mysql_native_password"
}
],
"proxy_priv": false,
"ssl": false,
"super_priv": true,
"user": "maxuser"
},
{
"default_role": "",
"global_priv": true,
"host": "localhost",
"plugins": [
{
"auth_string": "",
"plugin": "mysql_native_password"
}
],
"proxy_priv": false,
"ssl": false,
"super_priv": true,
"user": "root"
},
{
"default_role": "",
"global_priv": true,
"host": "%",
"plugins": [
{
"auth_string": "",
"plugin": "mysql_native_password"
}
],
"proxy_priv": false,
"ssl": false,
"super_priv": true,
"user": "root"
}
],
"users_last_update": "Fri, 25 Jul 2025 15:43:49 GMT"
},
"id": "RW-Split-Router",
"links": {
"self": "http://localhost:8989/v1/services/RW-Split-Router/"
},
"relationships": {
"listeners": {
"data": [
{
"id": "RW-Split-Listener",
"type": "listeners"
}
],
"links": {
"related": "http://localhost:8989/v1/listeners/",
"self": "http://localhost:8989/v1/services/RW-Split-Router/relationships/listeners/"
}
},
"monitors": {
"data": [
{
"id": "MariaDB-Monitor",
"type": "monitors"
}
],
"links": {
"related": "http://localhost:8989/v1/monitors/",
"self": "http://localhost:8989/v1/services/RW-Split-Router/relationships/monitors/"
}
}
},
"type": "services"
},
{
"attributes": {
"connections": 0,
"listeners": [
{
"attributes": {
"module": "MariaDBProtocol",
"parameters": {
"MariaDBProtocol": {
"allow_replication": true,
"compression": "zlib,zstd",
"compression_threshold": 50
},
"address": "::",
"authenticator": null,
"authenticator_options": null,
"connection_init_sql_file": null,
"connection_metadata": [
"character_set_client=auto",
"character_set_connection=auto",
"character_set_results=auto",
"max_allowed_packet=auto",
"system_time_zone=auto",
"time_zone=auto",
"tx_isolation=auto",
"maxscale=auto"
],
"port": 4008,
"protocol": "MariaDBProtocol",
"proxy_protocol_networks": null,
"redirect_url": null,
"service": "Read-Connection-Router",
"socket": null,
"sql_mode": "default",
"ssl": false,
"ssl_ca": null,
"ssl_cert": null,
"ssl_cert_verify_depth": 9,
"ssl_cipher": null,
"ssl_crl": null,
"ssl_key": null,
"ssl_passphrase": "",
"ssl_verify_peer_certificate": false,
"ssl_verify_peer_host": false,
"ssl_version": "MAX",
"type": "listener",
"user_mapping_file": null
},
"source": {
"file": "/etc/maxscale.cnf",
"type": "static"
},
"state": "Running"
},
"id": "Read-Connection-Listener",
"relationships": {
"services": {
"data": [
{
"id": "Read-Connection-Router",
"type": "services"
}
],
"links": {
"related": "http://localhost:8989/v1/services/",
"self": "http://localhost:8989/v1/listeners/Read-Connection-Listener/relationships/services/"
}
}
},
"type": "listeners"
}
],
"module": "readconnroute",
"parameters": {
"auth_all_servers": false,
"connection_keepalive": "300000ms",
"disable_sescmd_history": false,
"enable_root_user": false,
"force_connection_keepalive": false,
"idle_session_pool_time": "-1ms",
"localhost_match_wildcard_host": true,
"log_auth_warnings": true,
"log_debug": false,
"log_info": false,
"log_notice": false,
"log_warning": false,
"master_accept_reads": true,
"max_connections": 0,
"max_replication_lag": "0ms",
"max_sescmd_history": 50,
"multiplex_timeout": "60000ms",
"net_write_timeout": "0ms",
"password": "*****",
"prune_sescmd_history": true,
"rank": "primary",
"retain_last_statements": -1,
"role": null,
"router": "readconnroute",
"router_options": "master",
"strip_db_esc": true,
"type": "service",
"user": "maxuser",
"user_accounts_file": null,
"user_accounts_file_usage": "add_when_load_ok",
"version_string": null,
"wait_timeout": "28800000ms"
},
"router": "readconnroute",
"source": {
"file": "/etc/maxscale.cnf",
"type": "static"
},
"started": "Fri, 25 Jul 2025 15:43:46 GMT",
"state": "Started",
"statistics": {
"active_operations": 0,
"avg_sescmd_history_length": 0.0,
"avg_session_active_pct": 0.0,
"avg_session_lifetime": 0.0,
"avg_session_queries": 0.0,
"connections": 0,
"failed_auths": 0,
"max_connections": 0,
"max_sescmd_history_length": 0,
"max_session_active_pct": 0.0,
"max_session_lifetime": 0.0,
"max_session_queries": 0,
"routed_packets": 0,
"routed_reads": 0,
"routed_writes": 0,
"total_connections": 0
},
"total_connections": 0,
"users": [
{
"default_role": "",
"global_priv": false,
"host": "127.0.0.1",
"plugins": [
{
"auth_string": "976B96FB3F7898CCFFCABC014300C311FB7607FD",
"plugin": "mysql_native_password"
}
],
"proxy_priv": false,
"ssl": false,
"super_priv": false,
"user": "healthcheck"
},
{
"default_role": "",
"global_priv": false,
"host": "::1",
"plugins": [
{
"auth_string": "976B96FB3F7898CCFFCABC014300C311FB7607FD",
"plugin": "mysql_native_password"
}
],
"proxy_priv": false,
"ssl": false,
"super_priv": false,
"user": "healthcheck"
},
{
"default_role": "",
"global_priv": false,
"host": "localhost",
"plugins": [
{
"auth_string": "976B96FB3F7898CCFFCABC014300C311FB7607FD",
"plugin": "mysql_native_password"
}
],
"proxy_priv": false,
"ssl": false,
"super_priv": false,
"user": "healthcheck"
},
{
"default_role": "",
"global_priv": false,
"host": "localhost",
"plugins": [
{
"auth_string": "",
"plugin": "mysql_native_password"
}
],
"proxy_priv": false,
"ssl": false,
"super_priv": false,
"user": "mariadb.sys"
},
{
"default_role": "",
"global_priv": true,
"host": "127.0.0.1",
"plugins": [
{
"auth_string": "5EDBD32E469DAE0CE10E6999C3899DEFCB9F12E0",
"plugin": "mysql_native_password"
}
],
"proxy_priv": false,
"ssl": false,
"super_priv": true,
"user": "maxuser"
},
{
"default_role": "",
"global_priv": true,
"host": "%",
"plugins": [
{
"auth_string": "5EDBD32E469DAE0CE10E6999C3899DEFCB9F12E0",
"plugin": "mysql_native_password"
}
],
"proxy_priv": false,
"ssl": false,
"super_priv": true,
"user": "maxuser"
},
{
"default_role": "",
"global_priv": true,
"host": "localhost",
"plugins": [
{
"auth_string": "",
"plugin": "mysql_native_password"
}
],
"proxy_priv": false,
"ssl": false,
"super_priv": true,
"user": "root"
},
{
"default_role": "",
"global_priv": true,
"host": "%",
"plugins": [
{
"auth_string": "",
"plugin": "mysql_native_password"
}
],
"proxy_priv": false,
"ssl": false,
"super_priv": true,
"user": "root"
}
],
"users_last_update": "Fri, 25 Jul 2025 15:43:49 GMT"
},
"id": "Read-Connection-Router",
"links": {
"self": "http://localhost:8989/v1/services/Read-Connection-Router/"
},
"relationships": {
"filters": {
"data": [
{
"id": "QLA",
"type": "filters"
},
{
"id": "Hint",
"type": "filters"
}
],
"links": {
"related": "http://localhost:8989/v1/filters/",
"self": "http://localhost:8989/v1/services/Read-Connection-Router/relationships/filters/"
}
},
"listeners": {
"data": [
{
"id": "Read-Connection-Listener",
"type": "listeners"
}
],
"links": {
"related": "http://localhost:8989/v1/listeners/",
"self": "http://localhost:8989/v1/services/Read-Connection-Router/relationships/listeners/"
}
},
"servers": {
"data": [
{
"id": "server1",
"type": "servers"
},
{
"id": "server2",
"type": "servers"
}
],
"links": {
"related": "http://localhost:8989/v1/servers/",
"self": "http://localhost:8989/v1/services/Read-Connection-Router/relationships/servers/"
}
}
},
"type": "services"
},
{
"attributes": {
"gtid_binlog_pos": "0-3000-5",
"gtid_current_pos": "0-3000-5",
"last_event": "master_up",
"lock_held": null,
"master_group": null,
"master_id": -1,
"name": "server1",
"node_id": 3000,
"parameters": {
"address": "127.0.0.1",
"disk_space_threshold": "",
"extra_port": 0,
"initial_status": "down",
"max_routing_connections": 0,
"monitorpw": null,
"monitoruser": null,
"persistmaxtime": "0ms",
"persistpoolmax": 0,
"port": 3000,
"priority": 0,
"private_address": null,
"proxy_protocol": false,
"rank": "primary",
"replication_custom_options": null,
"socket": null,
"ssl": false,
"ssl_ca": null,
"ssl_cert": null,
"ssl_cert_verify_depth": 9,
"ssl_cipher": null,
"ssl_key": null,
"ssl_passphrase": "",
"ssl_verify_peer_certificate": false,
"ssl_verify_peer_host": false,
"ssl_version": "MAX",
"use_service_credentials": true
},
"read_only": false,
"replication_lag": 0,
"server_id": 3000,
"slave_connections": [],
"source": {
"file": "/etc/maxscale.cnf",
"type": "static"
},
"state": "Master, Running",
"statistics": {
"active_operations": 0,
"adaptive_avg_select_time": "0ns",
"connection_pool_empty": 0,
"connections": 1,
"failed_auths": 0,
"max_connections": 1,
"max_pool_size": 0,
"persistent_connections": 0,
"response_time_distribution": {
"read": {
"distribution": [
{
"count": 0,
"time": "0.000001",
"total": 0.0
},
{
"count": 0,
"time": "0.000010",
"total": 0.0
},
{
"count": 0,
"time": "0.000100",
"total": 0.0
},
{
"count": 0,
"time": "0.001000",
"total": 0.0
},
{
"count": 0,
"time": "0.010000",
"total": 0.0
},
{
"count": 0,
"time": "0.100000",
"total": 0.0
},
{
"count": 0,
"time": "1.000000",
"total": 0.0
},
{
"count": 0,
"time": "10.000000",
"total": 0.0
},
{
"count": 0,
"time": "100.000000",
"total": 0.0
},
{
"count": 0,
"time": "1000.000000",
"total": 0.0
},
{
"count": 0,
"time": "10000.000000",
"total": 0.0
},
{
"count": 0,
"time": "100000.000000",
"total": 0.0
}
],
"operation": "read",
"range_base": 10
},
"write": {
"distribution": [
{
"count": 0,
"time": "0.000001",
"total": 0.0
},
{
"count": 0,
"time": "0.000010",
"total": 0.0
},
{
"count": 0,
"time": "0.000100",
"total": 0.0
},
{
"count": 4,
"time": "0.001000",
"total": 0.001319181
},
{
"count": 0,
"time": "0.010000",
"total": 0.0
},
{
"count": 0,
"time": "0.100000",
"total": 0.0
},
{
"count": 0,
"time": "1.000000",
"total": 0.0
},
{
"count": 0,
"time": "10.000000",
"total": 0.0
},
{
"count": 0,
"time": "100.000000",
"total": 0.0
},
{
"count": 0,
"time": "1000.000000",
"total": 0.0
},
{
"count": 0,
"time": "10000.000000",
"total": 0.0
},
{
"count": 0,
"time": "100000.000000",
"total": 0.0
}
],
"operation": "write",
"range_base": 10
}
},
"reused_connections": 0,
"routed_packets": 4,
"routed_reads": 0,
"routed_writes": 4,
"total_connections": 1
},
"status": {
"extra": "",
"mode": "Normal",
"reason": [
"Primary"
],
"state": "Write"
},
"triggered_at": "Fri, 25 Jul 2025 15:43:48 GMT",
"uptime": 10,
"version_string": "10.11.9-MariaDB-ubu2204-log"
},
"id": "server1",
"links": {
"self": "http://localhost:8989/v1/servers/server1/"
},
"relationships": {
"monitors": {
"data": [
{
"id": "MariaDB-Monitor",
"type": "monitors"
}
],
"links": {
"related": "http://localhost:8989/v1/monitors/",
"self": "http://localhost:8989/v1/servers/server1/relationships/monitors/"
}
},
"services": {
"data": [
{
"id": "RW-Split-Router",
"type": "services"
},
{
"id": "Read-Connection-Router",
"type": "services"
}
],
"links": {
"related": "http://localhost:8989/v1/services/",
"self": "http://localhost:8989/v1/servers/server1/relationships/services/"
}
}
},
"type": "servers"
},
{
"attributes": {
"gtid_binlog_pos": "0-3000-5",
"gtid_current_pos": "0-3000-5",
"last_event": "slave_up",
"lock_held": null,
"master_group": null,
"master_id": 3000,
"name": "server2",
"node_id": 3001,
"parameters": {
"address": "127.0.0.1",
"disk_space_threshold": "",
"extra_port": 0,
"initial_status": "down",
"max_routing_connections": 0,
"monitorpw": null,
"monitoruser": null,
"persistmaxtime": "0ms",
"persistpoolmax": 0,
"port": 3001,
"priority": 0,
"private_address": null,
"proxy_protocol": false,
"rank": "primary",
"replication_custom_options": null,
"socket": null,
"ssl": false,
"ssl_ca": null,
"ssl_cert": null,
"ssl_cert_verify_depth": 9,
"ssl_cipher": null,
"ssl_key": null,
"ssl_passphrase": "",
"ssl_verify_peer_certificate": false,
"ssl_verify_peer_host": false,
"ssl_version": "MAX",
"use_service_credentials": true
},
"read_only": false,
"replication_lag": 0,
"server_id": 3001,
"slave_connections": [
{
"connection_name": "",
"gtid_io_pos": "",
"last_io_error": "",
"last_sql_error": "",
"master_host": "127.0.0.1",
"master_port": 3000,
"master_server_id": 3000,
"master_server_name": "server1",
"seconds_behind_master": 0,
"slave_io_running": "Yes",
"slave_sql_running": "Yes",
"using_gtid": "No"
}
],
"source": {
"file": "/etc/maxscale.cnf",
"type": "static"
},
"state": "Slave, Running",
"statistics": {
"active_operations": 0,
"adaptive_avg_select_time": "0ns",
"connection_pool_empty": 0,
"connections": 1,
"failed_auths": 0,
"max_connections": 1,
"max_pool_size": 0,
"persistent_connections": 0,
"response_time_distribution": {
"read": {
"distribution": [
{
"count": 0,
"time": "0.000001",
"total": 0.0
},
{
"count": 0,
"time": "0.000010",
"total": 0.0
},
{
"count": 0,
"time": "0.000100",
"total": 0.0
},
{
"count": 1,
"time": "0.001000",
"total": 0.00066959099999999998
},
{
"count": 0,
"time": "0.010000",
"total": 0.0
},
{
"count": 0,
"time": "0.100000",
"total": 0.0
},
{
"count": 0,
"time": "1.000000",
"total": 0.0
},
{
"count": 0,
"time": "10.000000",
"total": 0.0
},
{
"count": 0,
"time": "100.000000",
"total": 0.0
},
{
"count": 0,
"time": "1000.000000",
"total": 0.0
},
{
"count": 0,
"time": "10000.000000",
"total": 0.0
},
{
"count": 0,
"time": "100000.000000",
"total": 0.0
}
],
"operation": "read",
"range_base": 10
},
"write": {
"distribution": [
{
"count": 0,
"time": "0.000001",
"total": 0.0
},
{
"count": 0,
"time": "0.000010",
"total": 0.0
},
{
"count": 0,
"time": "0.000100",
"total": 0.0
},
{
"count": 0,
"time": "0.001000",
"total": 0.0
},
{
"count": 0,
"time": "0.010000",
"total": 0.0
},
{
"count": 0,
"time": "0.100000",
"total": 0.0
},
{
"count": 0,
"time": "1.000000",
"total": 0.0
},
{
"count": 0,
"time": "10.000000",
"total": 0.0
},
{
"count": 0,
"time": "100.000000",
"total": 0.0
},
{
"count": 0,
"time": "1000.000000",
"total": 0.0
},
{
"count": 0,
"time": "10000.000000",
"total": 0.0
},
{
"count": 0,
"time": "100000.000000",
"total": 0.0
}
],
"operation": "write",
"range_base": 10
}
},
"reused_connections": 0,
"routed_packets": 1,
"routed_reads": 1,
"routed_writes": 0,
"total_connections": 1
},
"status": {
"extra": "",
"mode": "Normal",
"reason": [
"Replica"
],
"state": "Read"
},
"triggered_at": "Fri, 25 Jul 2025 15:43:48 GMT",
"uptime": 9,
"version_string": "10.11.9-MariaDB-ubu2204-log"
},
"id": "server2",
"links": {
"self": "http://localhost:8989/v1/servers/server2/"
},
"relationships": {
"monitors": {
"data": [
{
"id": "MariaDB-Monitor",
"type": "monitors"
}
],
"links": {
"related": "http://localhost:8989/v1/monitors/",
"self": "http://localhost:8989/v1/servers/server2/relationships/monitors/"
}
},
"services": {
"data": [
{
"id": "RW-Split-Router",
"type": "services"
},
{
"id": "Read-Connection-Router",
"type": "services"
}
],
"links": {
"related": "http://localhost:8989/v1/services/",
"self": "http://localhost:8989/v1/servers/server2/relationships/services/"
}
}
},
"type": "servers"
},
{
"attributes": {
"module": "mariadbmon",
"monitor_diagnostics": {
"failback_master": null,
"master": "server1",
"master_gtid_domain_id": 0,
"primary": null,
"server_info": [
{
"gtid_binlog_pos": "0-3000-5",
"gtid_current_pos": "0-3000-5",
"lock_held": null,
"master_group": null,
"name": "server1",
"read_only": false,
"server_id": 3000,
"slave_connections": []
},
{
"gtid_binlog_pos": "0-3000-5",
"gtid_current_pos": "0-3000-5",
"lock_held": null,
"master_group": null,
"name": "server2",
"read_only": false,
"server_id": 3001,
"slave_connections": [
{
"connection_name": "",
"gtid_io_pos": "",
"last_io_error": "",
"last_sql_error": "",
"master_host": "127.0.0.1",
"master_port": 3000,
"master_server_id": 3000,
"master_server_name": "server1",
"seconds_behind_master": 0,
"slave_io_running": "Yes",
"slave_sql_running": "Yes",
"using_gtid": "No"
}
]
}
],
"state": "Idle"
},
"parameters": {
"assume_unique_hostnames": true,
"auto_failback_switchover": false,
"auto_failover": "false",
"auto_rejoin": false,
"backend_connect_attempts": 1,
"backend_timeout": "3000ms",
"backup_storage_address": null,
"backup_storage_path": null,
"cooperative_monitoring_locks": "none",
"cs_admin_api_key": null,
"cs_admin_base_path": "/cmapi/0.4.0",
"cs_admin_port": 8640,
"demotion_sql_file": null,
"disk_space_check_interval": "0ms",
"disk_space_threshold": null,
"enforce_read_only_servers": false,
"enforce_read_only_slaves": false,
"enforce_simple_topology": false,
"enforce_writable_master": false,
"events": "all,master_down,master_up,slave_down,slave_up,server_down,server_up,synced_down,synced_up,donor_down,donor_up,lost_master,lost_slave,lost_synced,lost_donor,new_master,new_slave,new_synced,new_donor",
"failcount": 5,
"failover_timeout": "90000ms",
"handle_events": true,
"journal_max_age": "28800000ms",
"maintenance_on_low_disk_space": true,
"mariabackup_parallel": 1,
"mariabackup_use_memory": "1G",
"master_conditions": "primary_monitor_master,disk_space_ok",
"master_failure_timeout": "10000ms",
"module": "mariadbmon",
"monitor_interval": "1000ms",
"password": "*****",
"primary_state_sql": null,
"promotion_sql_file": null,
"rebuild_port": 4444,
"replica_state_sql": null,
"replication_custom_options": null,
"replication_master_ssl": false,
"replication_password": "*****",
"replication_user": "maxuser",
"role": null,
"script": null,
"script_max_replication_lag": -1,
"script_timeout": "90000ms",
"servers_no_cooperative_monitoring_locks": null,
"servers_no_promotion": null,
"slave_conditions": "",
"ssh_check_host_key": true,
"ssh_keyfile": null,
"ssh_port": 22,
"ssh_timeout": "10000ms",
"ssh_user": null,
"switchover_on_low_disk_space": false,
"switchover_timeout": "90000ms",
"type": "monitor",
"user": "maxuser",
"verify_master_failure": true,
"write_test_fail_action": "log",
"write_test_interval": "0ms",
"write_test_table": "mxs.maxscale_write_test"
},
"source": {
"file": "/etc/maxscale.cnf",
"type": "static"
},
"state": "Running",
"ticks": 12
},
"id": "MariaDB-Monitor",
"links": {
"self": "http://localhost:8989/v1/monitors/MariaDB-Monitor/"
},
"relationships": {
"servers": {
"data": [
{
"id": "server1",
"type": "servers"
},
{
"id": "server2",
"type": "servers"
}
],
"links": {
"related": "http://localhost:8989/v1/servers/",
"self": "http://localhost:8989/v1/monitors/MariaDB-Monitor/relationships/servers/"
}
},
"services": {
"data": [
{
"id": "RW-Split-Router",
"type": "services"
}
],
"links": {
"related": "http://localhost:8989/v1/services/",
"self": "http://localhost:8989/v1/monitors/MariaDB-Monitor/relationships/services/"
}
}
},
"type": "monitors"
},
{
"attributes": {
"module": "qlafilter",
"parameters": {
"append": false,
"duration_unit": "ms",
"exclude": null,
"filebase": "/tmp/qla.log",
"flush": true,
"log_data": "date,user,query",
"log_type": "unified",
"match": null,
"module": "qlafilter",
"newline_replacement": " ",
"options": "",
"separator": ",",
"source": null,
"source_exclude": null,
"source_match": null,
"use_canonical_form": false,
"user": null,
"user_exclude": null,
"user_match": null
},
"source": {
"file": "/etc/maxscale.cnf",
"type": "static"
}
},
"id": "QLA",
"links": {
"self": "http://localhost:8989/v1/filters/QLA/"
},
"relationships": {
"services": {
"data": [
{
"id": "Read-Connection-Router",
"type": "services"
}
],
"links": {
"related": "http://localhost:8989/v1/services/",
"self": "http://localhost:8989/v1/filters/QLA/relationships/services/"
}
}
},
"type": "filters"
},
{
"attributes": {
"module": "hintfilter",
"parameters": {
"module": "hintfilter"
},
"source": {
"file": "/etc/maxscale.cnf",
"type": "static"
}
},
"id": "Hint",
"links": {
"self": "http://localhost:8989/v1/filters/Hint/"
},
"relationships": {
"services": {
"data": [
{
"id": "Read-Connection-Router",
"type": "services"
}
],
"links": {
"related": "http://localhost:8989/v1/services/",
"self": "http://localhost:8989/v1/filters/Hint/relationships/services/"
}
}
},
"type": "filters"
},
{
"attributes": {
"module": "MariaDBProtocol",
"parameters": {
"MariaDBProtocol": {
"allow_replication": true,
"compression": "zlib,zstd",
"compression_threshold": 50
},
"address": "::",
"authenticator": null,
"authenticator_options": null,
"connection_init_sql_file": null,
"connection_metadata": [
"character_set_client=auto",
"character_set_connection=auto",
"character_set_results=auto",
"max_allowed_packet=auto",
"system_time_zone=auto",
"time_zone=auto",
"tx_isolation=auto",
"maxscale=auto"
],
"port": 4006,
"protocol": "MariaDBProtocol",
"proxy_protocol_networks": null,
"redirect_url": null,
"service": "RW-Split-Router",
"socket": null,
"sql_mode": "default",
"ssl": false,
"ssl_ca": null,
"ssl_cert": null,
"ssl_cert_verify_depth": 9,
"ssl_cipher": null,
"ssl_crl": null,
"ssl_key": null,
"ssl_passphrase": "",
"ssl_verify_peer_certificate": false,
"ssl_verify_peer_host": false,
"ssl_version": "MAX",
"type": "listener",
"user_mapping_file": null
},
"source": {
"file": "/etc/maxscale.cnf",
"type": "static"
},
"state": "Running"
},
"id": "RW-Split-Listener",
"relationships": {
"services": {
"data": [
{
"id": "RW-Split-Router",
"type": "services"
}
],
"links": {
"related": "http://localhost:8989/v1/services/",
"self": "http://localhost:8989/v1/listeners/RW-Split-Listener/relationships/services/"
}
}
},
"type": "listeners"
},
{
"attributes": {
"module": "MariaDBProtocol",
"parameters": {
"MariaDBProtocol": {
"allow_replication": true,
"compression": "zlib,zstd",
"compression_threshold": 50
},
"address": "::",
"authenticator": null,
"authenticator_options": null,
"connection_init_sql_file": null,
"connection_metadata": [
"character_set_client=auto",
"character_set_connection=auto",
"character_set_results=auto",
"max_allowed_packet=auto",
"system_time_zone=auto",
"time_zone=auto",
"tx_isolation=auto",
"maxscale=auto"
],
"port": 4008,
"protocol": "MariaDBProtocol",
"proxy_protocol_networks": null,
"redirect_url": null,
"service": "Read-Connection-Router",
"socket": null,
"sql_mode": "default",
"ssl": false,
"ssl_ca": null,
"ssl_cert": null,
"ssl_cert_verify_depth": 9,
"ssl_cipher": null,
"ssl_crl": null,
"ssl_key": null,
"ssl_passphrase": "",
"ssl_verify_peer_certificate": false,
"ssl_verify_peer_host": false,
"ssl_version": "MAX",
"type": "listener",
"user_mapping_file": null
},
"source": {
"file": "/etc/maxscale.cnf",
"type": "static"
},
"state": "Running"
},
"id": "Read-Connection-Listener",
"relationships": {
"services": {
"data": [
{
"id": "Read-Connection-Router",
"type": "services"
}
],
"links": {
"related": "http://localhost:8989/v1/services/",
"self": "http://localhost:8989/v1/listeners/Read-Connection-Listener/relationships/services/"
}
}
},
"type": "listeners"
}
],
"links": {
"self": "http://localhost:8989/v1/objects/"
}
}Retrieve global instance details. Access version information, manage global configuration parameters, and monitor the logging status of your MaxScale instance.
The MaxScale resource represents a MaxScale instance and it is the core on top of which the modules build upon.
Retrieve global information about a MaxScale instance. This includes various file locations, configuration options and version information.
Status: 200 OK
Update MaxScale parameters. The request body must define updated values for the data.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.
Parameters modified:
Status: 204 No Content
Invalid JSON body:
Status: 400 Bad Request
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.
Status: 200 OK
Get the information for all threads. Returns a collection of threads resources.
Status: 200 OK
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.
Status: 200 OK
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.
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]
Status: 200 OK
Get the contents of the MaxScale logs as separate entries. This endpoint was added in MaxScale 24.02. This endpoint is nearly identical to the /v1/maxscale/logs/data endpoint except that this is a resource collection where each log line is a separate resource.
This endpoint supports the same parameters as .
Status: 200 OK
Stream the contents of the MaxScale logs. This endpoint was added in MaxScale 6.
This endpoint opens a 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:
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.
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.
Upgrade started:
Status: 101 Switching Protocols
Client didn't request a WebSocket upgrade:
Status: 426 Upgrade Required
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 misspelling of the ms_timestamp and log_throttling parameters, this is not fully backwards compatible.
Update logging parameters. The request body must define updated values for the data.attributes.parameters object. All logging parameters can be altered at runtime.
Parameters modified:
Status: 204 No Content
Invalid JSON body:
Status: 400 Bad Request
Flushes any pending messages to disk and reopens the log files. The body of the message is ignored.
Status: 204 No Content
Reloads all TLS certificates for listeners and servers as well as the REST API itself. If the reloading fails, the old certificates will remain in use for the objects that failed to reload. This also causes the JWT signature keys to be reloaded if one of the asymmetric key algorithms is being used. If JWTs are being signed with a random symmetric keys, a new random key is created.
The reloading is not transactional: if a single listener or server fails to reload its certificates, the remaining ones are not reloaded. This means that a failed reload can partially reload certificates. The REST API certificates are only reloaded if all other certificate reloads were successful.
Status: 204 No Content
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.
Status: 200 OK
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.
Status: 200 OK
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 mariadbmon module command reset-replication with two parameters, the name of the monitor instance and the server name:
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 provided statement and return the result.
Status: 200 OK
Initiates the dumping of the query classifier cache. The request body must be a JSON object consisting of the following fields:
path
The path of the directory where the dump should be saved. This is a mandatory field.
format
Here is an example request body:
The dumping is successfully initiated:
Status: 200 OK
The dump is written to a temporary file in the specified directory. At the end the file is renamed to the name returned in the response. Thus, if the file is immediately checked for, it may not yet be present.
This page is licensed: CC BY-SA / Gnu FDL
This value should not be modified by the user and the values returned in the links 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 and debug. Note that the debug log level is only used in debug builds of MaxScale.
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 and debug. Note that the debug log level is only used in debug builds of MaxScale.
json, pretty_json and json_lines. This is an optional field and the default is 'json'.GET /v1/maxscale{
"data": {
"attributes": {
"activated_at": "Fri, 25 Jul 2025 15:43:46 GMT",
"commit": "7e45151e58ee1ec2b35d7953af9d8830e1c57621",
"config_sync": null,
"parameters": {
"admin_audit": false,
"admin_audit_exclude_methods": [],
"admin_audit_file": "/var/log/maxscale/admin_audit.csv",
"admin_auth": true,
"admin_enabled": true,
"admin_gui": true,
"admin_host": "127.0.0.1",
"admin_jwt_algorithm": "auto",
"admin_jwt_issuer": "maxscale",
"admin_jwt_key": null,
"admin_jwt_max_age": "86400000ms",
"admin_log_auth_failures": true,
"admin_oidc_client_id": "maxscale",
"admin_oidc_client_secret": null,
"admin_oidc_flow": "auto",
"admin_oidc_url": null,
"admin_pam_readonly_service": null,
"admin_pam_readwrite_service": null,
"admin_port": 8989,
"admin_readonly_hosts": "%",
"admin_readwrite_hosts": "%",
"admin_secure_gui": false,
"admin_ssl_ca": null,
"admin_ssl_cert": null,
"admin_ssl_cipher": null,
"admin_ssl_key": null,
"admin_ssl_version": "MAX",
"admin_verify_url": null,
"auth_connect_timeout": "10000ms",
"auth_read_timeout": "10000ms",
"auth_write_timeout": "10000ms",
"auto_tune": [],
"config_sync_cluster": null,
"config_sync_db": "mysql",
"config_sync_interval": "5000ms",
"config_sync_password": null,
"config_sync_timeout": "10000ms",
"config_sync_user": null,
"connector_plugindir": "/usr/lib64/maxscale/plugin",
"core_file": true,
"datadir": "/var/lib/maxscale",
"debug": null,
"dump_last_statements": "never",
"event_authentication_failure_facility": "LOG_USER",
"event_authentication_failure_level": "LOG_WARNING",
"event_firewall_incident_facility": "LOG_USER",
"event_firewall_incident_level": "LOG_WARNING",
"host_cache_size": 128,
"key_manager": "none",
"libdir": "/usr/lib64/maxscale",
"load_persisted_configs": true,
"local_address": null,
"log_debug": false,
"log_info": false,
"log_notice": true,
"log_throttling": {
"count": 10,
"suppress": 10000,
"window": 1000
},
"log_warn_super_user": false,
"log_warning": true,
"logdir": "/var/log/maxscale",
"max_auth_errors_until_block": 10,
"maxlog": true,
"module_configdir": "/etc/maxscale.modules.d",
"ms_timestamp": false,
"passive": false,
"persist_runtime_changes": true,
"persistdir": "/var/lib/maxscale/maxscale.cnf.d",
"piddir": "/run/maxscale",
"query_classifier_cache_size": 5002190438,
"rebalance_period": "0ms",
"rebalance_threshold": 20,
"rebalance_window": 10,
"require_secure_transport": false,
"retain_last_statements": 0,
"secretsdir": null,
"session_trace": 0,
"session_trace_match": null,
"skip_name_resolve": false,
"sql_mode": "default",
"syslog": false,
"telemetry": false,
"threads": 3,
"threads_max": 256,
"trace_file_dir": null,
"trace_file_size": 0,
"users_refresh_interval": "0ms",
"users_refresh_time": "0ms",
"writeq_high_water": 65536,
"writeq_low_water": 1024
},
"started_at": "Fri, 25 Jul 2025 15:43:46 GMT",
"system": {
"machine": {
"cores_available": 8,
"cores_physical": 8,
"cores_virtual": 8.0,
"memory_available": 33347936256,
"memory_physical": 33347936256
},
"maxscale": {
"query_classifier_cache_size": 5002190438,
"threads": 3
},
"os": {
"machine": "x86_64",
"nodename": "monolith",
"release": "6.15.7-100.fc41.x86_64",
"sysname": "Linux",
"version": "#1 SMP PREEMPT_DYNAMIC Thu Jul 17 16:56:15 UTC 2025"
}
},
"uptime": 11,
"version": "99.99.99"
},
"id": "maxscale",
"type": "maxscale"
},
"links": {
"self": "http://localhost:8989/v1/maxscale/"
}
}PATCH /v1/maxscaleGET /v1/maxscale/threads/:id{
"data": {
"attributes": {
"stats": {
"current_descriptors": 8,
"listening": true,
"load": {
"last_hour": 0,
"last_minute": 0,
"last_second": 0
},
"memory": {
"query_classifier": 1601,
"sessions": 265831,
"total": 267432,
"zombies": 0
},
"query_classifier_cache": {
"evictions": 0,
"hits": 0,
"inserts": 3,
"misses": 4,
"size": 1601
},
"sessions": 1,
"state": "Active",
"total_descriptors": 8,
"zombies": 0
}
},
"id": "0",
"links": {
"self": "http://localhost:8989/v1/threads/0/"
},
"type": "threads"
},
"links": {
"self": "http://localhost:8989/v1/maxscale/threads/0/"
}
}GET /v1/maxscale/threads{
"data": [
{
"attributes": {
"stats": {
"current_descriptors": 8,
"listening": true,
"load": {
"last_hour": 0,
"last_minute": 0,
"last_second": 0
},
"memory": {
"query_classifier": 1601,
"sessions": 265831,
"total": 267432,
"zombies": 0
},
"query_classifier_cache": {
"evictions": 0,
"hits": 0,
"inserts": 3,
"misses": 4,
"size": 1601
},
"sessions": 1,
"state": "Active",
"total_descriptors": 8,
"zombies": 0
}
},
"id": "0",
"links": {
"self": "http://localhost:8989/v1/threads/0/"
},
"type": "threads"
},
{
"attributes": {
"stats": {
"current_descriptors": 5,
"listening": true,
"load": {
"last_hour": 0,
"last_minute": 0,
"last_second": 0
},
"memory": {
"query_classifier": 0,
"sessions": 0,
"total": 0,
"zombies": 0
},
"query_classifier_cache": {
"evictions": 0,
"hits": 0,
"inserts": 0,
"misses": 0,
"size": 0
},
"sessions": 0,
"state": "Active",
"total_descriptors": 5,
"zombies": 0
}
},
"id": "1",
"links": {
"self": "http://localhost:8989/v1/threads/1/"
},
"type": "threads"
},
{
"attributes": {
"stats": {
"current_descriptors": 5,
"listening": true,
"load": {
"last_hour": 0,
"last_minute": 0,
"last_second": 0
},
"memory": {
"query_classifier": 0,
"sessions": 0,
"total": 0,
"zombies": 0
},
"query_classifier_cache": {
"evictions": 0,
"hits": 0,
"inserts": 0,
"misses": 0,
"size": 0
},
"sessions": 0,
"state": "Active",
"total_descriptors": 5,
"zombies": 0
}
},
"id": "2",
"links": {
"self": "http://localhost:8989/v1/threads/2/"
},
"type": "threads"
}
],
"links": {
"self": "http://localhost:8989/v1/maxscale/threads/"
}
}GET /v1/maxscale/logs{
"data": {
"attributes": {
"log_file": "/var/log/maxscale/maxscale.log",
"log_priorities": [
"alert",
"error",
"warning",
"notice"
],
"parameters": {
"log_debug": false,
"log_info": false,
"log_notice": true,
"log_throttling": {
"count": 10,
"suppress": 10000,
"window": 1000
},
"log_warning": true,
"maxlog": true,
"ms_timestamp": false,
"syslog": false
}
},
"id": "logs",
"type": "logs"
},
"links": {
"self": "http://localhost:8989/v1/maxscale/logs/"
}
}GET /v1/maxscale/logs/data{
"data": {
"attributes": {
"log": [
{
"id": "38",
"message": "Server changed state: server2[127.0.0.1:3001]: slave_up. [Down] -> [Slave, Running]",
"priority": "notice",
"timestamp": "2025-07-25 15:43:48",
"unix_timestamp": 1753458228
},
{
"id": "39",
"message": "Read 8 user@host entries from 'server1' for service 'RW-Split-Router'.",
"priority": "notice",
"timestamp": "2025-07-25 15:43:49",
"unix_timestamp": 1753458229
},
{
"id": "40",
"message": "Read 8 user@host entries from 'server1' for service 'Read-Connection-Router'.",
"priority": "notice",
"timestamp": "2025-07-25 15:43:49",
"unix_timestamp": 1753458229
}
],
"log_source": "maxlog"
},
"id": "log_data",
"type": "log_data"
},
"links": {
"last": "http://localhost:8989/v1/maxscale/logs/data/?page%5Bsize%5D=3",
"prev": "http://localhost:8989/v1/maxscale/logs/data/?page%5Bcursor%5D=35&page%5Bsize%5D=3",
"self": "http://localhost:8989/v1/maxscale/logs/data/?page%5Bcursor%5D=38&page%5Bsize%5D=3"
}
}GET /v1/maxscale/logs/entries{
"data": [
{
"attributes": {
"log_source": "maxlog",
"message": "Server changed state: server2[127.0.0.1:3001]: slave_up. [Down] -> [Slave, Running]",
"priority": "notice",
"timestamp": "2025-07-25 15:43:48",
"unix_timestamp": 1753458228
},
"id": "38",
"type": "log_entry"
},
{
"attributes": {
"log_source": "maxlog",
"message": "Read 8 user@host entries from 'server1' for service 'RW-Split-Router'.",
"priority": "notice",
"timestamp": "2025-07-25 15:43:49",
"unix_timestamp": 1753458229
},
"id": "39",
"type": "log_entry"
},
{
"attributes": {
"log_source": "maxlog",
"message": "Read 8 user@host entries from 'server1' for service 'Read-Connection-Router'.",
"priority": "notice",
"timestamp": "2025-07-25 15:43:49",
"unix_timestamp": 1753458229
},
"id": "40",
"type": "log_entry"
}
],
"links": {
"last": "http://localhost:8989/v1/maxscale/logs/entries/?page%5Bsize%5D=3",
"prev": "http://localhost:8989/v1/maxscale/logs/entries/?page%5Bcursor%5D=35&page%5Bsize%5D=3",
"self": "http://localhost:8989/v1/maxscale/logs/entries/?page%5Bcursor%5D=38&page%5Bsize%5D=3"
},
"meta": {
"total": 3
}
}GET /v1/maxscale/logs/stream{
"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/logsPOST /v1/maxscale/logs/flushPOST /v1/maxscale/tls/reloadGET /v1/maxscale/modules/:name{
"data": {
"attributes": {
"api": "router",
"commands": [
{
"attributes": {
"arg_max": 1,
"arg_min": 1,
"description": "Reset global GTID state in readwritesplit.",
"method": "POST",
"parameters": [
{
"description": "Readwritesplit service",
"required": true,
"type": "SERVICE"
}
]
},
"id": "reset-gtid",
"links": {
"self": "http://localhost:8989/v1/modules/readwritesplit/reset-gtid/"
},
"type": "module_command"
}
],
"description": "A Read/Write splitting router for enhancement read scalability",
"groups": [
{
"description": "Settings that control how queries are routed",
"members": [
"use_sql_variables_in",
"slave_selection_criteria",
"max_replication_lag",
"max_slave_replication_lag",
"strict_multi_stmt",
"strict_sp_calls",
"strict_tmp_tables",
"master_accept_reads",
"max_slave_connections",
"slave_connections",
"lazy_connect"
],
"name": "Routing"
},
{
"description": "Settings that control how node failures are handled",
"members": [
"master_failure_mode",
"retry_failed_reads",
"master_reconnection",
"delayed_retry",
"delayed_retry_timeout"
],
"name": "Error Handling"
},
{
"description": "Settings that control the causal reads feature",
"members": [
"causal_reads",
"causal_reads_timeout"
],
"name": "Causal Reads"
},
{
"description": "Settings that control the transaction replay feature",
"members": [
"transaction_replay",
"transaction_replay_max_size",
"transaction_replay_timeout",
"transaction_replay_attempts",
"transaction_replay_retry_on_deadlock",
"transaction_replay_retry_on_mismatch",
"transaction_replay_safe_commit",
"transaction_replay_checksum"
],
"name": "Transaction Replay"
},
{
"description": "Settings that control the synchronous transaction feature",
"members": [
"sync_transaction",
"sync_transaction_count",
"sync_transaction_timeout",
"sync_transaction_max_lag"
],
"name": "Synchronous Transaction"
}
],
"module_type": "Router",
"parameters": [
{
"default_value": "none",
"description": "Causal reads mode",
"enum_values": [
"none",
"local",
"global",
"fast_global",
"fast",
"universal",
"fast_universal",
"false",
"off",
"0",
"true",
"on",
"1"
],
"group": "Causal Reads",
"mandatory": false,
"modifiable": true,
"name": "causal_reads",
"type": "enum"
},
{
"default_value": "10000ms",
"description": "Timeout for the slave synchronization",
"group": "Causal Reads",
"mandatory": false,
"modifiable": true,
"name": "causal_reads_timeout",
"type": "duration",
"unit": "s"
},
{
"default_value": false,
"description": "Retry failed writes outside of transactions",
"group": "Error Handling",
"mandatory": false,
"modifiable": true,
"name": "delayed_retry",
"type": "bool"
},
{
"default_value": "10000ms",
"description": "Timeout for delayed_retry",
"group": "Error Handling",
"mandatory": false,
"modifiable": true,
"name": "delayed_retry_timeout",
"type": "duration",
"unit": "s"
},
{
"default_value": false,
"description": "Create connections only when needed",
"group": "Routing",
"mandatory": false,
"modifiable": true,
"name": "lazy_connect",
"type": "bool"
},
{
"default_value": false,
"description": "Use master for reads",
"group": "Routing",
"mandatory": false,
"modifiable": true,
"name": "master_accept_reads",
"type": "bool"
},
{
"default_value": "fail_on_write",
"description": "Master failure mode behavior",
"enum_values": [
"fail_instantly",
"fail_on_write",
"error_on_write"
],
"group": "Error Handling",
"mandatory": false,
"modifiable": true,
"name": "master_failure_mode",
"type": "enum"
},
{
"default_value": true,
"description": "Reconnect to master",
"group": "Error Handling",
"mandatory": false,
"modifiable": true,
"name": "master_reconnection",
"type": "bool"
},
{
"default_value": "0ms",
"description": "Maximum replication lag",
"group": "Routing",
"mandatory": false,
"modifiable": true,
"name": "max_replication_lag",
"type": "duration",
"unit": "s"
},
{
"default_value": 255,
"description": "Maximum number of slave connections",
"group": "Routing",
"mandatory": false,
"modifiable": true,
"name": "max_slave_connections",
"type": "count"
},
{
"deprecated": true,
"description": "Alias for 'max_replication_lag'",
"group": "Routing",
"mandatory": false,
"modifiable": true,
"name": "max_slave_replication_lag",
"type": "duration"
},
{
"default_value": true,
"description": "Automatically retry failed reads outside of transactions",
"group": "Error Handling",
"mandatory": false,
"modifiable": true,
"name": "retry_failed_reads",
"type": "bool"
},
{
"default_value": 255,
"description": "Starting number of slave connections",
"group": "Routing",
"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",
"LEAST_GLOBAL_CONNECTIONS",
"LEAST_ROUTER_CONNECTIONS",
"LEAST_BEHIND_MASTER",
"LEAST_CURRENT_OPERATIONS",
"ADAPTIVE_ROUTING"
],
"group": "Routing",
"mandatory": false,
"modifiable": true,
"name": "slave_selection_criteria",
"type": "enum"
},
{
"default_value": false,
"description": "Lock connection to master after multi-statement query",
"group": "Routing",
"mandatory": false,
"modifiable": true,
"name": "strict_multi_stmt",
"type": "bool"
},
{
"default_value": false,
"description": "Lock connection to master after a stored procedure is executed",
"group": "Routing",
"mandatory": false,
"modifiable": true,
"name": "strict_sp_calls",
"type": "bool"
},
{
"default_value": true,
"description": "Prevent reconnections if temporary tables exist",
"group": "Routing",
"mandatory": false,
"modifiable": true,
"name": "strict_tmp_tables",
"type": "bool"
},
{
"default_value": "none",
"description": "Synchronize transactions with one or more replicas.",
"enum_values": [
"none",
"soft",
"hard"
],
"group": "Synchronous Transaction",
"mandatory": false,
"modifiable": true,
"name": "sync_transaction",
"type": "enum"
},
{
"default_value": 1,
"description": "Number of acknowledgements required for each transaction.",
"group": "Synchronous Transaction",
"mandatory": false,
"modifiable": true,
"name": "sync_transaction_count",
"type": "count"
},
{
"default_value": "0ms",
"description": "Maximum allowed replication lag before synchronization starts.",
"group": "Synchronous Transaction",
"mandatory": false,
"modifiable": true,
"name": "sync_transaction_max_lag",
"type": "duration",
"unit": "ms"
},
{
"default_value": "10000ms",
"description": "Timeout for transaction synchronization.",
"group": "Synchronous Transaction",
"mandatory": false,
"modifiable": true,
"name": "sync_transaction_timeout",
"type": "duration",
"unit": "ms"
},
{
"default_value": false,
"description": "Retry failed transactions",
"group": "Transaction Replay",
"mandatory": false,
"modifiable": true,
"name": "transaction_replay",
"type": "bool"
},
{
"default_value": 5,
"description": "Maximum number of times to retry a transaction",
"group": "Transaction Replay",
"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"
],
"group": "Transaction Replay",
"mandatory": false,
"modifiable": true,
"name": "transaction_replay_checksum",
"type": "enum"
},
{
"default_value": 1048576,
"description": "Maximum size of transaction to retry",
"group": "Transaction Replay",
"mandatory": false,
"modifiable": true,
"name": "transaction_replay_max_size",
"type": "size"
},
{
"default_value": false,
"description": "Retry transaction on deadlock",
"group": "Transaction Replay",
"mandatory": false,
"modifiable": true,
"name": "transaction_replay_retry_on_deadlock",
"type": "bool"
},
{
"default_value": false,
"description": "Retry transaction on checksum mismatch",
"group": "Transaction Replay",
"mandatory": false,
"modifiable": true,
"name": "transaction_replay_retry_on_mismatch",
"type": "bool"
},
{
"default_value": true,
"description": "Prevent replaying of about-to-commit transaction",
"group": "Transaction Replay",
"mandatory": false,
"modifiable": true,
"name": "transaction_replay_safe_commit",
"type": "bool"
},
{
"default_value": "30000ms",
"description": "Timeout for transaction replay",
"group": "Transaction Replay",
"mandatory": false,
"modifiable": true,
"name": "transaction_replay_timeout",
"type": "duration",
"unit": "s"
},
{
"default_value": "all",
"description": "Whether to route SQL variable modifications to all servers or only to the master",
"enum_values": [
"all",
"master"
],
"group": "Routing",
"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": "s"
},
{
"deprecated": true,
"description": "Alias for 'wait_timeout'",
"mandatory": false,
"modifiable": true,
"name": "connection_timeout",
"type": "duration"
},
{
"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": false,
"description": "Ping connections unconditionally",
"mandatory": false,
"modifiable": true,
"name": "force_connection_keepalive",
"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": "s"
},
{
"default_value": "0ms",
"description": "Network write timeout",
"mandatory": false,
"modifiable": true,
"name": "net_write_timeout",
"type": "duration",
"unit": "s"
},
{
"description": "Password for the user used to retrieve database users",
"mandatory": true,
"modifiable": true,
"name": "password",
"type": "password"
},
{
"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"
},
{
"description": "Role used for retrieving database users",
"mandatory": false,
"modifiable": true,
"name": "role",
"type": "string"
},
{
"default_value": false,
"deprecated": true,
"description": "Track session state using server responses",
"mandatory": false,
"modifiable": true,
"name": "session_track_trx_state",
"type": "bool"
},
{
"default_value": true,
"deprecated": 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"
},
{
"default_value": "28800000ms",
"description": "Connection idle timeout",
"mandatory": false,
"modifiable": true,
"name": "wait_timeout",
"type": "duration",
"unit": "s"
}
]
},
"id": "readwritesplit",
"links": {
"self": "http://localhost:8989/v1/modules/readwritesplit/"
},
"type": "modules"
},
"links": {
"self": "http://localhost:8989/v1/maxscale/modules/"
}
}GET /v1/maxscale/modules{
"data": [
{
"attributes": {
"commands": [],
"description": "maxscale",
"maturity": "GA",
"module_type": "maxscale",
"parameters": [
{
"default_value": false,
"description": "Enable REST audit logging",
"mandatory": false,
"modifiable": true,
"name": "admin_audit",
"type": "bool"
},
{
"default_value": [],
"description": "List of HTTP methods to exclude from audit logging, e.g. \"GET\"",
"enum_values": [
"GET",
"PUT",
"POST",
"PATCH",
"DELETE",
"HEAD",
"CONNECT",
"OPTIONS",
"TRACE"
],
"mandatory": false,
"modifiable": true,
"name": "admin_audit_exclude_methods",
"type": "enum list"
},
{
"default_value": "admin_audit.csv",
"description": "Full path to admin audit file",
"mandatory": false,
"modifiable": true,
"name": "admin_audit_file",
"type": "string"
},
{
"default_value": true,
"description": "Admin interface authentication.",
"mandatory": false,
"modifiable": false,
"name": "admin_auth",
"type": "bool"
},
{
"default_value": true,
"description": "Admin interface is enabled.",
"mandatory": false,
"modifiable": false,
"name": "admin_enabled",
"type": "bool"
},
{
"default_value": true,
"description": "Enable admin GUI.",
"mandatory": false,
"modifiable": false,
"name": "admin_gui",
"type": "bool"
},
{
"default_value": "127.0.0.1",
"description": "Admin interface host.",
"mandatory": false,
"modifiable": false,
"name": "admin_host",
"type": "string"
},
{
"default_value": "auto",
"description": "JWT signature algorithm",
"enum_values": [
"auto",
"HS256",
"HS384",
"HS512",
"RS256",
"RS384",
"RS512",
"ES256",
"ES384",
"ES512",
"PS256",
"PS384",
"PS512",
"ED25519",
"ED448"
],
"mandatory": false,
"modifiable": false,
"name": "admin_jwt_algorithm",
"type": "enum"
},
{
"default_value": "maxscale",
"description": "The issuer claim for all JWTs generated by MaxScale.",
"mandatory": false,
"modifiable": false,
"name": "admin_jwt_issuer",
"type": "string"
},
{
"description": "Encryption key ID for symmetric signature algorithms. If left empty, MaxScale will generate a random key that is used to sign the JWT.",
"mandatory": false,
"modifiable": false,
"name": "admin_jwt_key",
"type": "string"
},
{
"default_value": "86400000ms",
"description": "Maximum age of the JWTs generated by MaxScale",
"mandatory": false,
"modifiable": true,
"name": "admin_jwt_max_age",
"type": "duration",
"unit": "s"
},
{
"default_value": true,
"description": "Log admin interface authentication failures.",
"mandatory": false,
"modifiable": true,
"name": "admin_log_auth_failures",
"type": "bool"
},
{
"description": "Client ID used for OIDC authentication",
"mandatory": false,
"modifiable": true,
"name": "admin_oidc_client_id",
"type": "string"
},
{
"description": "Client secret used for OIDC authentication",
"mandatory": false,
"modifiable": true,
"name": "admin_oidc_client_secret",
"type": "password"
},
{
"default_value": "auto",
"description": "OIDC authentication flow",
"enum_values": [
"auto",
"implicit",
"code"
],
"mandatory": false,
"modifiable": true,
"name": "admin_oidc_flow",
"type": "enum"
},
{
"description": "Extra public certificates used to validate externally signed JWTs",
"mandatory": false,
"modifiable": true,
"name": "admin_oidc_url",
"type": "string"
},
{
"description": "PAM service for read-only users.",
"mandatory": false,
"modifiable": false,
"name": "admin_pam_readonly_service",
"type": "string"
},
{
"description": "PAM service for read-write users.",
"mandatory": false,
"modifiable": false,
"name": "admin_pam_readwrite_service",
"type": "string"
},
{
"default_value": 8989,
"description": "Admin interface port.",
"mandatory": false,
"modifiable": false,
"name": "admin_port",
"type": "int"
},
{
"default_value": "%",
"description": "Allowed hosts for read-only rest-api users.",
"mandatory": false,
"modifiable": false,
"name": "admin_readonly_hosts",
"type": "host pattern list"
},
{
"default_value": "%",
"description": "Allowed hosts for read-only rest-api users.",
"mandatory": false,
"modifiable": false,
"name": "admin_readwrite_hosts",
"type": "host pattern list"
},
{
"default_value": true,
"description": "Only serve GUI over HTTPS.",
"mandatory": false,
"modifiable": false,
"name": "admin_secure_gui",
"type": "bool"
},
{
"description": "Admin SSL CA cert",
"mandatory": false,
"modifiable": false,
"name": "admin_ssl_ca",
"type": "path"
},
{
"deprecated": true,
"description": "Alias for 'admin_ssl_ca'",
"mandatory": false,
"modifiable": false,
"name": "admin_ssl_ca_cert",
"type": "path"
},
{
"description": "Admin SSL cert",
"mandatory": false,
"modifiable": true,
"name": "admin_ssl_cert",
"type": "path"
},
{
"description": "Additional SSL cipher priorities for admin connections.",
"mandatory": false,
"modifiable": false,
"name": "admin_ssl_cipher",
"type": "string"
},
{
"description": "Admin SSL key",
"mandatory": false,
"modifiable": true,
"name": "admin_ssl_key",
"type": "path"
},
{
"default_value": "MAX",
"description": "Enabled TLS protocol versions for the REST API",
"enum_values": [
"MAX",
"TLSv10",
"TLSv11",
"TLSv12",
"TLSv13",
"TLSv1.0",
"TLSv1.1",
"TLSv1.2",
"TLSv1.3"
],
"mandatory": false,
"modifiable": false,
"name": "admin_ssl_version",
"type": "enum_mask"
},
{
"description": "URL for third-party verification of client tokens",
"mandatory": false,
"modifiable": false,
"name": "admin_verify_url",
"type": "string"
},
{
"default_value": "10000ms",
"description": "Connection timeout for fetching user accounts.",
"mandatory": false,
"modifiable": true,
"name": "auth_connect_timeout",
"type": "duration",
"unit": "s"
},
{
"default_value": "10000ms",
"description": "Read timeout for fetching user accounts (deprecated).",
"mandatory": false,
"modifiable": true,
"name": "auth_read_timeout",
"type": "duration",
"unit": "s"
},
{
"default_value": "10000ms",
"description": "Write timeout for for fetching user accounts (deprecated).",
"mandatory": false,
"modifiable": true,
"name": "auth_write_timeout",
"type": "duration",
"unit": "s"
},
{
"default_value": [],
"description": "Specifies whether a MaxScale parameter whose value depends on a specific global server variable, should automatically be updated to match the variable's current value.",
"mandatory": false,
"modifiable": false,
"name": "auto_tune",
"type": "stringlist"
},
{
"description": "Cluster used for configuration synchronization. If left empty (i.e. value is \"\"), synchronization is not done.",
"mandatory": false,
"modifiable": true,
"name": "config_sync_cluster",
"type": "string"
},
{
"default_value": "mysql",
"description": "Database where the 'maxscale_config' table is created.",
"mandatory": false,
"modifiable": false,
"name": "config_sync_db",
"type": "string"
},
{
"default_value": "5000ms",
"description": "How often to synchronize the configuration.",
"mandatory": false,
"modifiable": true,
"name": "config_sync_interval",
"type": "duration",
"unit": "ms"
},
{
"description": "Password for the user used for configuration synchronization.",
"mandatory": false,
"modifiable": true,
"name": "config_sync_password",
"type": "password"
},
{
"default_value": "10000ms",
"description": "Timeout for the configuration synchronization operations.",
"mandatory": false,
"modifiable": true,
"name": "config_sync_timeout",
"type": "duration",
"unit": "s"
},
{
"description": "User account used for configuration synchronization.",
"mandatory": false,
"modifiable": true,
"name": "config_sync_user",
"type": "string"
},
{
"default_value": true,
"description": "Write a core-file if MaxScale crashes.",
"mandatory": false,
"modifiable": false,
"name": "core_file",
"type": "bool"
},
{
"description": "Debug options",
"mandatory": false,
"modifiable": false,
"name": "debug",
"type": "string"
},
{
"default_value": "never",
"description": "In what circumstances should the last statements that a client sent be dumped.",
"enum_values": [
"on_close",
"on_error",
"never"
],
"mandatory": false,
"modifiable": true,
"name": "dump_last_statements",
"type": "enum"
},
{
"default_value": "LOG_USER",
"description": "The facility using which authentication failures should be logged.",
"enum_values": [
"LOG_AUTH",
"LOG_AUTHPRIV",
"LOG_CRON",
"LOG_DAEMON",
"LOG_FTP",
"LOG_KERN",
"LOG_LOCAL0",
"LOG_LOCAL1",
"LOG_LOCAL2",
"LOG_LOCAL3",
"LOG_LOCAL4",
"LOG_LOCAL5",
"LOG_LOCAL6",
"LOG_LOCAL7",
"LOG_LPR",
"LOG_MAIL",
"LOG_NEWS",
"LOG_SYSLOG",
"LOG_USER",
"LOG_UUCP"
],
"mandatory": false,
"modifiable": true,
"name": "event_authentication_failure_facility",
"type": "enum"
},
{
"default_value": "LOG_WARNING",
"description": "The level/priority using which authentication failures should be logged.",
"enum_values": [
"LOG_ALERT",
"LOG_CRIT",
"LOG_DEBUG",
"LOG_EMERG",
"LOG_ERR",
"LOG_INFO",
"LOG_NOTICE",
"LOG_WARNING"
],
"mandatory": false,
"modifiable": true,
"name": "event_authentication_failure_level",
"type": "enum"
},
{
"default_value": "LOG_USER",
"description": "The facility using which firewall incidents should be logged.",
"enum_values": [
"LOG_AUTH",
"LOG_AUTHPRIV",
"LOG_CRON",
"LOG_DAEMON",
"LOG_FTP",
"LOG_KERN",
"LOG_LOCAL0",
"LOG_LOCAL1",
"LOG_LOCAL2",
"LOG_LOCAL3",
"LOG_LOCAL4",
"LOG_LOCAL5",
"LOG_LOCAL6",
"LOG_LOCAL7",
"LOG_LPR",
"LOG_MAIL",
"LOG_NEWS",
"LOG_SYSLOG",
"LOG_USER",
"LOG_UUCP"
],
"mandatory": false,
"modifiable": true,
"name": "event_firewall_incident_facility",
"type": "enum"
},
{
"default_value": "LOG_WARNING",
"description": "The level/priority using which firewall incidents should be logged.",
"enum_values": [
"LOG_ALERT",
"LOG_CRIT",
"LOG_DEBUG",
"LOG_EMERG",
"LOG_ERR",
"LOG_INFO",
"LOG_NOTICE",
"LOG_WARNING"
],
"mandatory": false,
"modifiable": true,
"name": "event_firewall_incident_level",
"type": "enum"
},
{
"default_value": 128,
"description": "Size of the reverse hostname resolution cache",
"mandatory": false,
"modifiable": true,
"name": "host_cache_size",
"type": "count"
},
{
"default_value": "none",
"description": "Key manager type",
"enum_values": [
"none",
"file",
"kmip",
"vault"
],
"mandatory": false,
"modifiable": true,
"name": "key_manager",
"type": "enum"
},
{
"default_value": true,
"description": "Specifies whether persisted configuration files should be loaded on startup.",
"mandatory": false,
"modifiable": false,
"name": "load_persisted_configs",
"type": "bool"
},
{
"description": "Local address to use when connecting.",
"mandatory": false,
"modifiable": false,
"name": "local_address",
"type": "string"
},
{
"default_value": false,
"description": "Specifies whether debug messages should be logged (meaningful only with debug builds).",
"mandatory": false,
"modifiable": true,
"name": "log_debug",
"type": "bool"
},
{
"default_value": false,
"description": "Specifies whether info messages should be logged.",
"mandatory": false,
"modifiable": true,
"name": "log_info",
"type": "bool"
},
{
"default_value": true,
"description": "Specifies whether notice messages should be logged.",
"mandatory": false,
"modifiable": true,
"name": "log_notice",
"type": "bool"
},
{
"default_value": {
"count": 10,
"suppress": 10000,
"window": 1000
},
"description": "Limit the amount of identical log messages than can be logged during a certain time period.",
"mandatory": false,
"modifiable": true,
"name": "log_throttling",
"type": "throttling"
},
{
"default_value": false,
"description": "Log a warning when a user with super privilege logs in.",
"mandatory": false,
"modifiable": false,
"name": "log_warn_super_user",
"type": "bool"
},
{
"default_value": true,
"description": "Specifies whether warning messages should be logged.",
"mandatory": false,
"modifiable": true,
"name": "log_warning",
"type": "bool"
},
{
"default_value": 10,
"description": "The maximum number of authentication failures that are tolerated before a host is temporarily blocked.",
"mandatory": false,
"modifiable": true,
"name": "max_auth_errors_until_block",
"type": "int"
},
{
"default_value": true,
"description": "Log to MaxScale's own log.",
"mandatory": false,
"modifiable": true,
"name": "maxlog",
"type": "bool"
},
{
"default_value": false,
"description": "Enable or disable high precision timestamps.",
"mandatory": false,
"modifiable": true,
"name": "ms_timestamp",
"type": "bool"
},
{
"default_value": false,
"deprecated": true,
"description": "True if MaxScale is in passive mode.",
"mandatory": false,
"modifiable": true,
"name": "passive",
"type": "bool"
},
{
"default_value": true,
"description": "Persist configurations changes done at runtime.",
"mandatory": false,
"modifiable": false,
"name": "persist_runtime_changes",
"type": "bool"
},
{
"default_value": "qc_sqlite",
"deprecated": true,
"description": "The name of the query classifier to load.",
"mandatory": false,
"modifiable": false,
"name": "query_classifier",
"type": "string"
},
{
"deprecated": true,
"description": "Arguments for the query classifier.",
"mandatory": false,
"modifiable": false,
"name": "query_classifier_args",
"type": "string"
},
{
"default_value": 5002190438,
"description": "Maximum amount of memory used by query classifier cache.",
"mandatory": false,
"modifiable": true,
"name": "query_classifier_cache_size",
"type": "size"
},
{
"default_value": 1,
"deprecated": true,
"description": "Number of times an interrupted query is retried.",
"mandatory": false,
"modifiable": false,
"name": "query_retries",
"type": "int"
},
{
"default_value": "5000ms",
"deprecated": true,
"description": "The total timeout in seconds for any retried queries.",
"mandatory": false,
"modifiable": true,
"name": "query_retry_timeout",
"type": "duration",
"unit": "s"
},
{
"default_value": "0ms",
"description": "How often should the load of the worker threads be checked and rebalancing be made.",
"mandatory": false,
"modifiable": true,
"name": "rebalance_period",
"type": "duration",
"unit": "ms"
},
{
"default_value": 20,
"description": "If the difference in load between the thread with the maximum load and the thread with the minimum load is larger than the value of this parameter, then work will be moved from the former to the latter.",
"mandatory": false,
"modifiable": true,
"name": "rebalance_threshold",
"type": "int"
},
{
"default_value": 10,
"description": "The load of how many seconds should be taken into account when rebalancing.",
"mandatory": false,
"modifiable": true,
"name": "rebalance_window",
"type": "count"
},
{
"default_value": false,
"description": "All connections must use SSL.",
"mandatory": false,
"modifiable": false,
"name": "require_secure_transport",
"type": "bool"
},
{
"default_value": 0,
"description": "How many statements should be retained for each session for debugging purposes.",
"mandatory": false,
"modifiable": true,
"name": "retain_last_statements",
"type": "count"
},
{
"description": "Directory where the .secrets encryption key is located in.",
"mandatory": false,
"modifiable": false,
"name": "secretsdir",
"type": "path"
},
{
"default_value": 0,
"description": "How many log entries are stored in the session specific trace log.",
"mandatory": false,
"modifiable": true,
"name": "session_trace",
"type": "count"
},
{
"description": "Regular expression that is matched against the contents of the session trace log and if it matches the contents are logged when the session stops.",
"mandatory": false,
"modifiable": true,
"name": "session_trace_match",
"type": "regex"
},
{
"default_value": false,
"description": "Do not resolve client IP addresses to hostnames during authentication",
"mandatory": false,
"modifiable": true,
"name": "skip_name_resolve",
"type": "bool"
},
{
"default_value": false,
"deprecated": true,
"description": "Skip service and monitor permission checks.",
"mandatory": false,
"modifiable": true,
"name": "skip_permission_checks",
"type": "bool"
},
{
"default_value": "default",
"description": "The query classifier sql mode.",
"enum_values": [
"default",
"oracle"
],
"mandatory": false,
"modifiable": false,
"name": "sql_mode",
"type": "enum"
},
{
"default_value": false,
"description": "Log to syslog.",
"mandatory": false,
"modifiable": true,
"name": "syslog",
"type": "bool"
},
{
"default_value": false,
"description": "When enabled maxscale sends telemetry to the default otel Collector",
"mandatory": false,
"modifiable": false,
"name": "telemetry",
"type": "bool"
},
{
"default_value": 8,
"description": "This parameter specifies how many threads will be used for handling the routing.",
"mandatory": false,
"modifiable": true,
"name": "threads",
"type": "count"
},
{
"default_value": 256,
"description": "This parameter specifies a hard maximum for the number of routing threads.",
"mandatory": false,
"modifiable": false,
"name": "threads_max",
"type": "count"
},
{
"description": "Directory where trace files are stored at",
"mandatory": false,
"modifiable": false,
"name": "trace_file_dir",
"type": "path"
},
{
"default_value": 0,
"description": "How many bytes of the trace log is retained",
"mandatory": false,
"modifiable": true,
"name": "trace_file_size",
"type": "size"
},
{
"default_value": "0ms",
"description": "How often the users will be refreshed.",
"mandatory": false,
"modifiable": true,
"name": "users_refresh_interval",
"type": "duration",
"unit": "s"
},
{
"default_value": "30000ms",
"description": "How often the users can be refreshed.",
"mandatory": false,
"modifiable": true,
"name": "users_refresh_time",
"type": "duration",
"unit": "s"
},
{
"default_value": 65536,
"description": "High water mark of dcb write queue.",
"mandatory": false,
"modifiable": true,
"name": "writeq_high_water",
"type": "size"
},
{
"default_value": 1024,
"description": "Low water mark of dcb write queue.",
"mandatory": false,
"modifiable": true,
"name": "writeq_low_water",
"type": "size"
}
],
"version": "99.99.99"
},
"id": "maxscale",
"links": {
"self": "http://localhost:8989/v1/modules/maxscale/"
},
"type": "modules"
},
{
"attributes": {
"commands": [],
"description": "servers",
"maturity": "GA",
"module_type": "servers",
"parameters": [
{
"description": "Server address",
"mandatory": false,
"modifiable": true,
"name": "address",
"type": "string"
},
{
"description": "Server authenticator (deprecated)",
"mandatory": false,
"modifiable": false,
"name": "authenticator",
"type": "string"
},
{
"default_value": "",
"description": "Server disk space threshold",
"mandatory": false,
"modifiable": true,
"name": "disk_space_threshold",
"type": "disk_space_limits"
},
{
"default_value": 0,
"description": "Server extra port",
"mandatory": false,
"modifiable": true,
"name": "extra_port",
"type": "count"
},
{
"default_value": "down",
"description": "Initial server status",
"enum_values": [
"down",
"up",
"write",
"read"
],
"mandatory": false,
"modifiable": true,
"name": "initial_status",
"type": "enum"
},
{
"default_value": 0,
"description": "Maximum routing connections",
"mandatory": false,
"modifiable": true,
"name": "max_routing_connections",
"type": "count"
},
{
"description": "Monitor password",
"mandatory": false,
"modifiable": true,
"name": "monitorpw",
"type": "password"
},
{
"description": "Monitor user",
"mandatory": false,
"modifiable": true,
"name": "monitoruser",
"type": "string"
},
{
"default_value": "0ms",
"description": "Maximum time that a connection can be in the pool",
"mandatory": false,
"modifiable": true,
"name": "persistmaxtime",
"type": "duration",
"unit": "s"
},
{
"default_value": 0,
"description": "Maximum size of the persistent connection pool",
"mandatory": false,
"modifiable": true,
"name": "persistpoolmax",
"type": "count"
},
{
"default_value": 3306,
"description": "Server port",
"mandatory": false,
"modifiable": true,
"name": "port",
"type": "count"
},
{
"default_value": 0,
"description": "Server priority",
"mandatory": false,
"modifiable": true,
"name": "priority",
"type": "int"
},
{
"description": "Server private address (replication)",
"mandatory": false,
"modifiable": true,
"name": "private_address",
"type": "string"
},
{
"description": "Server protocol (deprecated)",
"mandatory": false,
"modifiable": false,
"name": "protocol",
"type": "string"
},
{
"default_value": false,
"description": "Enable proxy protocol",
"mandatory": false,
"modifiable": true,
"name": "proxy_protocol",
"type": "bool"
},
{
"default_value": "primary",
"description": "Server rank",
"enum_values": [
"primary",
"secondary"
],
"mandatory": false,
"modifiable": true,
"name": "rank",
"type": "enum"
},
{
"description": "Custom CHANGE MASTER TO options",
"mandatory": false,
"modifiable": true,
"name": "replication_custom_options",
"type": "string"
},
{
"description": "Server UNIX socket",
"mandatory": false,
"modifiable": true,
"name": "socket",
"type": "string"
},
{
"default_value": false,
"description": "Enable TLS for server",
"mandatory": false,
"modifiable": true,
"name": "ssl",
"type": "bool"
},
{
"description": "TLS certificate authority",
"mandatory": false,
"modifiable": true,
"name": "ssl_ca",
"type": "path"
},
{
"deprecated": true,
"description": "Alias for 'ssl_ca'",
"mandatory": false,
"modifiable": true,
"name": "ssl_ca_cert",
"type": "path"
},
{
"description": "TLS public certificate",
"mandatory": false,
"modifiable": true,
"name": "ssl_cert",
"type": "path"
},
{
"default_value": 9,
"description": "TLS certificate verification depth",
"mandatory": false,
"modifiable": true,
"name": "ssl_cert_verify_depth",
"type": "count"
},
{
"description": "TLS cipher list",
"mandatory": false,
"modifiable": true,
"name": "ssl_cipher",
"type": "string"
},
{
"description": "TLS private key",
"mandatory": false,
"modifiable": true,
"name": "ssl_key",
"type": "path"
},
{
"default_value": "",
"description": "Passphrase for TLS key",
"mandatory": false,
"modifiable": true,
"name": "ssl_passphrase",
"type": "sslpassphrase"
},
{
"default_value": false,
"description": "Verify TLS peer certificate",
"mandatory": false,
"modifiable": true,
"name": "ssl_verify_peer_certificate",
"type": "bool"
},
{
"default_value": false,
"description": "Verify TLS peer host",
"mandatory": false,
"modifiable": true,
"name": "ssl_verify_peer_host",
"type": "bool"
},
{
"default_value": "MAX",
"description": "Enabled TLS protocol versions",
"enum_values": [
"MAX",
"TLSv10",
"TLSv11",
"TLSv12",
"TLSv13",
"TLSv1.0",
"TLSv1.1",
"TLSv1.2",
"TLSv1.3"
],
"mandatory": false,
"modifiable": true,
"name": "ssl_version",
"type": "enum_mask"
},
{
"default_value": "server",
"description": "Object type",
"mandatory": false,
"modifiable": false,
"name": "type",
"type": "string"
},
{
"default_value": true,
"description": "Use the service credentials to log in and then switch to the client user. This feature is only used with MariaDB version 12 or newer.",
"mandatory": false,
"modifiable": true,
"name": "use_service_credentials",
"type": "bool"
}
],
"version": "99.99.99"
},
"id": "servers",
"links": {
"self": "http://localhost:8989/v1/modules/servers/"
},
"type": "modules"
},
{
"attributes": {
"api": "filter",
"commands": [],
"description": "A hint parsing filter",
"groups": [],
"module_type": "Filter",
"parameters": []
},
"id": "hintfilter",
"links": {
"self": "http://localhost:8989/v1/modules/hintfilter/"
},
"type": "modules"
},
{
"attributes": {
"api": "authenticator",
"commands": [],
"description": "Standard MySQL/MariaDB authentication (mysql_native_password)",
"groups": [],
"module_type": "Authenticator",
"parameters": []
},
"id": "MariaDBAuth",
"links": {
"self": "http://localhost:8989/v1/modules/MariaDBAuth/"
},
"type": "modules"
},
{
"attributes": {
"api": "monitor",
"commands": [
{
"attributes": {
"arg_max": 3,
"arg_min": 3,
"description": "Create a backup with Mariabackup. Does not wait for completion.",
"method": "POST",
"parameters": [
{
"description": "Monitor name",
"required": true,
"type": "MONITOR"
},
{
"description": "Source server",
"required": true,
"type": "SERVER"
},
{
"description": "Backup name",
"required": true,
"type": "STRING"
}
]
},
"id": "async-create-backup",
"links": {
"self": "http://localhost:8989/v1/modules/mariadbmon/async-create-backup/"
},
"type": "module_command"
},
{
"attributes": {
"arg_max": 3,
"arg_min": 3,
"description": "Add a node to a ColumnStore cluster. Does not wait for completion.",
"method": "POST",
"parameters": [
{
"description": "Monitor name",
"required": true,
"type": "MONITOR"
},
{
"description": "Hostname/IP of node to add to ColumnStore cluster",
"required": true,
"type": "STRING"
},
{
"description": "Timeout",
"required": true,
"type": "STRING"
}
]
},
"id": "async-cs-add-node",
"links": {
"self": "http://localhost:8989/v1/modules/mariadbmon/async-cs-add-node/"
},
"type": "module_command"
},
{
"attributes": {
"arg_max": 1,
"arg_min": 1,
"description": "Get ColumnStore cluster status. Does not wait for completion.",
"method": "POST",
"parameters": [
{
"description": "Monitor name",
"required": true,
"type": "MONITOR"
}
]
},
"id": "async-cs-get-status",
"links": {
"self": "http://localhost:8989/v1/modules/mariadbmon/async-cs-get-status/"
},
"type": "module_command"
},
{
"attributes": {
"arg_max": 3,
"arg_min": 3,
"description": "Remove a node from a ColumnStore cluster. Does not wait for completion.",
"method": "POST",
"parameters": [
{
"description": "Monitor name",
"required": true,
"type": "MONITOR"
},
{
"description": "Hostname/IP of node to remove from ColumnStore cluster",
"required": true,
"type": "STRING"
},
{
"description": "Timeout",
"required": true,
"type": "STRING"
}
]
},
"id": "async-cs-remove-node",
"links": {
"self": "http://localhost:8989/v1/modules/mariadbmon/async-cs-remove-node/"
},
"type": "module_command"
},
{
"attributes": {
"arg_max": 2,
"arg_min": 2,
"description": "Set ColumnStore cluster read-only. Does not wait for completion.",
"method": "POST",
"parameters": [
{
"description": "Monitor name",
"required": true,
"type": "MONITOR"
},
{
"description": "Timeout",
"required": true,
"type": "STRING"
}
]
},
"id": "async-cs-set-readonly",
"links": {
"self": "http://localhost:8989/v1/modules/mariadbmon/async-cs-set-readonly/"
},
"type": "module_command"
},
{
"attributes": {
"arg_max": 2,
"arg_min": 2,
"description": "Set ColumnStore cluster readwrite. Does not wait for completion.",
"method": "POST",
"parameters": [
{
"description": "Monitor name",
"required": true,
"type": "MONITOR"
},
{
"description": "Timeout",
"required": true,
"type": "STRING"
}
]
},
"id": "async-cs-set-readwrite",
"links": {
"self": "http://localhost:8989/v1/modules/mariadbmon/async-cs-set-readwrite/"
},
"type": "module_command"
},
{
"attributes": {
"arg_max": 2,
"arg_min": 2,
"description": "Start ColumnStore cluster. Does not wait for completion.",
"method": "POST",
"parameters": [
{
"description": "Monitor name",
"required": true,
"type": "MONITOR"
},
{
"description": "Timeout",
"required": true,
"type": "STRING"
}
]
},
"id": "async-cs-start-cluster",
"links": {
"self": "http://localhost:8989/v1/modules/mariadbmon/async-cs-start-cluster/"
},
"type": "module_command"
},
{
"attributes": {
"arg_max": 2,
"arg_min": 2,
"description": "Stop ColumnStore cluster. Does not wait for completion.",
"method": "POST",
"parameters": [
{
"description": "Monitor name",
"required": true,
"type": "MONITOR"
},
{
"description": "Timeout",
"required": true,
"type": "STRING"
}
]
},
"id": "async-cs-stop-cluster",
"links": {
"self": "http://localhost:8989/v1/modules/mariadbmon/async-cs-stop-cluster/"
},
"type": "module_command"
},
{
"attributes": {
"arg_max": 1,
"arg_min": 1,
"description": "Schedule primary failover. Does not wait for completion.",
"method": "POST",
"parameters": [
{
"description": "Monitor name",
"required": true,
"type": "MONITOR"
}
]
},
"id": "async-failover",
"links": {
"self": "http://localhost:8989/v1/modules/mariadbmon/async-failover/"
},
"type": "module_command"
},
{
"attributes": {
"arg_max": 1,
"arg_min": 1,
"description": "Schedule primary failover if no detected trx loss. Does not wait for completion.",
"method": "POST",
"parameters": [
{
"description": "Monitor name",
"required": true,
"type": "MONITOR"
}
]
},
"id": "async-failover-safe",
"links": {
"self": "http://localhost:8989/v1/modules/mariadbmon/async-failover-safe/"
},
"type": "module_command"
},
{
"attributes": {
"arg_max": 4,
"arg_min": 2,
"description": "Rebuild a server with Mariabackup. Does not wait for completion.",
"method": "POST",
"parameters": [
{
"description": "Monitor name",
"required": true,
"type": "MONITOR"
},
{
"description": "Target server",
"required": true,
"type": "SERVER"
},
{
"description": "Source server (optional)",
"required": false,
"type": "[SERVER]"
},
{
"description": "Target data directory (optional)",
"required": false,
"type": "[STRING]"
}
]
},
"id": "async-rebuild-server",
"links": {
"self": "http://localhost:8989/v1/modules/mariadbmon/async-rebuild-server/"
},
"type": "module_command"
},
{
"attributes": {
"arg_max": 2,
"arg_min": 2,
"description": "Rejoin server to a cluster. Does not wait for completion.",
"method": "POST",
"parameters": [
{
"description": "Monitor name",
"required": true,
"type": "MONITOR"
},
{
"description": "Joining server",
"required": true,
"type": "SERVER"
}
]
},
"id": "async-rejoin",
"links": {
"self": "http://localhost:8989/v1/modules/mariadbmon/async-rejoin/"
},
"type": "module_command"
},
{
"attributes": {
"arg_max": 1,
"arg_min": 1,
"description": "Release any held server locks for 1 minute. Does not wait for completion.",
"method": "POST",
"parameters": [
{
"description": "Monitor name",
"required": true,
"type": "MONITOR"
}
]
},
"id": "async-release-locks",
"links": {
"self": "http://localhost:8989/v1/modules/mariadbmon/async-release-locks/"
},
"type": "module_command"
},
{
"attributes": {
"arg_max": 2,
"arg_min": 1,
"description": "Delete replica connections, delete binary logs and set up replication (dangerous). Does not wait for completion.",
"method": "POST",
"parameters": [
{
"description": "Monitor name",
"required": true,
"type": "MONITOR"
},
{
"description": "Primary server (optional)",
"required": false,
"type": "[SERVER]"
}
]
},
"id": "async-reset-replication",
"links": {
"self": "http://localhost:8989/v1/modules/mariadbmon/async-reset-replication/"
},
"type": "module_command"
},
{
"attributes": {
"arg_max": 4,
"arg_min": 3,
"description": "Restore a server from a backup. Does not wait for completion.",
"method": "POST",
"parameters": [
{
"description": "Monitor name",
"required": true,
"type": "MONITOR"
},
{
"description": "Target server",
"required": true,
"type": "SERVER"
},
{
"description": "Backup name",
"required": true,
"type": "STRING"
},
{
"description": "Target data directory (optional)",
"required": false,
"type": "[STRING]"
}
]
},
"id": "async-restore-from-backup",
"links": {
"self": "http://localhost:8989/v1/modules/mariadbmon/async-restore-from-backup/"
},
"type": "module_command"
},
{
"attributes": {
"arg_max": 3,
"arg_min": 1,
"description": "Schedule primary switchover. Does not wait for completion.",
"method": "POST",
"parameters": [
{
"description": "Monitor name",
"required": true,
"type": "MONITOR"
},
{
"description": "New primary (optional)",
"required": false,
"type": "[SERVER]"
},
{
"description": "Current primary (optional)",
"required": false,
"type": "[SERVER]"
}
]
},
"id": "async-switchover",
"links": {
"self": "http://localhost:8989/v1/modules/mariadbmon/async-switchover/"
},
"type": "module_command"
},
{
"attributes": {
"arg_max": 1,
"arg_min": 1,
"description": "Cancel the last scheduled command.",
"method": "POST",
"parameters": [
{
"description": "Monitor name",
"required": true,
"type": "MONITOR"
}
]
},
"id": "cancel-cmd",
"links": {
"self": "http://localhost:8989/v1/modules/mariadbmon/cancel-cmd/"
},
"type": "module_command"
},
{
"attributes": {
"arg_max": 1,
"arg_min": 1,
"description": "Get ColumnStore cluster status.",
"method": "POST",
"parameters": [
{
"description": "Monitor name",
"required": true,
"type": "MONITOR"
}
]
},
"id": "cs-get-status",
"links": {
"self": "http://localhost:8989/v1/modules/mariadbmon/cs-get-status/"
},
"type": "module_command"
},
{
"attributes": {
"arg_max": 1,
"arg_min": 1,
"description": "Perform primary failover",
"method": "POST",
"parameters": [
{
"description": "Monitor name",
"required": true,
"type": "MONITOR"
}
]
},
"id": "failover",
"links": {
"self": "http://localhost:8989/v1/modules/mariadbmon/failover/"
},
"type": "module_command"
},
{
"attributes": {
"arg_max": 1,
"arg_min": 1,
"description": "Perform primary failover if no detected trx loss",
"method": "POST",
"parameters": [
{
"description": "Monitor name",
"required": true,
"type": "MONITOR"
}
]
},
"id": "failover-safe",
"links": {
"self": "http://localhost:8989/v1/modules/mariadbmon/failover-safe/"
},
"type": "module_command"
},
{
"attributes": {
"arg_max": 1,
"arg_min": 1,
"description": "Fetch result of the last scheduled command.",
"method": "GET",
"parameters": [
{
"description": "Monitor name",
"required": true,
"type": "MONITOR"
}
]
},
"id": "fetch-cmd-result",
"links": {
"self": "http://localhost:8989/v1/modules/mariadbmon/fetch-cmd-result/"
},
"type": "module_command"
},
{
"attributes": {
"arg_max": 2,
"arg_min": 2,
"description": "Rejoin server to a cluster",
"method": "POST",
"parameters": [
{
"description": "Monitor name",
"required": true,
"type": "MONITOR"
},
{
"description": "Joining server",
"required": true,
"type": "SERVER"
}
]
},
"id": "rejoin",
"links": {
"self": "http://localhost:8989/v1/modules/mariadbmon/rejoin/"
},
"type": "module_command"
},
{
"attributes": {
"arg_max": 1,
"arg_min": 1,
"description": "Release any held server locks for 1 minute.",
"method": "POST",
"parameters": [
{
"description": "Monitor name",
"required": true,
"type": "MONITOR"
}
]
},
"id": "release-locks",
"links": {
"self": "http://localhost:8989/v1/modules/mariadbmon/release-locks/"
},
"type": "module_command"
},
{
"attributes": {
"arg_max": 2,
"arg_min": 1,
"description": "Delete replica connections, delete binary logs and set up replication (dangerous)",
"method": "POST",
"parameters": [
{
"description": "Monitor name",
"required": true,
"type": "MONITOR"
},
{
"description": "Primary server (optional)",
"required": false,
"type": "[SERVER]"
}
]
},
"id": "reset-replication",
"links": {
"self": "http://localhost:8989/v1/modules/mariadbmon/reset-replication/"
},
"type": "module_command"
},
{
"attributes": {
"arg_max": 3,
"arg_min": 1,
"description": "Switch primary server with replica",
"method": "POST",
"parameters": [
{
"description": "Monitor name",
"required": true,
"type": "MONITOR"
},
{
"description": "New primary (optional)",
"required": false,
"type": "[SERVER]"
},
{
"description": "Current primary (optional)",
"required": false,
"type": "[SERVER]"
}
]
},
"id": "switchover",
"links": {
"self": "http://localhost:8989/v1/modules/mariadbmon/switchover/"
},
"type": "module_command"
},
{
"attributes": {
"arg_max": 3,
"arg_min": 1,
"description": "Switch primary server with replica. Ignores most errors.",
"method": "POST",
"parameters": [
{
"description": "Monitor name",
"required": true,
"type": "MONITOR"
},
{
"description": "New primary (optional)",
"required": false,
"type": "[SERVER]"
},
{
"description": "Current primary (optional)",
"required": false,
"type": "[SERVER]"
}
]
},
"id": "switchover-force",
"links": {
"self": "http://localhost:8989/v1/modules/mariadbmon/switchover-force/"
},
"type": "module_command"
},
{
"attributes": {
"description": "Create a backup with Mariabackup. Does not wait for completion.",
"method": "POST",
"parameters": [
{
"description": "Monitor name",
"name": "monitor",
"required": true,
"type": "MONITOR"
},
{
"description": "Source server",
"name": "source",
"required": true,
"type": "SERVER"
},
{
"description": "Backup name",
"name": "bu_name",
"required": true,
"type": "STRING"
},
{
"description": "Dry-run, only test preconditions",
"name": "dry_run",
"required": false,
"type": "[BOOLEAN]"
}
]
},
"id": "async-create-backup",
"links": {
"self": "http://localhost:8989/v1/modules/mariadbmon/async-create-backup/"
},
"type": "module_command"
},
{
"attributes": {
"description": "Rebuild a server with Mariabackup. Does not wait for completion.",
"method": "POST",
"parameters": [
{
"description": "Monitor name",
"name": "monitor",
"required": true,
"type": "MONITOR"
},
{
"description": "Target server",
"name": "target",
"required": true,
"type": "SERVER"
},
{
"description": "Source server",
"name": "source",
"required": false,
"type": "[SERVER]"
},
{
"description": "Target data directory",
"name": "datadir",
"required": false,
"type": "[STRING]"
},
{
"description": "Dry-run, only test preconditions",
"name": "dry_run",
"required": false,
"type": "[BOOLEAN]"
}
]
},
"id": "async-rebuild-server",
"links": {
"self": "http://localhost:8989/v1/modules/mariadbmon/async-rebuild-server/"
},
"type": "module_command"
},
{
"attributes": {
"description": "Restore a server from a backup. Does not wait for completion.",
"method": "POST",
"parameters": [
{
"description": "Monitor name",
"name": "monitor",
"required": true,
"type": "MONITOR"
},
{
"description": "Target server",
"name": "target",
"required": true,
"type": "SERVER"
},
{
"description": "Backup name",
"name": "bu_name",
"required": true,
"type": "STRING"
},
{
"description": "Target data directory",
"name": "datadir",
"required": false,
"type": "[STRING]"
},
{
"description": "Dry-run, only test preconditions",
"name": "dry_run",
"required": false,
"type": "[BOOLEAN]"
}
]
},
"id": "async-restore-from-backup",
"links": {
"self": "http://localhost:8989/v1/modules/mariadbmon/async-restore-from-backup/"
},
"type": "module_command"
},
{
"attributes": {
"description": "Bootstrap an empty monitor.",
"method": "POST",
"parameters": [
{
"description": "Monitor name",
"name": "monitor",
"required": true,
"type": "MONITOR"
},
{
"description": "Run command asynchronously",
"name": "async",
"required": false,
"type": "[BOOLEAN]"
},
{
"description": "server template",
"name": "template",
"required": false,
"type": "[SERVER]"
},
{
"description": "starting address",
"name": "address",
"required": true,
"type": "STRING"
},
{
"description": "starting port",
"name": "port",
"required": false,
"type": "[STRING]"
}
]
},
"id": "bootstrap",
"links": {
"self": "http://localhost:8989/v1/modules/mariadbmon/bootstrap/"
},
"type": "module_command"
},
{
"attributes": {
"description": "Discover replica servers and add them to MaxScale.",
"method": "POST",
"parameters": [
{
"description": "Monitor name",
"name": "monitor",
"required": true,
"type": "MONITOR"
},
{
"description": "Run command asynchronously",
"name": "async",
"required": false,
"type": "[BOOLEAN]"
},
{
"description": "Remove shut down or non-replicating servers",
"name": "remove",
"required": false,
"type": "[BOOLEAN]"
}
]
},
"id": "discover-replicas",
"links": {
"self": "http://localhost:8989/v1/modules/mariadbmon/discover-replicas/"
},
"type": "module_command"
},
{
"attributes": {
"description": "Fetch json status information on most recent asynchronous manual command.",
"method": "GET",
"parameters": [
{
"description": "Monitor name",
"name": "monitor",
"required": true,
"type": "MONITOR"
}
]
},
"id": "fetch-cmd-status",
"links": {
"self": "http://localhost:8989/v1/modules/mariadbmon/fetch-cmd-status/"
},
"type": "module_command"
},
{
"attributes": {
"description": "List available backups.",
"method": "GET",
"parameters": [
{
"description": "Monitor name",
"name": "monitor",
"required": true,
"type": "MONITOR"
}
]
},
"id": "list-backups",
"links": {
"self": "http://localhost:8989/v1/modules/mariadbmon/list-backups/"
},
"type": "module_command"
},
{
"attributes": {
"description": "Alter server replication.",
"method": "POST",
"parameters": [
{
"description": "Monitor name",
"name": "monitor",
"required": true,
"type": "MONITOR"
},
{
"description": "Replica to redirect",
"name": "replica",
"required": true,
"type": "SERVER"
},
{
"description": "New primary for the replica",
"name": "new_primary",
"required": true,
"type": "SERVER"
},
{
"description": "Replica connection name",
"name": "conn_name",
"required": false,
"type": "[STRING]"
},
{
"description": "Run command asynchronously",
"name": "async",
"required": false,
"type": "[BOOLEAN]"
}
]
},
"id": "redirect",
"links": {
"self": "http://localhost:8989/v1/modules/mariadbmon/redirect/"
},
"type": "module_command"
},
{
"attributes": {
"description": "Scan replication topology.",
"method": "GET",
"parameters": [
{
"description": "Monitor name",
"name": "monitor",
"required": true,
"type": "MONITOR"
},
{
"description": "Run command asynchronously",
"name": "async",
"required": false,
"type": "[BOOLEAN]"
}
]
},
"id": "scan-topology",
"links": {
"self": "http://localhost:8989/v1/modules/mariadbmon/scan-topology/"
},
"type": "module_command"
},
{
"attributes": {
"description": "Switch primary server with replica.",
"method": "POST",
"parameters": [
{
"description": "Monitor name",
"name": "monitor",
"required": true,
"type": "MONITOR"
},
{
"description": "New primary",
"name": "new_primary",
"required": false,
"type": "[SERVER]"
},
{
"description": "Current primary",
"name": "old_primary",
"required": false,
"type": "[SERVER]"
},
{
"description": "Run command asynchronously",
"name": "async",
"required": false,
"type": "[BOOLEAN]"
},
{
"description": "Ignore most errors",
"name": "force",
"required": false,
"type": "[BOOLEAN]"
},
{
"description": "Set old primary to maintenance instead of redirecting it.",
"name": "old_primary_maint",
"required": false,
"type": "[BOOLEAN]"
}
]
},
"id": "switchover",
"links": {
"self": "http://localhost:8989/v1/modules/mariadbmon/switchover/"
},
"type": "module_command"
}
],
"description": "A MariaDB Primary/Replica replication monitor",
"groups": [],
"module_type": "Monitor",
"parameters": [
{
"default_value": true,
"description": "Assume that hostnames are unique",
"mandatory": false,
"modifiable": true,
"name": "assume_unique_hostnames",
"type": "bool"
},
{
"default_value": false,
"description": "Switchover back to old primary server when it returns to the cluster",
"mandatory": false,
"modifiable": true,
"name": "auto_failback_switchover",
"type": "bool"
},
{
"default_value": "false",
"description": "Enable automatic primary server failover",
"enum_values": [
"false",
"off",
"no",
"0",
"true",
"on",
"yes",
"1",
"safe"
],
"mandatory": false,
"modifiable": true,
"name": "auto_failover",
"type": "enum"
},
{
"default_value": false,
"description": "Enable automatic server rejoin",
"mandatory": false,
"modifiable": true,
"name": "auto_rejoin",
"type": "bool"
},
{
"description": "Address of backup storage.",
"mandatory": false,
"modifiable": true,
"name": "backup_storage_address",
"type": "string"
},
{
"description": "Backup storage directory path.",
"mandatory": false,
"modifiable": true,
"name": "backup_storage_path",
"type": "string"
},
{
"default_value": "none",
"description": "Cooperative monitoring type",
"enum_values": [
"none",
"majority_of_running",
"majority_of_all"
],
"mandatory": false,
"modifiable": true,
"name": "cooperative_monitoring_locks",
"type": "enum"
},
{
"description": "The API key used in communication with the ColumnStore admin daemon.",
"mandatory": false,
"modifiable": true,
"name": "cs_admin_api_key",
"type": "string"
},
{
"default_value": "/cmapi/0.4.0",
"description": "The base path to be used when accessing the ColumnStore administrative daemon. If, for instance, a daemon URL is https://localhost:8640/cmapi/0.4.0/node/start then the admin_base_path is \"/cmapi/0.4.0\".",
"mandatory": false,
"modifiable": true,
"name": "cs_admin_base_path",
"type": "string"
},
{
"default_value": 8640,
"description": "Port of the ColumnStore administrative daemon.",
"mandatory": false,
"modifiable": true,
"name": "cs_admin_port",
"type": "count"
},
{
"description": "Path to SQL file that is executed during node demotion",
"mandatory": false,
"modifiable": true,
"name": "demotion_sql_file",
"type": "path"
},
{
"default_value": false,
"description": "Enable read_only on all non-primary servers",
"mandatory": false,
"modifiable": true,
"name": "enforce_read_only_servers",
"type": "bool"
},
{
"default_value": false,
"description": "Enable read_only on all slave servers",
"mandatory": false,
"modifiable": true,
"name": "enforce_read_only_slaves",
"type": "bool"
},
{
"default_value": false,
"description": "Enforce a simple topology",
"mandatory": false,
"modifiable": true,
"name": "enforce_simple_topology",
"type": "bool"
},
{
"default_value": false,
"description": "Disable read_only on the current master server",
"mandatory": false,
"modifiable": true,
"name": "enforce_writable_master",
"type": "bool"
},
{
"default_value": 5,
"description": "Number of failures to tolerate before failover occurs",
"mandatory": false,
"modifiable": true,
"name": "failcount",
"type": "count"
},
{
"default_value": "90000ms",
"description": "Timeout for failover",
"mandatory": false,
"modifiable": true,
"name": "failover_timeout",
"type": "duration",
"unit": "s"
},
{
"default_value": true,
"description": "Manage server-side events",
"mandatory": false,
"modifiable": true,
"name": "handle_events",
"type": "bool"
},
{
"default_value": true,
"description": "Put the server into maintenance mode when it runs out of disk space",
"mandatory": false,
"modifiable": true,
"name": "maintenance_on_low_disk_space",
"type": "bool"
},
{
"default_value": 1,
"description": "Mariabackup thread count.",
"mandatory": false,
"modifiable": true,
"name": "mariabackup_parallel",
"type": "int"
},
{
"default_value": "1G",
"description": "Mariabackup buffer pool size.",
"mandatory": false,
"modifiable": true,
"name": "mariabackup_use_memory",
"type": "string"
},
{
"default_value": "primary_monitor_master,disk_space_ok",
"description": "Conditions that the master servers must meet",
"enum_values": [
"none",
"connecting_slave",
"connected_slave",
"running_slave",
"primary_monitor_master",
"disk_space_ok"
],
"mandatory": false,
"modifiable": true,
"name": "master_conditions",
"type": "enum_mask"
},
{
"default_value": "10000ms",
"description": "Master failure timeout",
"mandatory": false,
"modifiable": true,
"name": "master_failure_timeout",
"type": "duration",
"unit": "s"
},
{
"description": "Path to SQL file that is executed during node promotion",
"mandatory": false,
"modifiable": true,
"name": "promotion_sql_file",
"type": "path"
},
{
"default_value": 4444,
"description": "Listen port used for transferring server backup.",
"mandatory": false,
"modifiable": true,
"name": "rebuild_port",
"type": "count"
},
{
"description": "Custom CHANGE MASTER TO options",
"mandatory": false,
"modifiable": true,
"name": "replication_custom_options",
"type": "string"
},
{
"default_value": false,
"description": "Enable SSL when configuring replication",
"mandatory": false,
"modifiable": true,
"name": "replication_master_ssl",
"type": "bool"
},
{
"description": "Password for the user that is used for replication",
"mandatory": false,
"modifiable": true,
"name": "replication_password",
"type": "password"
},
{
"description": "User used for replication",
"mandatory": false,
"modifiable": true,
"name": "replication_user",
"type": "string"
},
{
"default_value": -1,
"description": "Replication lag limit at which the script is run",
"mandatory": false,
"modifiable": true,
"name": "script_max_replication_lag",
"type": "int"
},
{
"description": "List of servers that are omitted from cooperative monitoring locks.",
"mandatory": false,
"modifiable": true,
"name": "servers_no_cooperative_monitoring_locks",
"type": "serverlist"
},
{
"description": "List of servers that are never promoted",
"mandatory": false,
"modifiable": true,
"name": "servers_no_promotion",
"type": "serverlist"
},
{
"default_value": "",
"description": "Conditions that the slave servers must meet",
"enum_values": [
"none",
"linked_master",
"running_master",
"writable_master",
"primary_monitor_master",
"disk_space_ok"
],
"mandatory": false,
"modifiable": true,
"name": "slave_conditions",
"type": "enum_mask"
},
{
"default_value": true,
"description": "Is SSH host key check enabled.",
"mandatory": false,
"modifiable": true,
"name": "ssh_check_host_key",
"type": "bool"
},
{
"description": "SSH keyfile. Used for running remote commands on servers.",
"mandatory": false,
"modifiable": true,
"name": "ssh_keyfile",
"type": "path"
},
{
"default_value": 22,
"description": "SSH port. Used for running remote commands on servers.",
"mandatory": false,
"modifiable": true,
"name": "ssh_port",
"type": "count"
},
{
"default_value": "10000ms",
"description": "SSH connection and command timeout",
"mandatory": false,
"modifiable": true,
"name": "ssh_timeout",
"type": "duration",
"unit": "s"
},
{
"description": "SSH username. Used for running remote commands on servers.",
"mandatory": false,
"modifiable": true,
"name": "ssh_user",
"type": "string"
},
{
"default_value": false,
"description": "Perform a switchover when a server runs out of disk space",
"mandatory": false,
"modifiable": true,
"name": "switchover_on_low_disk_space",
"type": "bool"
},
{
"default_value": "90000ms",
"description": "Timeout for switchover",
"mandatory": false,
"modifiable": true,
"name": "switchover_timeout",
"type": "duration",
"unit": "s"
},
{
"default_value": true,
"description": "Verify master failure",
"mandatory": false,
"modifiable": true,
"name": "verify_master_failure",
"type": "bool"
},
{
"default_value": "log",
"description": "Action to take on write test failure.",
"enum_values": [
"log",
"failover"
],
"mandatory": false,
"modifiable": true,
"name": "write_test_fail_action",
"type": "enum"
},
{
"default_value": "0ms",
"description": "Primary server write test interval.",
"mandatory": false,
"modifiable": true,
"name": "write_test_interval",
"type": "duration",
"unit": "s"
},
{
"default_value": "mxs.maxscale_write_test",
"description": "Primary server write test table.",
"mandatory": false,
"modifiable": true,
"name": "write_test_table",
"type": "string"
},
{
"default_value": 1,
"description": "Number of connection attempts to make to a server",
"mandatory": false,
"modifiable": true,
"name": "backend_connect_attempts",
"type": "count"
},
{
"deprecated": true,
"description": "Alias for 'backend_timeout'",
"mandatory": false,
"modifiable": true,
"name": "backend_connect_timeout",
"type": "duration"
},
{
"default_value": "3000ms",
"deprecated": true,
"description": "Read timeout for monitor connections",
"mandatory": false,
"modifiable": true,
"name": "backend_read_timeout",
"type": "duration",
"unit": "s"
},
{
"default_value": "3000ms",
"description": "Monitor backend connection timeout",
"mandatory": false,
"modifiable": true,
"name": "backend_timeout",
"type": "duration",
"unit": "s"
},
{
"default_value": "3000ms",
"deprecated": true,
"description": "Write timeout for monitor connections",
"mandatory": false,
"modifiable": true,
"name": "backend_write_timeout",
"type": "duration",
"unit": "s"
},
{
"default_value": "0ms",
"description": "How often the disk space is checked",
"mandatory": false,
"modifiable": true,
"name": "disk_space_check_interval",
"type": "duration",
"unit": "ms"
},
{
"description": "Disk space threshold",
"mandatory": false,
"modifiable": true,
"name": "disk_space_threshold",
"type": "string"
},
{
"default_value": "all,master_down,master_up,slave_down,slave_up,server_down,server_up,synced_down,synced_up,donor_down,donor_up,lost_master,lost_slave,lost_synced,lost_donor,new_master,new_slave,new_synced,new_donor",
"description": "Events that cause the script to be called",
"enum_values": [
"all",
"master_down",
"master_up",
"slave_down",
"slave_up",
"server_down",
"server_up",
"synced_down",
"synced_up",
"donor_down",
"donor_up",
"lost_master",
"lost_slave",
"lost_synced",
"lost_donor",
"new_master",
"new_slave",
"new_synced",
"new_donor"
],
"mandatory": false,
"modifiable": true,
"name": "events",
"type": "enum_mask"
},
{
"default_value": "28800000ms",
"description": "The time the on-disk cached server states are valid for",
"mandatory": false,
"modifiable": true,
"name": "journal_max_age",
"type": "duration",
"unit": "s"
},
{
"default_value": "2000ms",
"description": "How often the servers are monitored",
"mandatory": false,
"modifiable": true,
"name": "monitor_interval",
"type": "duration",
"unit": "ms"
},
{
"description": "Password for the user used to monitor the servers",
"mandatory": true,
"modifiable": true,
"name": "password",
"type": "password"
},
{
"description": "SQL queries run when a server gains Master-status",
"mandatory": false,
"modifiable": true,
"name": "primary_state_sql",
"type": "string"
},
{
"description": "SQL queries run when a server gains Slave-status",
"mandatory": false,
"modifiable": true,
"name": "replica_state_sql",
"type": "string"
},
{
"description": "Role used for monitoring the servers",
"mandatory": false,
"modifiable": true,
"name": "role",
"type": "string"
},
{
"description": "Script to run whenever an event occurs",
"mandatory": false,
"modifiable": true,
"name": "script",
"type": "string"
},
{
"default_value": "90000ms",
"description": "Timeout for the script",
"mandatory": false,
"modifiable": true,
"name": "script_timeout",
"type": "duration",
"unit": "s"
},
{
"description": "List of servers to use",
"mandatory": false,
"modifiable": true,
"name": "servers",
"type": "serverlist"
},
{
"description": "Username used to monitor the servers",
"mandatory": true,
"modifiable": true,
"name": "user",
"type": "string"
}
]
},
"id": "mariadbmon",
"links": {
"self": "http://localhost:8989/v1/modules/mariadbmon/"
},
"type": "modules"
},
{
"attributes": {
"api": "protocol",
"commands": [],
"description": "The client to MaxScale MySQL protocol implementation",
"groups": [],
"module_type": "Protocol",
"parameters": [
{
"default_value": true,
"description": "Allow use of the replication protocol through this listener",
"mandatory": false,
"modifiable": false,
"name": "allow_replication",
"type": "bool"
},
{
"default_value": "zlib,zstd",
"description": "Supported compression algorithms",
"enum_values": [
"none",
"zlib",
"zstd"
],
"mandatory": false,
"modifiable": true,
"name": "compression",
"type": "enum_mask"
},
{
"default_value": 50,
"description": "Upper limit for payloads that are sent uncompressed",
"mandatory": false,
"modifiable": true,
"name": "compression_threshold",
"type": "size"
},
{
"default_value": "::",
"description": "Listener address",
"mandatory": false,
"modifiable": false,
"name": "address",
"type": "string"
},
{
"description": "Listener authenticator",
"mandatory": false,
"modifiable": false,
"name": "authenticator",
"type": "string"
},
{
"description": "Authenticator options",
"mandatory": false,
"modifiable": false,
"name": "authenticator_options",
"type": "string"
},
{
"description": "Path to connection initialization SQL",
"mandatory": false,
"modifiable": true,
"name": "connection_init_sql_file",
"type": "path"
},
{
"default_value": [
"character_set_client=auto",
"character_set_connection=auto",
"character_set_results=auto",
"max_allowed_packet=auto",
"system_time_zone=auto",
"time_zone=auto",
"tx_isolation=auto",
"maxscale=auto"
],
"description": "Metadata that's sent to all connecting clients.",
"mandatory": false,
"modifiable": true,
"name": "connection_metadata",
"type": "stringlist"
},
{
"default_value": 0,
"description": "Listener port",
"mandatory": false,
"modifiable": false,
"name": "port",
"type": "count"
},
{
"default_value": "MariaDBProtocol",
"description": "Listener protocol to use",
"mandatory": false,
"modifiable": false,
"name": "protocol",
"type": "module"
},
{
"description": "Allowed (sub)networks for proxy protocol connections. Should be a comma-separated list of IPv4 or IPv6 addresses.",
"mandatory": false,
"modifiable": true,
"name": "proxy_protocol_networks",
"type": "string"
},
{
"description": "Redirect clients to this URL",
"mandatory": false,
"modifiable": true,
"name": "redirect_url",
"type": "string"
},
{
"description": "Service to which the listener connects to",
"mandatory": true,
"modifiable": false,
"name": "service",
"type": "service"
},
{
"description": "Listener UNIX socket",
"mandatory": false,
"modifiable": false,
"name": "socket",
"type": "string"
},
{
"default_value": "default",
"description": "SQL parsing mode",
"enum_values": [
"default",
"oracle"
],
"mandatory": false,
"modifiable": true,
"name": "sql_mode",
"type": "enum"
},
{
"default_value": false,
"description": "Enable TLS for server",
"mandatory": false,
"modifiable": true,
"name": "ssl",
"type": "bool"
},
{
"description": "TLS certificate authority",
"mandatory": false,
"modifiable": true,
"name": "ssl_ca",
"type": "path"
},
{
"deprecated": true,
"description": "Alias for 'ssl_ca'",
"mandatory": false,
"modifiable": true,
"name": "ssl_ca_cert",
"type": "path"
},
{
"description": "TLS public certificate",
"mandatory": false,
"modifiable": true,
"name": "ssl_cert",
"type": "path"
},
{
"default_value": 9,
"description": "TLS certificate verification depth",
"mandatory": false,
"modifiable": true,
"name": "ssl_cert_verify_depth",
"type": "count"
},
{
"description": "TLS cipher list",
"mandatory": false,
"modifiable": true,
"name": "ssl_cipher",
"type": "string"
},
{
"description": "TLS certificate revocation list",
"mandatory": false,
"modifiable": true,
"name": "ssl_crl",
"type": "string"
},
{
"description": "TLS private key",
"mandatory": false,
"modifiable": true,
"name": "ssl_key",
"type": "path"
},
{
"default_value": "",
"description": "Passphrase for TLS key",
"mandatory": false,
"modifiable": true,
"name": "ssl_passphrase",
"type": "sslpassphrase"
},
{
"default_value": false,
"description": "Verify TLS peer certificate",
"mandatory": false,
"modifiable": true,
"name": "ssl_verify_peer_certificate",
"type": "bool"
},
{
"default_value": false,
"description": "Verify TLS peer host",
"mandatory": false,
"modifiable": true,
"name": "ssl_verify_peer_host",
"type": "bool"
},
{
"default_value": "MAX",
"description": "Enabled TLS protocol versions",
"enum_values": [
"MAX",
"TLSv10",
"TLSv11",
"TLSv12",
"TLSv13",
"TLSv1.0",
"TLSv1.1",
"TLSv1.2",
"TLSv1.3"
],
"mandatory": false,
"modifiable": true,
"name": "ssl_version",
"type": "enum_mask"
},
{
"description": "Path to user and group mapping file",
"mandatory": false,
"modifiable": true,
"name": "user_mapping_file",
"type": "path"
}
]
},
"id": "MariaDBProtocol",
"links": {
"self": "http://localhost:8989/v1/modules/MariaDBProtocol/"
},
"type": "modules"
},
{
"attributes": {
"api": "parser",
"commands": [],
"description": "MariaDB SQL parser using sqlite3.",
"groups": [],
"module_type": "Parser",
"parameters": []
},
"id": "pp_sqlite",
"links": {
"self": "http://localhost:8989/v1/modules/pp_sqlite/"
},
"type": "modules"
},
{
"attributes": {
"api": "filter",
"commands": [
{
"attributes": {
"arg_max": 3,
"arg_min": 1,
"description": "Show unified log file as a JSON array",
"method": "GET",
"parameters": [
{
"description": "Filter to read logs from",
"required": true,
"type": "FILTER"
},
{
"description": "Start reading from this line",
"required": false,
"type": "[STRING]"
},
{
"description": "Stop reading at this line (exclusive)",
"required": false,
"type": "[STRING]"
}
]
},
"id": "log",
"links": {
"self": "http://localhost:8989/v1/modules/qlafilter/log/"
},
"type": "module_command"
}
],
"description": "A simple query logging filter",
"groups": [],
"module_type": "Filter",
"parameters": [
{
"default_value": true,
"description": "Append new entries to log files instead of overwriting them",
"mandatory": false,
"modifiable": true,
"name": "append",
"type": "bool"
},
{
"default_value": "ms",
"description": "Duration in milliseconds (ms) or microseconds (us)",
"enum_values": [
"ms",
"milliseconds",
"us",
"microseconds"
],
"mandatory": false,
"modifiable": true,
"name": "duration_unit",
"type": "enum"
},
{
"description": "Exclude queries matching this pattern from the log",
"mandatory": false,
"modifiable": true,
"name": "exclude",
"type": "regex"
},
{
"description": "The basename of the output file",
"mandatory": true,
"modifiable": true,
"name": "filebase",
"type": "string"
},
{
"default_value": false,
"description": "Flush log files after every write",
"mandatory": false,
"modifiable": true,
"name": "flush",
"type": "bool"
},
{
"default_value": "date,user,query",
"description": "Type of data to log in the log files",
"enum_values": [
"service",
"session",
"date",
"user",
"query",
"reply_time",
"total_reply_time",
"default_db",
"num_rows",
"reply_size",
"transaction",
"transaction_time",
"num_warnings",
"error_msg",
"server",
"command"
],
"mandatory": false,
"modifiable": true,
"name": "log_data",
"type": "enum_mask"
},
{
"default_value": "session",
"description": "The type of log file to use",
"enum_values": [
"session",
"unified",
"stdout"
],
"mandatory": false,
"modifiable": true,
"name": "log_type",
"type": "enum_mask"
},
{
"description": "Only log queries matching this pattern",
"mandatory": false,
"modifiable": true,
"name": "match",
"type": "regex"
},
{
"default_value": " ",
"description": "Value used to replace newlines",
"mandatory": false,
"modifiable": true,
"name": "newline_replacement",
"type": "string"
},
{
"default_value": "",
"description": "Regular expression options",
"enum_values": [
"case",
"ignorecase",
"extended"
],
"mandatory": false,
"modifiable": true,
"name": "options",
"type": "enum_mask"
},
{
"default_value": ",",
"description": "Defines the separator between elements of a log entry",
"mandatory": false,
"modifiable": true,
"name": "separator",
"type": "string"
},
{
"description": "Log queries only from this network address",
"mandatory": false,
"modifiable": true,
"name": "source",
"type": "string"
},
{
"description": "Exclude queries from hosts that match this pattern",
"mandatory": false,
"modifiable": true,
"name": "source_exclude",
"type": "regex"
},
{
"description": "Log queries only from hosts that match this pattern",
"mandatory": false,
"modifiable": true,
"name": "source_match",
"type": "regex"
},
{
"default_value": false,
"description": "Write queries in canonical form",
"mandatory": false,
"modifiable": true,
"name": "use_canonical_form",
"type": "bool"
},
{
"description": "Log queries only from this user",
"mandatory": false,
"modifiable": true,
"name": "user",
"type": "string"
},
{
"description": "Exclude queries from users that match this pattern",
"mandatory": false,
"modifiable": true,
"name": "user_exclude",
"type": "regex"
},
{
"description": "Log queries only from users that match this pattern",
"mandatory": false,
"modifiable": true,
"name": "user_match",
"type": "regex"
}
]
},
"id": "qlafilter",
"links": {
"self": "http://localhost:8989/v1/modules/qlafilter/"
},
"type": "modules"
},
{
"attributes": {
"api": "router",
"commands": [],
"description": "A connection based router to load balance based on connections",
"groups": [],
"module_type": "Router",
"parameters": [
{
"default_value": true,
"description": "Use master for reads",
"mandatory": false,
"modifiable": true,
"name": "master_accept_reads",
"type": "bool"
},
{
"default_value": "0ms",
"description": "Maximum acceptable replication lag",
"mandatory": false,
"modifiable": true,
"name": "max_replication_lag",
"type": "duration",
"unit": "s"
},
{
"default_value": "running",
"description": "A comma separated list of server roles",
"enum_values": [
"master",
"slave",
"running",
"synced"
],
"mandatory": false,
"modifiable": true,
"name": "router_options",
"type": "enum_mask"
},
{
"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": "s"
},
{
"deprecated": true,
"description": "Alias for 'wait_timeout'",
"mandatory": false,
"modifiable": true,
"name": "connection_timeout",
"type": "duration"
},
{
"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": false,
"description": "Ping connections unconditionally",
"mandatory": false,
"modifiable": true,
"name": "force_connection_keepalive",
"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": "s"
},
{
"default_value": "0ms",
"description": "Network write timeout",
"mandatory": false,
"modifiable": true,
"name": "net_write_timeout",
"type": "duration",
"unit": "s"
},
{
"description": "Password for the user used to retrieve database users",
"mandatory": true,
"modifiable": true,
"name": "password",
"type": "password"
},
{
"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"
},
{
"description": "Role used for retrieving database users",
"mandatory": false,
"modifiable": true,
"name": "role",
"type": "string"
},
{
"default_value": false,
"deprecated": true,
"description": "Track session state using server responses",
"mandatory": false,
"modifiable": true,
"name": "session_track_trx_state",
"type": "bool"
},
{
"default_value": true,
"deprecated": 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"
},
{
"default_value": "28800000ms",
"description": "Connection idle timeout",
"mandatory": false,
"modifiable": true,
"name": "wait_timeout",
"type": "duration",
"unit": "s"
}
]
},
"id": "readconnroute",
"links": {
"self": "http://localhost:8989/v1/modules/readconnroute/"
},
"type": "modules"
},
{
"attributes": {
"api": "router",
"commands": [
{
"attributes": {
"arg_max": 1,
"arg_min": 1,
"description": "Reset global GTID state in readwritesplit.",
"method": "POST",
"parameters": [
{
"description": "Readwritesplit service",
"required": true,
"type": "SERVICE"
}
]
},
"id": "reset-gtid",
"links": {
"self": "http://localhost:8989/v1/modules/readwritesplit/reset-gtid/"
},
"type": "module_command"
}
],
"description": "A Read/Write splitting router for enhancement read scalability",
"groups": [
{
"description": "Settings that control how queries are routed",
"members": [
"use_sql_variables_in",
"slave_selection_criteria",
"max_replication_lag",
"max_slave_replication_lag",
"strict_multi_stmt",
"strict_sp_calls",
"strict_tmp_tables",
"master_accept_reads",
"max_slave_connections",
"slave_connections",
"lazy_connect"
],
"name": "Routing"
},
{
"description": "Settings that control how node failures are handled",
"members": [
"master_failure_mode",
"retry_failed_reads",
"master_reconnection",
"delayed_retry",
"delayed_retry_timeout"
],
"name": "Error Handling"
},
{
"description": "Settings that control the causal reads feature",
"members": [
"causal_reads",
"causal_reads_timeout"
],
"name": "Causal Reads"
},
{
"description": "Settings that control the transaction replay feature",
"members": [
"transaction_replay",
"transaction_replay_max_size",
"transaction_replay_timeout",
"transaction_replay_attempts",
"transaction_replay_retry_on_deadlock",
"transaction_replay_retry_on_mismatch",
"transaction_replay_safe_commit",
"transaction_replay_checksum"
],
"name": "Transaction Replay"
},
{
"description": "Settings that control the synchronous transaction feature",
"members": [
"sync_transaction",
"sync_transaction_count",
"sync_transaction_timeout",
"sync_transaction_max_lag"
],
"name": "Synchronous Transaction"
}
],
"module_type": "Router",
"parameters": [
{
"default_value": "none",
"description": "Causal reads mode",
"enum_values": [
"none",
"local",
"global",
"fast_global",
"fast",
"universal",
"fast_universal",
"false",
"off",
"0",
"true",
"on",
"1"
],
"group": "Causal Reads",
"mandatory": false,
"modifiable": true,
"name": "causal_reads",
"type": "enum"
},
{
"default_value": "10000ms",
"description": "Timeout for the slave synchronization",
"group": "Causal Reads",
"mandatory": false,
"modifiable": true,
"name": "causal_reads_timeout",
"type": "duration",
"unit": "s"
},
{
"default_value": false,
"description": "Retry failed writes outside of transactions",
"group": "Error Handling",
"mandatory": false,
"modifiable": true,
"name": "delayed_retry",
"type": "bool"
},
{
"default_value": "10000ms",
"description": "Timeout for delayed_retry",
"group": "Error Handling",
"mandatory": false,
"modifiable": true,
"name": "delayed_retry_timeout",
"type": "duration",
"unit": "s"
},
{
"default_value": false,
"description": "Create connections only when needed",
"group": "Routing",
"mandatory": false,
"modifiable": true,
"name": "lazy_connect",
"type": "bool"
},
{
"default_value": false,
"description": "Use master for reads",
"group": "Routing",
"mandatory": false,
"modifiable": true,
"name": "master_accept_reads",
"type": "bool"
},
{
"default_value": "fail_on_write",
"description": "Master failure mode behavior",
"enum_values": [
"fail_instantly",
"fail_on_write",
"error_on_write"
],
"group": "Error Handling",
"mandatory": false,
"modifiable": true,
"name": "master_failure_mode",
"type": "enum"
},
{
"default_value": true,
"description": "Reconnect to master",
"group": "Error Handling",
"mandatory": false,
"modifiable": true,
"name": "master_reconnection",
"type": "bool"
},
{
"default_value": "0ms",
"description": "Maximum replication lag",
"group": "Routing",
"mandatory": false,
"modifiable": true,
"name": "max_replication_lag",
"type": "duration",
"unit": "s"
},
{
"default_value": 255,
"description": "Maximum number of slave connections",
"group": "Routing",
"mandatory": false,
"modifiable": true,
"name": "max_slave_connections",
"type": "count"
},
{
"deprecated": true,
"description": "Alias for 'max_replication_lag'",
"group": "Routing",
"mandatory": false,
"modifiable": true,
"name": "max_slave_replication_lag",
"type": "duration"
},
{
"default_value": true,
"description": "Automatically retry failed reads outside of transactions",
"group": "Error Handling",
"mandatory": false,
"modifiable": true,
"name": "retry_failed_reads",
"type": "bool"
},
{
"default_value": 255,
"description": "Starting number of slave connections",
"group": "Routing",
"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",
"LEAST_GLOBAL_CONNECTIONS",
"LEAST_ROUTER_CONNECTIONS",
"LEAST_BEHIND_MASTER",
"LEAST_CURRENT_OPERATIONS",
"ADAPTIVE_ROUTING"
],
"group": "Routing",
"mandatory": false,
"modifiable": true,
"name": "slave_selection_criteria",
"type": "enum"
},
{
"default_value": false,
"description": "Lock connection to master after multi-statement query",
"group": "Routing",
"mandatory": false,
"modifiable": true,
"name": "strict_multi_stmt",
"type": "bool"
},
{
"default_value": false,
"description": "Lock connection to master after a stored procedure is executed",
"group": "Routing",
"mandatory": false,
"modifiable": true,
"name": "strict_sp_calls",
"type": "bool"
},
{
"default_value": true,
"description": "Prevent reconnections if temporary tables exist",
"group": "Routing",
"mandatory": false,
"modifiable": true,
"name": "strict_tmp_tables",
"type": "bool"
},
{
"default_value": "none",
"description": "Synchronize transactions with one or more replicas.",
"enum_values": [
"none",
"soft",
"hard"
],
"group": "Synchronous Transaction",
"mandatory": false,
"modifiable": true,
"name": "sync_transaction",
"type": "enum"
},
{
"default_value": 1,
"description": "Number of acknowledgements required for each transaction.",
"group": "Synchronous Transaction",
"mandatory": false,
"modifiable": true,
"name": "sync_transaction_count",
"type": "count"
},
{
"default_value": "0ms",
"description": "Maximum allowed replication lag before synchronization starts.",
"group": "Synchronous Transaction",
"mandatory": false,
"modifiable": true,
"name": "sync_transaction_max_lag",
"type": "duration",
"unit": "ms"
},
{
"default_value": "10000ms",
"description": "Timeout for transaction synchronization.",
"group": "Synchronous Transaction",
"mandatory": false,
"modifiable": true,
"name": "sync_transaction_timeout",
"type": "duration",
"unit": "ms"
},
{
"default_value": false,
"description": "Retry failed transactions",
"group": "Transaction Replay",
"mandatory": false,
"modifiable": true,
"name": "transaction_replay",
"type": "bool"
},
{
"default_value": 5,
"description": "Maximum number of times to retry a transaction",
"group": "Transaction Replay",
"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"
],
"group": "Transaction Replay",
"mandatory": false,
"modifiable": true,
"name": "transaction_replay_checksum",
"type": "enum"
},
{
"default_value": 1048576,
"description": "Maximum size of transaction to retry",
"group": "Transaction Replay",
"mandatory": false,
"modifiable": true,
"name": "transaction_replay_max_size",
"type": "size"
},
{
"default_value": false,
"description": "Retry transaction on deadlock",
"group": "Transaction Replay",
"mandatory": false,
"modifiable": true,
"name": "transaction_replay_retry_on_deadlock",
"type": "bool"
},
{
"default_value": false,
"description": "Retry transaction on checksum mismatch",
"group": "Transaction Replay",
"mandatory": false,
"modifiable": true,
"name": "transaction_replay_retry_on_mismatch",
"type": "bool"
},
{
"default_value": true,
"description": "Prevent replaying of about-to-commit transaction",
"group": "Transaction Replay",
"mandatory": false,
"modifiable": true,
"name": "transaction_replay_safe_commit",
"type": "bool"
},
{
"default_value": "30000ms",
"description": "Timeout for transaction replay",
"group": "Transaction Replay",
"mandatory": false,
"modifiable": true,
"name": "transaction_replay_timeout",
"type": "duration",
"unit": "s"
},
{
"default_value": "all",
"description": "Whether to route SQL variable modifications to all servers or only to the master",
"enum_values": [
"all",
"master"
],
"group": "Routing",
"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": "s"
},
{
"deprecated": true,
"description": "Alias for 'wait_timeout'",
"mandatory": false,
"modifiable": true,
"name": "connection_timeout",
"type": "duration"
},
{
"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": false,
"description": "Ping connections unconditionally",
"mandatory": false,
"modifiable": true,
"name": "force_connection_keepalive",
"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": "s"
},
{
"default_value": "0ms",
"description": "Network write timeout",
"mandatory": false,
"modifiable": true,
"name": "net_write_timeout",
"type": "duration",
"unit": "s"
},
{
"description": "Password for the user used to retrieve database users",
"mandatory": true,
"modifiable": true,
"name": "password",
"type": "password"
},
{
"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"
},
{
"description": "Role used for retrieving database users",
"mandatory": false,
"modifiable": true,
"name": "role",
"type": "string"
},
{
"default_value": false,
"deprecated": true,
"description": "Track session state using server responses",
"mandatory": false,
"modifiable": true,
"name": "session_track_trx_state",
"type": "bool"
},
{
"default_value": true,
"deprecated": 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"
},
{
"default_value": "28800000ms",
"description": "Connection idle timeout",
"mandatory": false,
"modifiable": true,
"name": "wait_timeout",
"type": "duration",
"unit": "s"
}
]
},
"id": "readwritesplit",
"links": {
"self": "http://localhost:8989/v1/modules/readwritesplit/"
},
"type": "modules"
}
],
"links": {
"self": "http://localhost:8989/v1/maxscale/modules/"
}
}GET /v1/maxscale/modules/:module/:commandPOST /v1/maxscale/modules/:module/:commandPOST /v1/maxscale/modules/mariadbmon/reset-replication?MariaDB-Monitor&server1{
"links": {
"self": "http://localhost:8989/v1/maxscale/modules/mariadbmon/reset-replication"
},
"meta": [ // Output of module command (module dependent)
{
"name": "value"
}
]
}GET /v1/maxscale/query_classifier/classify?sql=<statement>GET /v1/maxscale/query_classifier/classify?sql=SELECT+1{
"data": {
"attributes": {
"canonical": "SELECT ?",
"fields": [],
"functions": [],
"operation": "sql::OP_SELECT",
"parse_result": "Parser::Result::PARSED",
"type_mask": "sql::TYPE_READ"
},
"id": "classify",
"type": "classify"
},
"links": {
"self": "http://localhost:8989/v1/maxscale/query_classifier/classify/"
}
}POST /v1/maxscale/query_classifier/dump{
"path": "/tmp",
"format": "pretty_json"
}{
data: {
attributes: { path: '/tmp/qc_dump-2024-09-23_11-50-02.jsonl' },
id: 'qc_dump'
},
links: {
self: 'http://127.0.0.1:8989/v1/maxscale/query_classifier/cache/dump/'
}
}