Install mysql client in docker image

Install mysql client in docker image

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

Install mysql client in docker image

When building a PHP container for database migrations or dumping, you might encounter a subtle version mismatch between your application's expectations and what apt-get installs by default. The specific scenario often arises when using Laravel 7.x or older versions where the core migration scripts explicitly check for MySQL-specific variables like set-gtid-purged.

If you use the standard command apt-get install -y default-mysql-client, you are actually installing the MariaDB client packages on Debian-based systems. While MariaDB is a drop-in replacement for MySQL, it does not support certain legacy MySQL server variables that older Laravel core scripts attempt to pass via environment variables. This results in the error mysqldump: unknown variable 'set-gtid-purged=OFF', causing your containerized migration process to fail immediately upon startup.

The root cause lies in package naming and distribution defaults. On Ubuntu and Debian, default-mysql-client is a meta-package that pulls in MariaDB binaries because the official MySQL client binary (provided by Oracle) is not included in the standard repositories without specific configuration or third-party sources like MDEV. Since your Laravel script detects the server SQL version to decide how to handle the dump command, it expects the exact behavior of the MySQL client, not the MariaDB variant.

To resolve this, you must explicitly install the MySQL client package rather than relying on the default meta-package. You can achieve this by specifying the full package name available in the Debian/Ubuntu repositories: default-mysql-client is actually a symlink or alias that often resolves to MariaDB in modern distributions. The correct approach is to install the specific package provided by Oracle or ensure you are pulling from a source that offers the genuine MySQL client if strict compatibility is required.

However, for most production environments running on standard Ubuntu/Debian bases, the most reliable fix without adding external repositories is to use default-mariadb-client only if you confirm MariaDB support, but since the requirement is strict MySQL compatibility for older Laravel scripts, you need to switch sources or use a specific package.

If your goal is to ensure the container works with the MySQL protocol strictly as expected by older Laravel versions, you can modify your Dockerfile to install from a repository that provides the genuine MySQL client binaries. Alternatively, if you cannot change the source repositories, you might need to downgrade the PHP version or update the Laravel application code to rely on MariaDB-compatible flags, but modifying the core script is not an option here.

Here is a practical approach using apt-get with specific package management:

FROM library/php:7.4-fpm

# Update package lists
RUN apt-get update

# Install the genuine MySQL client if available in your source list,
# or use default-mariadb-client if you accept MariaDB compatibility.
# Note: On standard Ubuntu 20.04+, 'default-mysql-client' installs MariaDB.
# To get the Oracle MySQL client, you typically need to add a repo like:
# apt-add-repository "deb http://repo.mysql.com/apt/ubuntu/ focal mysql-8.0"
# Then install: apt-get install -y default-mysql-client

# If sticking with standard repos and needing strict MySQL behavior for old scripts:
RUN apt-get install -y default-mariadb-client \
    && rm -rf /var/lib/apt/lists/*

In many cases, the error unknown variable 'set-gtid-purged=OFF' can be bypassed if you configure your MySQL/MariaDB server to not require GTID or adjust the environment variables passed to mysqldump. However, if the Laravel core script is hardcoded to pass this flag based on a version check that identifies MariaDB as "MySQL", the only robust fix without code changes is ensuring the client binary matches the expected signature.

If you are deploying with newer Laravel versions (5.8+), they have largely deprecated the use of set-gtid-purged in favor of more modern migration strategies, but legacy scripts still trigger this check. In such cases, verifying that your Dockerfile installs the correct client package is critical to preventing runtime failures during the initial data dump or migration step.

Always verify the installed binary version inside the container by running mysqldump --version before attempting the migration. If you see "MariaDB" in the output but the script expects MySQL, you may need to adjust your deployment strategy or update the underlying application stack to align with current best practices where MariaDB compatibility is standard across most enterprise setups.

Our network