mariadb/xpand-single

Verified Publisher

By MariaDB Corporation

Updated over 1 year ago

Single node MariaDB Xpand docker image, for development and test. Not for Production Use.

Image
3

5.4K

What is MariaDB Xpand?

MariaDB Xpand is a distributed SQL database that provides strong consistency, high availability, and scale-out performance, with a high level of MariaDB compatibility.

Quick Reference

Maintained by: MariaDB Corporation

Where to get help or report issues:
MariaDB Community Slack
MariaDB Xpand Forums

This image currently supports amd64/x86-64 architecture. Apple M1, ARM, s390x, and others are not supported.

How to Use this Image

The MariaDB Xpand docker image is a convenient way to get started and familiarize with Xpand. The docker image supports deploying a single node Xpand, and is ideal as a development and learning sandbox. It is not appropriate for performance or production use. If you are ready to try a full, clustered version of Xpand, try MariaDB SkySQL or Contact us for a free download.

Supported tags

Tags: latest, 6.1, 6.0.6, 6.0.5, 5.3.22, 5.3.23, 23.09.1

Quick Reference (continued)

Default system requirements:

  • 21GiB storage
  • 6GiB free memory
  • 4 CPU cores / threads

Minimum system requirements:

  • 6GiB storage
  • 2GiB free memory
  • 2 CPU cores / threads

Start an Xpand instance

Starting an Xpand instance is simple. Here are the various options, depending on your preferred storage method and method for connecting.

One-off without persistent data:

 $ docker run --rm -p3306:3306 --ulimit memlock=-1 --name xpand mariadb/xpand-single 

When Xpand is ready, connect with:

 $ mariadb -h 127.0.0.1 -u xpand

Alternately, use the mariadb client included in the image:

 $ docker exec -it xpand mariadb -u xpand

Getting Started with Xpand

Xpand supports most standard MariaDB SQL syntax, including DDL for:

  • CREATE and ALTER TABLE
  • Stored Procedures, Triggers, Partitioned Tables, and Temporary tables.
  • Schema changes for Xpand are always online.

And DML for:

  • SELECT, DISTINCT, [LEFT | RIGHT | OUTER] JOIN, STRAIGHT_JOIN
  • UNION, HAVING, GROUP BY, LIMIT, ASC, DESC, ORDER BY, FOR UPDATE
  • Subqueries, including with IN
  • EXISTS, NOT EXISTS

You can load data from mariadb-dumps (see below), LOAD DATA INFILE.

Viewing Logs

Database logs are sent to the container stdout and will be displayed on the console, or if the -d or --detach options are specified to the docker run command, they may be viewed with docker logs xpand. The query log can be found within the container at /data/xpand/logs/query.log or may be sent to stdout along with the database log, using the -q flag when the container is launched.

Container Command line options

The following are the command line options for this docker image. These arguments must be placed after the image name on the command line.

-m, --memory: Amount of memory to pre-allocate to Xpand, in MiB. [Default: 50% of available memory, 95% of the container limit (as set by the --memory option to docker run,) or 16GiB, whichever is lower]

  • Note: For memory allocations over 4000MiB, the memlock ulimit must be greater than the allocation quantity by at least 128MiB (or -1, for unlimted.)

-d, --data: Amount of disk space to pre-allocate to Xpand, in GiB. [Default: 20GiB or 90% of available disk space, whichever is lower.]

  • Note: Total disk usage will be around 500MiB higher than this value.
  • Note 2: This option only has an effect on the first run with persistent data.

-c, --cpus: Number of CPUs to utilize in Xpand. [Default: All cores available to the container (fractional values for the --cpus option to docker run are rounded up,) up to a maximum of 8.]

  • Note: Setting this option to a value greater than the number of physical cores/threads is possible, but not recommended, for performance reasons.

-u, --user: Database user to create at start, granted all database privileges, allowed from host %. [Default: xpand]

DB_PASSWD, -p, --passwd: Database user password. [Default: no password]

-P, --port: Database SQL port for TCP connection [Default: 3306]

  • Note: The second argument to the -p option for docker run should match this port in order to allow TCP SQL connections from the container host. (See example below.)

-q, --querylog: Also send query.log output to console rather than /data/xpand/log/query.log

--mini: Alias for minimum viable config with 2 CPUs, 2GiB Memory, and 5GiB storage (long version: -c 2 -m 2048 -d 5).

Example usage:

Run a container with 4GiB memory, 8 CPUs, and 40GB storage:

 $ docker run --ulimit memlock=-1 mariadb/xpand-single -m 4096 -c 8 -d 40

Bind an alternate TCP port for SQL connections:

 $ docker run --ulimit memlock=-1 -p3307:3307 mariadb/xpand-single -P 3307
 $ mariadb -P 3307 -h 127.0.0.1 -u xpand

Create a SQL user with a different name and a password:

 $ docker run --ulimit memlock=-1 mariadb/xpand-single -u dbadmin -p"$SQL_PASSWORD"
 $ mariadb -h 127.0.0.1 -u dbadmin -p

This image also supports docker's --cpus, --cpuset-cpus, and --memory arguments for controlling resource utilization.

For example, to limit the container to 250% cpu usage (xpand --cpus setting becomes 3) and 5.5GiB of memory:

 $ docker run --rm --cpus 2.5 --memory 5.5G -p3306:3306 --ulimit memlock=-1 --name xpand mariadb/xpand-single

Using database dumps

Xpand supports mariadb-dump. One way this can be used with the Xpand docker image is to use docker-exec and run the tool from the same container:

$ docker exec -it xpand mariadb-dump -u xpand -p"$SQL_PASSWORD" --single-transaction --all-databases > xpand-data.sql

Restore data from dump files

For restoring data. You can use the docker exec command with the -i flag, similar to the following:

$ docker exec -i xpand mariadb -uxpand -p"$SQLPASSWD" < databases.sql

More Advanced Usage

Create a persistent database

You can also run Xpand with data persistently stored in a named volume:

$ docker run -v xpand:/data/xpand -p3306:3306 --ulimit memlock=-1 --name xpand mariadb/xpand-single

Or persisted on the host filesystem:

$ docker run -v /var/lib/xpand:/data/xpand -p3306:3306 --ulimit memlock=-1 --name xpand mariadb/xpand-single

With this method, the database can be also accessed from the host OS via the unix socket at /var/lib/xpand/mysql.sock:

$ mariadb -S /var/lib/xpand/mysql.sock -u xpand

Scaling Out

Once you are ready to move onto a clustered version of Xpand, you can try MariaDB SkySQL or request a free download.

Docker Pull Command

docker pull mariadb/xpand-single