CMAPI

CMAPI is a REST API for administering MariaDB Enterprise ColumnStore in multi-node topologies.

Reference material is available for MariaDB Enterprise ColumnStore.

MariaDB Enterprise ColumnStore is included with MariaDB Enterprise Server.

Clients

CMAPI is a REST API, so it should be compatible with most standard REST clients.

CMAPI examples throughout the documentation use curl as the REST client. The examples also pipe the JSON output to jq for enhanced readability.

Endpoint

The endpoint for CMAPI contains the hostname and port for the primary node running Enterprise ColumnStore, /cmapi/, the CMAPI API version (0.4.0), and a action-specific endpoint path.

Example: https://mcs1:8640/cmapi/0.4.0/cluster/node

Endpoint Paths

Endpoint Path	Method	Action
mode-set	PUT	Sets all ColumnStore nodes to read-only or read-write
node	DELETE	Removes a ColumnStore node
node	PUT	Adds a ColumnStore node
shutdown	PUT	Shuts down ColumnStore on all nodes
start	PUT	Starts ColumnStore on all nodes
status	GET	Checks the status of ColumnStore

Method and required data vary by CMAPI endpoint path.

Required Headers

Header	Description
Content-Type	Set to application/json
x-api-key	Set to the API key configured for CMAPI. Calls using the incorrect keys are rejected.

Authentication

Authentication is performed via an API key, which performs the role of a shared secret. The API key is passed to the API using the x-api-key header.

The API key is stored in /etc/columnstore/cmapi_server.conf.

Generate an API Key

The API key is a shared secret that can be used to add nodes to multi-node Enterprise ColumnStore. The API key can be any string, but it is recommended to use a long, random string. The API key should be stored securely and kept confidential.

For example, to create a random 256-bit API key using openssl rand:

openssl rand -hex 32
93816fa66cc2d8c224e62275bd4f248234dd4947b68d4af2b29671dd7d5532dd

Set the API Key

To set the API key for the first time, provide the desired API key when you add the first node using the node PUT command. Since Enterprise ColumnStore does not yet have an API key, CMAPI will write the first API key it receives to /etc/columnstore/cmapi_server.conf.

For example, if the primary server's host name is mcs1 and its IP address is 192.0.2.1, the following command will add the primary server to Enterprise ColumnStore and write the provided API key to the node's CMAPI configuration file:

curl -k -s -X PUT https://mcs1:8640/cmapi/0.4.0/cluster/node \
   --header 'Content-Type:application/json' \
   --header 'x-api-key:93816fa66cc2d8c224e62275bd4f248234dd4947b68d4af2b29671dd7d5532dd' \
   --data '{"timeout":120, "node": "192.0.2.1"}' \
   | jq .

Change the API Key

To change the API key in multi-node Enterprise ColumnStore, change it in the CMAPI configuration file on each node located at /etc/columnstore/cmapi_server.conf. The CMAPI server must be restarted on each node for the changes to be applied.

Restart the CMAPI server by running the following command on each node:

sudo systemctl restart mariadb-columnstore-cmapi

Bash Aliases

Bash aliases are available starting with Enterprise ColumnStore 5.5.2.

These aliases are available if your bash shell is configured to source the columnstoreAlias shell script.

These aliases execute curl and jq, so both programs must be installed on the system.

These aliases automatically retrieve the IP address for the primary node using the mcsGetConfig command. The aliases automatically retrieve the API key by reading /etc/columnstore/cmapi_server.conf.

Available aliases:

Alias	Endpoint	Action
mcsReadOnly	mode-set	Sets all ColumnStore nodes to read-only
mcsReadWrite	mode-set	Sets all ColumnStore nodes to read/write
mcsShutdown	shutdown	Shuts down ColumnStore on all nodes
mcsStart	start	Starts ColumnStore on all nodes
mcsStatus	status	Checks the status of ColumnStore

CMAPI Service Management

The systemctl command is used to start and stop the CMAPI service.

Operation	Command
Status	systemctl status mariadb-columnstore-cmapi
Start	systemctl start mariadb-columnstore-cmapi
Stop	systemctl stop mariadb-columnstore-cmapi
Restart	systemctl restart mariadb-columnstore-cmapi
Enable startup	systemctl enable mariadb-columnstore-cmapi
Disable startup	systemctl disable mariadb-columnstore-cmapi
View systemd journal	journalctl -u mariadb-columnstore-cmapi

Configuration

The CMAPI configuration file is located at /etc/columnstore/cmapi_server.conf.

To change the configuration:

• Modify the configuration file on each node

• Restart the CMAPI server on each node:

  sudo systemctl restart mariadb-columnstore-cmapi

Configure Failover

Starting with CMAPI 6.4.1, the auto_failover option can be set to True or False in the [application] section:

[application]
auto_failover = False

• The default value of the auto_failover option is True.

• The auto_failover option should be set to False when non-shared local storage is used.

Logging

Starting with Enterprise ColumnStore 5.5.2, the CMAPI logs can be found at /var/log/mariadb/columnstore/cmapi_server.log.

In previous versions, CMAPI's log messages can be viewed in the systemd journal:

sudo journalctl -u mariadb-columnstore-cmapi

CMAPI Responses

CMAPI responds to client requests with standard HTTP response messages.

Status Line

The first part of the standard HTTP response message is the status line. To determine if your request was successful, check the status code and the reason phrase from the status line.

Status Code	Reason Phrase	Outcome
200	OK	Successful
200 < x < 300	Varies	Possibly successful
300 <= x < 400	Varies	Request redirected
400 <= x < 500	Varies	Client-side error Check endpoint, API key, and JSON data
500 <= x < 600	Varies	Server-side error Contact support

Please consult the HTTP standard to see the full list of status codes and their descriptions.

Headers

The second part of the standard HTTP response message is the HTTP headers. To determine what kind of message body is in the response message, check the Content-Type header field.

Outcome	Content-Type
Success	application/json
Failure	Undefined Depends on specific failure

Body

The final part of the standard HTTP response message is the body.

Outcome	Body
Success	JSON Data
Failure	Undefined Depends on specific failure

_{This page is: Copyright © 2025 MariaDB. All rights reserved.}