Adds a ColumnStore node.

See CMAPI for detail on REST API endpoint, required headers, and other available actions.

Description

Upon successful node PUT call CMAPI configures MariaDB Enterprise ColumnStore to add the new node and a dbroot for that node.

Call made via HTTPS PUT, with authentication via shared secret using the x-api-key header.

JSON data required for this call:

Examples

Executing cURL Manually

CMAPI calls can be made from the command-line using cURL.

Replace the CMAPI_API_KEY and sample data in the following example:

In this example, jq produces human-readable output from the returned JSON response:

Shuts down ColumnStore on all nodes

See for detail on REST API endpoint, required headers, and other available actions.

Description

Upon successful shutdown call CMAPI connects to each MariaDB Enterprise ColumnStore node and performs shut down.

Call made via HTTPS PUT, with authentication via shared secret using the x-api-key header.

Sets all ColumnStore nodes to read-only or read-write.

See CMAPI for detail on REST API endpoint, required headers, and other available actions.

Description

Upon successful mode-set call CMAPI re-configures MariaDB Enterprise ColumnStore to the designated mode, either read-only or read/write operation.

Call made via HTTPS PUT, with authentication via shared secret using the x-api-key header.

JSON data required for this call:

Bash aliases mcsReadOnly and mcsReadWrite are available starting with Enterprise ColumnStore 5.5.2.

Examples

Executing cURL Manually

CMAPI calls can be made from the command-line using cURL.

Replace the CMAPI_API_KEY and sample data in the following example:

In this example, jq produces human-readable output from the returned JSON response.

Executing the Bash Aliases

Starting with Enterprise ColumnStore 5.5.2, if your bash shell is configured to source the columnstoreAlias shell script, this command can be executed using the mcsReadOnly and mcsReadWrite aliases. The alias executes curl and jq, so both programs must be installed on the system.

The 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.

To set the deployment's mode to read-only:

To set the deployment's mode to read-write:

These aliases use jq produces human-readable output from the returned JSON response.

Removes a ColumnStore node.

See for detail on REST API endpoint, required headers, and other available actions.

Description

Upon successful node DELETE call CMAPI configures MariaDB Enterprise ColumnStore to remove the specified node.

Call made via HTTPS DELETE, with authentication via shared secret using the x-api-key header.

Starts ColumnStore on all nodes.

See for detail on REST API endpoint, required headers, and other available actions.

Description

Upon successful start call CMAPI connects to each MariaDB Enterprise ColumnStore node and performs start-up.

Call made via HTTPS PUT, with authentication via shared secret using the x-api-key header.

Checks the status of ColumnStore.

See CMAPI for detail on REST API endpoint, required headers, and other available actions.

Description

Upon successful status call CMAPI returns JSON payload containing detailed information on MariaDB Enterprise Cluster status.

Call made via HTTPS GET, with authentication via shared secret using the x-api-key header.

Bash alias mcsStatus is available starting with Enterprise ColumnStore 5.5.2.

Examples

Executing cURL Manually

CMAPI calls can be made from the command-line using cURL.

Replace the CMAPI_API_KEY and sample data in the following example:

In this example, jq produces human-readable output from the returned JSON response:

Executing the Bash Alias

Starting with Enterprise ColumnStore 5.5.2, if your bash shell is configured to source the columnstoreAlias shell script, this command can be executed using the mcsStatus alias. The alias executes curl and jq, so both programs must be installed on the system.

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

In this example, jq produces human-readable output from the returned JSON response.

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

Method and required data vary by CMAPI endpoint path.

Required Headers

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:

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 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:

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:

Bash Aliases

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 command. The aliases automatically retrieve the API key by reading /etc/columnstore/cmapi_server.conf.

Available aliases:

CMAPI Service Management

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

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:

Configure Failover

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

• The default value of the auto_failover option is True.

• The auto_failover option should be set to False when is used.

Logging

Starting with Enterprise ColumnStore 5.5.2, the 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:

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.

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.

Body

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