Docker Images for MariaDB Xpand 23.09

Overview

MariaDB Corporation provides Docker images for MariaDB Xpand.

This page contains reference material for the MariaDB Xpand Docker images.

The reference material on this page applies to MariaDB Xpand 23.09.

DETAILS

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

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

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.

For instructions on how to deploy MariaDB Xpand with Docker, see "Deploy MariaDB Xpand with Docker".

For examples that show common Docker operations, see "EXAMPLES".

For examples that show how to use the Docker images for another version of MariaDB Xpand, see Docker Images by Xpand Version.

Other details are listed in the sections below.

Repositories

MariaDB Corporation provides a single repository on Docker Hub that contains the images for MariaDB Xpand:

Tags

The mariadb/xpand-single repository on Docker Hub contains images for different MariaDB Xpand releases using specific tags:

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

Command-Line Options

Flags

Description

  • -m

  • --memory

Amount of memory to pre-allocate to Xpand, in MB. For memory allocations over 4000 MB, the memlock ulimit must be greater than the allocation quantity by at least 128 MB (or -1, for unlimited.)

  • -d

  • --data

Amount of disk space to pre-allocate to Xpand, in GB. Total disk usage will be around 500 MB higher than this value. This value only has an effect on the first run with persistent data.

  • -c

  • --cpus

Number of CPUs for Xpand to use.

  • -u

  • --user

Database user to create at start

  • -p

  • --passwd

Database user password. The default is a blank password. The DB_PASSWD environment variable is also checked.

  • -P

  • --port

Database SQL port for TCP connection (note, docker's -p argument should match)

  • -q

  • --querylog

Also send query.log output to console rather than /data/xpand/log/query.log

  • --mini

Alias for minimum viable config: -c 2 -m 2048 -d 5

EXAMPLES

Backup and Restore Data

To backup the data on a Docker container with the mariadb-dump utility located on the Docker container, use docker exec:

$ docker exec --interactive --tty \
   mariadb-xpand \
   mariadb-dump \
   --user=xpand \
   --password \
   --single-transaction \
   --all-databases \
   > xpand-data.sql

To restore the backup with the mariadb client located on the Docker container, use docker exec:

$ docker exec --interactive \
   mariadb-xpand \
   mysql \
   --user=xpand \
   --password \
   < xpand-data.sql

Connect with Container Client

To connect to a Docker container with the mariadb client located on the Docker container, use docker exec:

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

To confirm the client is connected to the Docker container and the container is using the correct version of MariaDB Xpand, call the VERSION() function:

SELECT VERSION();

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

To exit the container, use exit:

exit

Bye

The example above shows how to connect to a Docker container using MariaDB Client on the container, but you can also connect using MariaDB Client on the host using TCP/IP. You can inspect the Docker container to find the container's IP address and port bindings.

Connect with Host Client

To connect to a Docker container with the mariadb client located on the host node, execute the client and specify the host's IP address or loopback address:

$ mysql --host=127.0.0.1 \
   --user=xpand \
   --password

To confirm the client is connected to the Docker container and the container is using the correct version of MariaDB Xpand, call the VERSION() function:

SELECT VERSION();

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

To exit the container, use exit:

exit

Bye

Create a Container with Docker Bridge Networking

By default, Docker containers use Docker bridge networking. To make connecting to the container easier, Docker can use port bindings to publish the container's TCP ports to the host.

To create a Docker container using Docker bridge networking, execute docker run:

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

6688f74f244e505fbe90e93dc5d28d20ddfc9d9fdb39ce71d6bff0660aea662d

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

To confirm the Docker container is running, execute 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

Create a Container with Non-persistent Data

To create a one-off Docker container with non-persistent data, execute docker run and specify the --rm option and --ulimit memlock=-1:

$ docker run --detach \
   --name mariadb-xpand \
   --publish '3306:3306/tcp' \
   --rm \
   --ulimit memlock=-1 \
   mariadb/xpand-single:latest

6688f74f244e505fbe90e93dc5d28d20ddfc9d9fdb39ce71d6bff0660aea662d

To confirm the Docker container is running, execute 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

Create a Container with Named Docker Volume

To create a Docker container with persistent data on a named Docker volume, execute docker run and specify the --volume option and --ulimit memlock=-1:

$ docker run --detach \
   --name mariadb-xpand \
   --publish '3306:3306/tcp' \
   --volume xpand:/data/xpand \
   --ulimit memlock=-1 \
   mariadb/xpand-single:latest

3082ab69e565be21c6157bb5a3d8c849ec03a2c51576778ac417a8a3aa9e7537

  • Configure the named Docker volume for the container by setting the volume name and path inside the container using the --volume command-line option.

To confirm the Docker container is running, execute 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

To list named Docker volumes, execute docker volume ls:

$ docker volume ls \
   --filter name='xpand'

DRIVER    VOLUME NAME
local     xpand

To inspect a named Docker volume, execute docker volume inspect:

$ docker volume inspect xpand

[
    {
        "CreatedAt": "2022-09-22T10:18:26-07:00",
        "Driver": "local",
        "Labels": null,
        "Mountpoint": "/var/lib/docker/volumes/xpand/_data",
        "Name": "xpand",
        "Options": null,
        "Scope": "local"
    }
]

To remove a named Docker volume after the corresponding container has been stopped and removed, execute docker volume rm:

$ docker volume rm xpand

xpand

Create a Container with Host Volume

To create a Docker container with persistent data on a host volume, execute docker run and specify the --volume option and --ulimit memlock=-1:

$ docker run --detach \
   --name mariadb-xpand \
   --publish '3306:3306/tcp' \
   --volume /var/lib/xpand:/data/xpand \
   --ulimit memlock=-1 \
   mariadb/xpand-single:latest

3082ab69e565be21c6157bb5a3d8c849ec03a2c51576778ac417a8a3aa9e7537

  • Configure the host volume for the container by setting the path on the host and the path inside the container using the --volume command-line option.

To confirm the Docker container is running, execute 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

To list the files in the host volume, use ls to list the directory on the host:

$ ls -l /var/lib/xpand/

total 5767492
-rw-r--r-- 1 docker_user docker_user          2 Sep 22 10:31 clxnode.pid
-rw-r--r-- 1 docker_user docker_user          5 Sep 22 10:31 control_port
-rw-r--r-- 1 root  root                      29 Sep 22 10:31 created_at
-rw------- 1 docker_user docker_user 5368709120 Sep 22 10:31 device1
-rw------- 1 docker_user docker_user  536875008 Sep 22 10:32 device1-redo
-rw-r--r-- 1 docker_user docker_user          5 Sep 22 10:31 healthmon_port
drwxr-xr-x 2 docker_user docker_user       4096 Sep 22 10:31 log
-rw-r--r-- 1 docker_user docker_user          5 Sep 22 10:31 mysql_port
srwxrwxrwt 1 docker_user docker_user          0 Sep 22 10:31 mysql.sock
-rw-r--r-- 1 docker_user docker_user         21 Sep 22 10:31 pnid
-rw------- 1 docker_user docker_user      32768 Sep 22 10:31 sector_size_test
drwx------ 2 docker_user docker_user       4096 Sep 22 10:32 super
drwx------ 2 docker_user docker_user       4096 Sep 22 10:32 uber

To remove a host volume after the corresponding container has been stopped and removed, use rm to remove the directory on the host:

rm -fr /var/lib/xpand

Inspect Container

A Docker contained can be inspected to find out internal details about the container, such as the following details:

  • IP addresses

  • MAC addresses

  • Port bindings

To inspect all internal details about a Docker container, execute docker inspect:

$ docker inspect mariadb-xpand

[
 {
     "Id": "2bb1b4125cb59f04e9bed8420787d44212534090efa55927902dbf700703a639",
     "Created": "2022-09-21T22:44:19.650798811Z",
     "Path": "/usr/local/bin/dumb-init",
     "Args": [
         "--",
         "/run_xpand.sh",
         "--mini"
     ],
     "State": {
         "Status": "running",
         "Running": true,
         "Paused": false,
         "Restarting": false,
         "OOMKilled": false,
         "Dead": false,
         "Pid": 42352,
         "ExitCode": 0,
         "Error": "",
         "StartedAt": "2022-09-21T22:44:19.97594195Z",
         "FinishedAt": "0001-01-01T00:00:00Z"
        },
        ..
    }
]

To inspect a specific internal detail about a Docker container, execute docker inspect and specify a filter using the --format option. Some examples are shown below.

To inspect the container's IP address:

$ docker inspect \
   --format='{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' \
   mariadb-xpand

172.17.0.2

Obtain a Shell in Container

To obtain a shell in the Docker container, execute the shell on the container using docker exec:

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

Pull Docker Image

To pull a Docker image with the appropriate tag, execute 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

To confirm the Docker image has been pulled, execute docker images:

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

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

Remove Container

To remove a Docker container, execute docker rm:

$ docker rm mariadb-xpand

mariadb-xpand

To confirm the container is removed, execute docker ps:

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

CONTAINER ID   IMAGE     COMMAND   CREATED   STATUS    PORTS     NAMES

Stop Container

To stop a Docker container, execute docker stop:

$ docker stop mariadb-xpand

mariadb-xpand

To confirm the container is stopped, execute 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

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.