Skip to content
Percona Software for MySQL Documentation

For help, click the link below to get free database assistance or contact our experts for personalized support.

Get help from Percona

Run Percona Server for MySQL in a Docker Container

Docker lets developers build, deploy, run, update, and manage containers, which isolate applications from the host system. Docker containers are made from Docker images, which are snapshots of the configuration needed to run an application, such as the code and libraries.

Percona solutions

Percona provides a range of solutions and services for open source databases. Some of the critical solutions offered are the following:

  • Database Distributions: Percona offers enhanced, enterprise-ready versions of popular open source databases, such as MySQL, MongoDB, and PostgreSQL

  • Backup Solutions: They provide tools for backing up your databases.

  • Clustering Solutions: Percona offers solutions for setting up and managing database clusters.

  • Observability, Monitoring, and Management Solutions: Percona Monitoring and Management (PMM) is an open source platform for managing and monitoring MySQL, MongoDB, and PostgreSQL performance.

  • Kubernetes Operators: Percona provides Kubernetes operators for automated provisioning and managing databases in Kubernetes.

These databases are supported across traditional deployments, cloud-based platforms, and hybrid IT environments. Percona’s solutions are designed for peak performance, security, scalability, and availability. They also offer support and services for these databases, ensuring they run faster and more reliably.

For this document, container refers to the Docker container and instance refers to the database server in the container.

Reasons for deploying Percona Server in Docker

Deploying a Percona Server for MySQL container is an efficient, fast solution to setting up a database quickly without using too many resources. This type of deployment works best for small to medium applications.

You should deploy a Percona Server for MySQL database in Docker for several reasons. Here are some of them:

  • Portability: Docker containers can run on any platform that supports Docker. This flexibility lets you move your database or installation steps from one platform to another.
  • Isolation: Docker containers are isolated from each other and the host system. This isolation means you can run multiple instances of MySQL on the same machine without interfering with each other or affecting the host’s performance. You can also isolate your database from other applications or services that might pose a security risk or consume too many resources.
  • Scalability: Depending on the load and demand, you can scale docker containers up or down. You can use tools like Docker Compose or Kubernetes to orchestrate multiple containers and manage their configuration, networking, and deployment. You can also use Docker Swarm or Amazon ECS to distribute your containers across multiple nodes and achieve high availability and fault tolerance.
  • Versioning: Docker images and containers contain all the dependencies and configurations needed to run your application. You can use tags to specify different versions of your images and easily switch between them. You can also use Docker Hub or other registries to store and share your images with others.
  • Development: Docker containers can help you create a consistent and reproducible development environment that matches your production environment. You can use tools like Dockerfile or Docker Build to automate the creation of your images and ensure they have the same settings and packages as your production images. You can also use tools like Docker Volumes or Bind Mounts to persist and share your data between containers or the host system.

Review Get more help for ways that we can work with you.

Percona Server for MySQL has an official Docker image hosted on Docker Hub. If you want the latest version, use the latest tag. You can reference a specific version using the Docker tag filter for the 8.0 versions.

We gather Telemetry data in the Percona packages and Docker images.

Make sure that you are using the latest version of Docker. The apt and yum versions may be outdated and cause errors. Install Docker on your system.

Starting a detached container

You can start a background container with the --detached or -d option, which runs the container in the background. In detached mode, the container exits when the root process used to run the container exits.

Benefits of using Docker run

The docker run command automatically pulls the image from a registry if that image is not available locally and starts a Docker container. A container is an isolated environment that runs an application on the host operating system. An image is a template that contains the application code and its dependencies. You can use this command to run an application in a container without affecting the host system or other containers.

The benefits of using the Docker run command are:

  • Allows you to run applications consistently and safely across different platforms and environments.
  • Reduces the overhead and complexity of installing and configuring applications and their dependencies on the host system.
  • Improves the security and isolation of applications by limiting their access to the host resources and other containers.
  • Enables faster development and deployment cycles by allowing you to easily create, update, and destroy containers.

The following example starts a container named ps with the latest version of Percona Server for MySQL 8.0. This action also creates the root user and uses root as the password. Please note that root is not a secure password.

$ docker run -d \
  --name ps \
  -e MYSQL_ROOT_PASSWORD=root \
  percona/percona-server:8.0
Expected output 
Unable to find image 'percona/percona-server:8.0' locally
8.0: Pulling from percona/percona-server

By default, Docker pulls the image from Docker Hub if it is not available locally.

To view the container’s logs, use the following command:

$ docker logs ps --follow
Expected output 
Initializing database
2022-09-07T15:20:03.158128Z 0 [System] [MY-013169] [Server] /usr/sbin/mysqld (mysqld 8.0.29-21) initializing of server in progress as process 15
2022-09-07T15:20:03.167764Z 1 [System] [MY-013576] [InnoDB] InnoDB initialization has started.
2022-09-07T15:20:03.530600Z 1 [System] [MY-013577] [InnoDB] InnoDB initialization has ended.
2022-09-07T15:20:04.367600Z 0 [Warning] [MY-013829] [Server] Missing data directory for ICU regular expressions: /usr/lib64/mysql/private/.
...
2022-09-07T15:20:13.706090Z 0 [System] [MY-011323] [Server] X Plugin ready for connections. Bind-address: '::' port: 33060, socket: /var/lib/mysql/mysqlx.sock
2022-09-07T15:20:13.706136Z 0 [System] [MY-010931] [Server] /usr/sbin/mysqld: ready for connections. Version: '8.0.29-21'  socket: '/var/lib/mysql/mysql.sock'  port: 3306  Percona Server (GPL), Release 21, Revision c59f87d2854.

You can access the server when you see the ready for connections information in the log.

Percona Server for MySQL ARM64

Percona Server for MySQL is available in the ARM64 architecture. You can find the version and architecture on Docker Hub Percona/Percona-Server Tags. Docker Hub provides images for multiple OS/ARCH combinations, letting you select the version and architecture that aligns with your specific system. Docker Hub has two elements for identifying and managing container images: tags and OS/ARCH.

Tags are labels attached to Docker images. The tag identifies the different versions of the same image.

You use a tag to do the following:

  • Pull a specific version of an image (for example, percona/percona-server:22.04)

  • Access the latest version (for example, percona/percona-server:latest)

The OS/ARCH refers to the combination of the operating system (OS) and architecture (ARCH) that an image is designed to run on. Common examples of OS/ARCH combinations include the following:

  • linux/amd64: Runs on Linux systems with 64-bit AMD or Intel processors

  • arm64/v8: Runs on ARM-based systems with 64-bit architecture

Select the desired tag and verify the OS/ARCH (linux/arm64/v8). Add that tag to the docker run command. If you do not add a tag, Docker uses latest as the default tag and assumes you are in the AMD64 architecture.

For example, to download 8.0.35 in linux/arm64/v8, add the 8.0.35-aarch64 tag. The aarch64 section defines the architecture as ARM64. Run the following command:

$ docker run -d \
  --name ps \
  -e MYSQL_ROOT_PASSWORD=root \
  percona/percona-server:8.0.35-aarch64
Expected output 
Unable to find image 'percona/percona-server:8.0.35-aarch64' locally
8.0.35-aarch64: Pulling from percona/percona-server
0f09b26fb4cb: Pull complete
...
121231b07f2a: Pull complete
Digest: sha256:610e7e3beffd09b8a037e2b172452d1231188a6ba12c414e7ffb306846f63b34 
Status: Downloaded newer image for percona/percona-server:8.0.35-aarch64
c0de02ce3b84281e030a710e184f20a6b8f012133ca15a51ed6a35e75d1d8e22

You can also use 8.0.35-27.1-multi. Docker selects the appropriate architecture.

Using Docker --platform for emulation

If you must use an AMD64 version in an ARM64 architecture, add --platform Linux/amd64 to specify the target platform in the docker run command. This option lets you construct images compatible with different architectures using an emulation.

Be aware of the following when running an emulation:

  • May be slower than running in the native architecture for compute-heavy tasks

  • Adds complexity to your environment and may require additional configuration

  • May find subtle architectural differences which lead to runtime issues

Be sure to test the image throughly before using it in production.

Passing Options

You can pass options with the docker run command. For example, the following command uses UTF-8 as the default setting for character set and collation for all databases:

$ docker run -d \
 --name ps \
 -e MYSQL_ROOT_PASSWORD=root \
 percona/percona-server:8.0 \
 --character-set-server=utf8 \
 --collation-server=utf8_general_ci

Accessing the Percona Server Container

The docker exec command lets you have a shell inside the container. This command uses it which forwards your input stream as an interactive TTY.

An example of accessing the detached container:

$ docker exec -it ps /bin/bash

If you need to troubleshoot, the error log is found in /var/log/ or /var/log/mysql/. The file name may be error.log or mysqld.log.

Troubleshooting

You can view the error log with the following command:

[mysql@ps] $ more /var/log/mysql/error.log
Expected output 
...
2017-08-29T04:20:22.190474Z 0 [Warning] 'NO_ZERO_DATE', 'NO_ZERO_IN_DATE' and 'ERROR_FOR_DIVISION_BY_ZERO' sql modes should be used with strict mode. They will be merged with strict mode in a future release.
2017-08-29T04:20:22.190520Z 0 [Warning] 'NO_AUTO_CREATE_USER' sql mode was not set.
...

Accessing the database

You can access the database either with Docker exec or using the mysql command in the container’s shell.

An example of using Docker exec to access the database:

$ docker exec -ti ps mysql -uroot -proot
Expected output 
mysql: [Warning] Using a password on the command line interface can be insecure.
Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 9
...

Exiting Percona Server also exits the container.

You can also run the MySQL command-line client within the container’s shell to access the database:

[mysql@ps] $ mysql -uroot -proot
Expected output 
mysql: [Warning] Using a password on the command line interface can be insecure.
Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 8
Server version: 8.0.29-21 Percona Server (GPL), Release 21, Revision c59f87d2854

Copyright (c) 2009-2022 Percona LLC and/or its affiliates
Copyright (c) 2000, 2022, Oracle and/or its affiliates.

Oracle is a registered trademark of Oracle Corporation and/or its
affiliates. Other names may be trademarks of their respective
owners.

Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

Accessing the server from an application in another container

The image exposes the standard MySQL port 3306, so container linking makes the Percona Server instance available from other containers. To link a container running your application (in this case, from an image named app/image) with the Percona Server container, run it with the following command:

$ docker run -d \
  --name app \
  --link ps \
  app/image:latest

This application container will be able to access the Percona Server container via port 3306.

Storing data

There are two ways to store data used by applications that run in Docker containers:

  • Let Docker manage the storage of your data by writing the database files to disk on the host system using its internal volume management.

  • Create a data directory on the host system on high-performance storage and mount it to a directory visible from the container. This method places the database files in a known location on the host system, and makes it easy for tools and applications on the host system to access the files. The user should ensure that the directory exists, that the user accounts have required permissions, and that any other security mechanisms on the host system are set up correctly.

For example, if you create a data directory on a suitable volume on your host system named /local/datadir, you run the container with the following command:

$ docker run -d \
  --name ps \
  -e MYSQL_ROOT_PASSWORD=root \
  -v /local/datadir:/var/lib/mysql \
  percona/percona-server:8.0

The -v /local/datadir:/var/lib/mysql option mounts the /local/datadir directory on the host to /var/lib/mysql in the container, which is the default data directory used by Percona Server for MySQL.

Do not add MYSQL_ROOT_PASSWORD to the docker run command if the data directory contains subdirectories, files, or data.

Note

If you have SELinux enabled, assign the relevant policy type to the new data directory so that the container will be allowed to access it:

$ chcon -Rt svirt_sandbox_file_t /local/datadir

Port forwarding

Docker allows mapping ports on the container to ports on the host system using the -p option. If you run the container with this option, you can connect to the database by connecting your client to a port on the host machine. This ability simplifies consolidating instances to a single host.

To map the standard MySQL port 3306 to port 6603 on the host:

$ docker run -d \
 --name ps \
 -e MYSQL_ROOT_PASSWORD=root \
 -p 6603:3306 \
 percona/percona-server:8.0

Exiting the container

If you are in the interactive shell, use CTRL-D or exit to exit the session.

If you have a non-shell process running, interrupt the process with CTRL-C before using either CTRL-D or exit.

Stopping the container

The docker stop container command sends a TERM signal, then waits 10 seconds and sends a KILL signal. The following example stops the ps container:

$ docker stop ps

The default length of time before stopping a container is 10 seconds. A very large instance cannot dump the data from memory to disk within that time. With this type of instance, add the --time or the -t option to docker stop:

$ docker stop ps -t 600

Removing the container

To remove a stopped container, use the docker rm command.

$ docker rm ps

For more information

Review the Docker Docs