Deploy MariaDB Xpand with Docker

Overview

MariaDB Corporation provides Docker images for MariaDB Xpand in Docker Hub.

This page provides instructions on how to deploy MariaDB Xpand in a single-node configuration using Docker.

Docker provides multiple benefits:

  • Docker is an open platform for developing, shipping, and running applications that allows you to separate your applications from your infrastructure.

  • Docker images are portable. A Docker image can be deployed in a Docker container on any system using the Docker platform, regardless of the host operating system.

  • Docker containers are isolated from the host operating system and from other Docker containers.

The Docker images for MariaDB Xpand are a convenient way to get started and familiarized with Xpand. The Docker images can be used as sandboxes for development and learning. The Docker images are not appropriate for performance or production use.

MariaDB Xpand is a distributed SQL database that provides strong consistency, high availability, and scale-out performance. MariaDB Xpand also provides a high level of compatibility with MariaDB Enterprise Server. For information about the features provided by MariaDB Xpand, see "MariaDB Xpand".

MariaDB Xpand can also be deployed as a multi-node cluster in private data centers. Multi-node Xpand clusters provide elasticity, high availability, fault tolerance, and write scaling. For information about how to deploy MariaDB Xpand in a multi-node cluster, see "Deploy Xpand Topology".

MariaDB Xpand can also be deployed on expert-maintained cloud infrastructure in MariaDB SkySQL. For information about how to deploy MariaDB Xpand in SkySQL, see the "Quickstart".

Use Cases

MariaDB Xpand can be deployed with Docker to support use cases that require software to be rapidly deployed on existing infrastructure, such as:

  • Continuously create and destroy automated testing environments as part of a continuous integration (CI) pipeline

  • Create a small test environment on a local workstation

  • Create multiple isolated test environments on the same host

Compatibility

The following products and versions can be deployed using the Docker images in Docker Hub:

  • MariaDB Xpand 5.3

  • MariaDB Xpand 6.0

  • MariaDB Xpand 6.1

Supported Architectures

The following architectures are currently supported:

  • x86_64

System Requirements

Resource

Default Configuration

--mini Configuration

Storage

21 GB

6 GB

Memory

6 GB

2 GB

CPU cores

4

2

Deploy Xpand in a Docker Container

To deploy MariaDB Xpand in a Docker container, follow the instructions below.

Step 1: Pull Docker Image

Pull the Xpand Docker image by executing docker pull:

$ docker pull mariadb/xpand-single:latest

latest: Pulling from mariadb/xpand-single
2d473b07cdd5: Pull complete
df77aa090591: Pull complete
7a3b718e57ab: Pull complete
6734e34f56f8: Pull complete
7ab5855141ec: Pull complete
b1fe1e607a84: Pull complete
Digest: sha256:b88c3aee07d14452546e13fcaa20f1a4ca5ef6d227b1bf32454c31c4882b648a
Status: Downloaded newer image for mariadb/xpand-single:latest
docker.io/mariadb/xpand-single:latest

The mariadb/xpand-single repository in Docker Hub contains images for different MariaDB Xpand releases. Specific releases can be chosen by specifying the release's tag. For additional information about the tags available, see "MariaDB Xpand Docker Images: Supported Tags".

Confirm the Docker image has been pulled by executing docker images:

$ docker images \
   --filter=reference='mariadb/xpand-single'

REPOSITORY             TAG       IMAGE ID       CREATED       SIZE
mariadb/xpand-single   latest    d7e0145da0e2   3 weeks ago   544MB

Step 2: Create a Container

Create a container using the pulled Docker image by executing docker run:

$ docker run --detach \
   --name mariadb-xpand \
   --publish '3306:3306/tcp' \
   mariadb/xpand-single:latest \
   --mini

6688f74f244e505fbe90e93dc5d28d20ddfc9d9fdb39ce71d6bff0660aea662d

  • Configure TCP port bindings for the container by setting the --publish or --publish-all command-line options.

  • Configure the Docker container to be have a small footprint by specifying the --mini command-line option.

  • Configure MariaDB Xpand by setting command-line options.

For troubleshooting information, see "Troubleshooting".

Confirm the container is running by executing docker ps:

$ docker ps \
   --all \
   --filter ancestor='mariadb/xpand-single:latest'

CONTAINER ID   IMAGE                         COMMAND                  CREATED         STATUS         PORTS                                                 NAMES
6688f74f244e   mariadb/xpand-single:latest   "/usr/local/bin/dumb…"   7 seconds ago   Up 6 seconds   3581/tcp, 0.0.0.0:3306->3306/tcp, :::3306->3306/tcp   mariadb-xpand

Step 3: Connect to Container

Connect to a Docker container with the mariadb client located on the Docker container using docker exec:

$ docker exec --interactive --tty \
   mariadb-xpand \
   mariadb \
   --user=xpand \
   --password

Confirm the container is using the correct version of MariaDB Xpand by calling the VERSION() function:

SELECT VERSION();

+------------------+
| VERSION()        |
+------------------+
| 5.0.45-Xpand-6.1 |
+------------------+

Exit the container using exit:

exit

Bye

Step 4: Stop Container

Stop a Docker container using docker stop:

$ docker stop mariadb-xpand

mariadb-xpand

Confirm the container is stopped by executing docker ps:

$ docker ps \
   --all \
   --filter ancestor='mariadb/xpand-single:latest'

CONTAINER ID   IMAGE                         COMMAND                  CREATED         STATUS                            PORTS     NAMES
6688f74f244e   mariadb/xpand-single:latest   "/usr/local/bin/dumb…"   2 minutes ago   Exited (143) About a minute ago             mariadb-xpand

Step 5: Remove Container

Remove a Docker container using docker rm:

$ docker rm mariadb-xpand

mariadb-xpand

Confirm the container is removed by executing docker ps:

$ docker ps \
   --all \
   --filter ancestor='mariadb/xpand-single:latest'

CONTAINER ID   IMAGE     COMMAND   CREATED   STATUS    PORTS     NAMES

Troubleshooting

View Container Logs

To view the logs in the Docker container, execute docker logs:

$ docker logs mariadb-xpand

The Xpand logs in the Docker container can also be accessed in the /data/xpand/log/ directory on the container.

To access the logs, open up a shell in the container using docker exec:

$ docker exec --interactive --tty \
   mariadb-xpand \
   bash

In the shell, navigate to the directory and view the contents:

$ cd /data/xpand/log/
$ ls -l

total 16
lrwxrwxrwx 1 xpand xpand    25 Sep 20 18:43 debug.log -> debug.log.20220920.184308
-rw-r--r-- 1 xpand xpand  1489 Sep 20 18:43 debug.log.20220920.184308
lrwxrwxrwx 1 xpand xpand    25 Sep 20 18:43 query.log -> query.log.20220920.184308
-rw-r--r-- 1 xpand xpand 10421 Sep 20 22:30 query.log.20220920.184308
lrwxrwxrwx 1 xpand xpand    24 Sep 20 18:43 user.log -> user.log.20220920.184308
-rw-r--r-- 1 xpand xpand     0 Sep 20 18:43 user.log.20220920.184308

The logs can be opened with a text editor on the container.

Storage Space

If the system does not have sufficient storage, the container fails to start, but Docker does not raise an error.

Confirm that the system failed due to lack of storage using docker logs:

$ sudo docker logs mariadb-xpand

Did not find existing database storage volume, initializing a new node.
Available disk space of 4 GB is insufficient to run Xpand.
Please try again with at least 7 GB of free storage space.

Address Already in Use

If the port used by the container is already in use, the container fails to start, and Docker raises an error:

$ docker run --detach \
   --name mariadb-xpand \
   --publish '3306:3306/tcp' \
   mariadb/xpand-single:latest \
   --mini

6688f74f244e505fbe90e93dc5d28d20ddfc9d9fdb39ce71d6bff0660aea662d
docker: Error response from daemon: driver failed programming external connectivity on endpoint mariadb-xpand (6dba95bff66ea17461293aa4f53e31fd64baf6fea66bbfa828d82552e92acbcd): Error starting userland proxy: listen tcp4 0.0.0.0:3306: bind: address already in use.

Confirm that an application is listening on the port by executing netstat:

netstat --numeric --numeric-ports --listening --program \
   grep "3306"

tcp        0      0 127.0.0.1:3306          0.0.0.0:*               LISTEN      -

Unsupported Architectures

Please see the current list of Supported Architectures. Other architectures are unsupported.

The behavior of this docker image on unsupported architectures is not known.

On some systems, such as Apple M1, it may be possible to run the image under virtualization.

Attempting to run the image directly on a Apple M1 running macOS, Docker raises an error:

WARNING: The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8) and no specific platform was requested

On Apple M1, this warning is followed by an infinite loop which can be exited by pressing Ctrl+c. The following error message is output during this loop:

/run_xpand.sh: line 228: [: -ne: unary operator expected
FATAL core/init.c:81 core_done: core failed: Illegal seek: core/INIT_SW_HASH failed (couldn't read /opt/clustrix/bin/clxnode)

Support

The Xpand docker image is provided as a convenience. No support is provided for the docker image. Users can get help or report issues at the following links: