How to enable php's mysql extensions in docker container?

How to enable php's mysql extensions in docker container?

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

Stefan Bogdanescu

Founder & Senior Architect

Diagnosing Missing PHP MySQL Extensions in Docker Compose

When configuring a multi-container setup for web development, it is common to encounter connectivity issues between your PHP application and your database service. In the scenario described, the architecture consists of an Nginx reverse proxy, a custom-built PHP-FPM container based on php:7.1.0-fpm-alpine, and a MariaDB instance running on an Alpine image. Despite the presence of a docker-compose.yml that logically links these services and a Dockerfile attempting to install mysqli, the application fails to connect. Adminer reports that none of the supported extensions—MySQLi, MySQL, or PDO_MySQL—are available.

The root cause lies in how the base image handles package installation versus persistence. The command docker-php-ext-install mysqli attempts to compile and install the extension using the FPM entrypoint script. However, simply running this command inside a Dockerfile does not guarantee that the resulting binary survives or functions correctly if the underlying build environment is not configured properly. More critically, in many Alpine-based setups, the installation might succeed within the context of the build but fail to register correctly when the container starts, often due to missing system libraries like libpq (for PostgreSQL) or specific MySQL client libraries that are not part of the minimal base image by default.

The immediate fix involves ensuring that the necessary development dependencies are installed before attempting to compile the PHP extensions. The standard procedure for Alpine images requires installing php7-dev, php7-pdo, and usually libpng or other headers depending on the specific extension requirements. Without these headers, docker-php-ext-install may either fail silently or produce a binary that cannot be loaded by the PHP interpreter at runtime.

Here is the corrected approach for your Dockerfile:

FROM php:7.1.0-fpm-alpine

# Install system dependencies required for compiling extensions
RUN apk add --no-cache \
    gcc \
    libc6-compat \
    autoconf \
    automake \
    libtool \
    make \
    pkgconfig \
    file \
    unzip \
    libjpeg-turbo-dev \
    libpng-dev \
    freetype-dev \
    oniguruma-dev \
    libxml2-dev \
    curl-dev \
    libzip-dev \
    zip \
    mariadb-connector-c-devel

# Install PHP extensions and enable them
RUN docker-php-ext-install -j$(nproc) mysqli pdo pdo_mysql && \
    docker-php-ext-enable mysqli pdo_mysql

# Clean up to reduce image size
RUN apk del --purge gcc g++ make autoconf automake libtool pkgconfig file unzip \
    && rm -rf /var/cache/apk/*

Note the explicit addition of mariadb-connector-c-devel. Since your database service is running yobasystems/alpine-mariadb, using the MariaDB connector ensures compatibility. While mysqli often pulls in the necessary client libraries automatically, explicit dependency management prevents subtle runtime errors where the extension exists but cannot resolve symbols.

Another critical aspect of this setup is the volume mounting strategy. Your current configuration mounts ./mysql:/var/lib/mysql directly from the host to the container. This approach persists data between restarts but ties your database state to the specific host machine. In a production or CI/CD environment, you might consider using named volumes instead. However, for local development where you need immediate access to the database files, bind mounting is acceptable provided that file permissions are handled correctly.

It is also worth noting that the links directive in your docker-compose.yml is deprecated and removed in recent versions of Docker Compose (v2+). Modern networking relies on service names as DNS hostnames. As long as your containers are defined within the same network, php can connect to mysql using mysql:3306 as the hostname without needing the legacy links configuration.

If you prefer not to build a custom image from scratch, you could alternatively install the extensions via apt-get (if switching to Debian-based images) or ensure that the base PHP image variant includes the necessary tools. However, sticking with Alpine offers a leaner footprint, provided the compilation steps are rigorous.

For Laravel projects specifically, ensuring these extensions are available is non-negotiable for database abstraction layers. If you find yourself managing complex dependency trees, consider leveraging pre-configured official images that bundle common extensions, or utilize the https://laravelcompany.com resource for guidance on optimizing your PHP environment for web applications.

Our network