E-book: A Practical Guide to AI and Vector Search in Relational Databases
Read Now
Download MariaDBContact Us

MaxScale MaxScale Resource

Overview

The MaxScale resource represents a MaxScale instance and it is the core on top of which the modules build upon.

Resource Operations

Get global information

GET /v1/maxscale

Retrieve global information about a MaxScale instance. This includes various file locations, configuration options and version information.

Response

Status: 200 OK

{
    "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/"
    }
}

Update MaxScale parameters

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.

Response

Parameters modified:

Status: 204 No Content

Invalid JSON body:

Status: 400 Bad Request

Get thread information

Get the information and statistics of a particular thread. The :id in the URI must map to a valid thread number between 0 and the configured value of threads.

Response

Status: 200 OK

Get information for all threads

Get the information for all threads. Returns a collection of threads resources.

Response

Status: 200 OK

Get logging information

Get information about the current state of logging, enabled log files and the location where the log files are stored.

Note: The parameters in this endpoint are a subset of the parameters in the /v1/maxscale endpoint. Because of this, the parameters in this endpoint are deprecated as of MaxScale 6.0.

Note: In MaxScale 2.5 the log_throttling and ms_timestamp parameters were incorrectly named as throttling and highprecision. In MaxScale 6, the parameter names are now correct which means the parameters declared here aren't fully backwards compatible.

Response

Status: 200 OK

Get log data

Get the contents of the MaxScale logs. This endpoint was added in MaxScale 6.

To navigate the log, use the prev link to move backwards to older log entries. The latest log entries can be read with the last link.

The entries are sorted in ascending order by the time they were logged. This means that with the default parameters, the latest logged event is the last element in the returned array.

Parameters

This endpoint supports the following parameters:

  • page[size]

    • Set number of rows of data to read. By default, 50 rows of data are read from the log.

  • page[cursor]

    • Set position from where the log data is retrieved. The default position to retrieve the log data is the end of the log.

      This value should not be modified by the user and the values returned in 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.

Response

Status: 200 OK

Get log entries

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.

Parameters

This endpoint supports the same parameters as /maxscale/logs/data.

Response

Status: 200 OK

Stream log data

Stream the contents of the MaxScale logs. This endpoint was added in MaxScale 6.

This endpoint opens a WebSocket connection and streams the contents of the log to it. Each WebSocket message will contain the JSON representation of the log message. The JSON is formatted in the same way as the values in the log array of the /v1/maxscale/logs/data endpoint:

Limitations

  • If the client writes any data to the open socket, it will be treated as an error and the stream is closed.

  • The WebSocket ping and close commands are not yet supported and will be treated as errors.

  • When maxlog is used as source of log data, any log messages logged after log rotation will not be sent if the file was moved or truncated. To fetch new events after log rotation, reopen the WebSocket connection.

Parameters

This endpoint supports the following parameters:

  • page[cursor]

    • Set position from where the log data is retrieved. The default position to retrieve the log data is the end of the log.

      To stream data from a known point, first read the data via the /v1/maxscale/logs/data endpoint and then use the id value of the newest log message (i.e. the first value in the log array) to start the stream.

  • priority

    • Include messages only from these log levels. The default is to include all messages.

      The value given should be a comma-separated list of log priorities. The priorities are alert, error, warning, notice, info and debug. Note that the debug log level is only used in debug builds of MaxScale.

Response

Upgrade started:

Status: 101 Switching Protocols

Client didn't request a WebSocket upgrade:

Status: 426 Upgrade Required

Update logging parameters

Note: The modification of logging parameters via this endpoint has deprecated in MaxScale 6.0. The parameters should be modified with the /v1/maxscale endpoint instead.

Any PATCH requests done to this endpoint will be redirected to the /v1/maxscale endpoint. Due to the 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.

Response

Parameters modified:

Status: 204 No Content

Invalid JSON body:

Status: 400 Bad Request

Flush and rotate log files

Flushes any pending messages to disk and reopens the log files. The body of the message is ignored.

Response

Status: 204 No Content

Reload TLS certificates

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.

Response

Status: 204 No Content

Get a loaded module

Retrieve information about a loaded module. The :name must be the name of a valid loaded module or either maxscale or servers.

The maxscale module will display the global configuration options (i.e. everything under the [maxscale] section) as a module.

The servers module displays the server object type and the configuration parameters it accepts as a module.

Any parameter with the modifiable value set to true can be modified at runtime using a PATCH command on the corresponding object endpoint.

Response

Status: 200 OK

Get all loaded modules

Retrieve information about all loaded modules.

This endpoint supports the load=all parameter. When defined, all modules located in the MaxScale module directory (libdir) will be loaded. This allows one to see the parameters of a module before the object is created.

Response

Status: 200 OK

Call a module command

For read-only commands:

For commands that can modify data:

Modules can expose commands that can be called via the REST API. The module resource lists all commands in the data.attributes.commands list. Each value is a command sub-resource identified by its id field and the HTTP method the command uses is defined by the attributes.method field.

The :module in the URI must be a valid name of a loaded module and :command must be a valid command identifier that is exposed by that module. All parameters to the module commands are passed as HTTP request parameters.

Here is an example POST requests to the mariadbmon module command reset-replication with two parameters, the name of the monitor instance and the server name:

Response

Command with output:

Status: 200 OK

The contents of the meta field will contain the output of the module command. This output depends on the command that is being executed. It can contain any valid JSON value.

Command with no output:

Status: 204 No Content

Classify a statement

Classify provided statement and return the result.

Response

Status: 200 OK

Dump query classifier cache

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

    • Specifies the format of the dump. Allowed values are json, pretty_json and json_lines. This is an optional field and the default is 'json'.

Here is an example request body:

Response

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

PreviousMaxScale Listener ResourceNextMaxScale Monitor Resource

Last updated

Was this helpful?