Introduction

If a PHP container cannot connect to MySQL through PDO, the pdo_mysql extension is usually missing from the built image. Official PHP Docker images provide helper scripts to compile and enable extensions during build.

This article shows a reliable Dockerfile setup and validation steps.

Core Sections

1) Minimal Dockerfile for pdo_mysql

1FROM php:8.3-fpm
2
3RUN docker-php-ext-install pdo pdo_mysql
4
5WORKDIR /var/www/html
6COPY . .

For most Debian-based official images, this is enough.

2) Add required OS packages when needed

Some variants may require build dependencies.

1RUN apt-get update && apt-get install -y --no-install-recommends \
2    default-mysql-client \
3    && docker-php-ext-install pdo_mysql \
4    && rm -rf /var/lib/apt/lists/*

Keep image lean by cleaning apt lists.

3) Build and verify extension

docker build -t my-php-app .
docker run --rm my-php-app php -m | rg pdo

You should see both PDO and pdo_mysql.

4) Test runtime connection

<?php
$pdo = new PDO('mysql:host=db;dbname=app;charset=utf8mb4', 'user', 'pass');
echo "ok\n";

Run this in container network to verify end-to-end connectivity.

5) Common docker-compose wiring

Ensure PHP service and MySQL service share a network and host uses service name (db), not localhost.

6) Production checklist for PHP Docker database connectivity

Code examples are necessary, but production readiness depends on how this pattern behaves under failure, load, and operational drift. Before rollout, define success criteria that are measurable. A useful baseline is three metrics: correctness (for example, expected output match rate), reliability (error rate and retry behavior), and latency (p95 or p99 execution time). Capture these metrics in a repeatable test environment rather than relying on ad hoc local runs. If external systems are involved, include at least one synthetic fault scenario such as timeout, malformed payload, or temporary dependency outage. This confirms the implementation fails predictably and recovers in a controlled way.

Document environment assumptions close to the code. Include runtime version constraints, required environment variables, and exact dependency versions used during validation. Many regressions come from mismatched environments rather than algorithmic changes. A short README snippet or inline comment that names these assumptions can prevent repeated troubleshooting later. Also define ownership for operational issues: who receives alerts, what threshold triggers action, and what rollback path is acceptable. Without explicit ownership and rollback criteria, otherwise small incidents can take longer to resolve.

A practical rollout sequence is:

1. Run automated checks (lint, unit tests, static validation) in CI.
2. Execute a smoke test against representative input sizes.
3. Validate one failure mode and verify error visibility in logs.
4. Deploy behind a feature flag or phased rollout if possible.
5. Monitor key metrics for a defined stabilization window.

1# Example operator workflow
2make lint
3make test
4./scripts/smoke_check.sh

Finally, keep a short limitations section. State what the current approach intentionally does not optimize or support. This prevents accidental misuse by future contributors and keeps design discussions grounded in explicit tradeoffs. For long-lived systems, schedule periodic review of this implementation, especially after runtime upgrades or library changes. A lightweight maintenance cadence often catches compatibility issues before they become production incidents.

Common Pitfalls

• Installing only pdo but forgetting pdo_mysql.
• Using wrong base image family without matching extension install method.
• Attempting DB connection to localhost inside containerized app.
• Not rebuilding image after Dockerfile changes.
• Skipping runtime verification and assuming extension loaded.

Summary

Enable pdo_mysql during image build using docker-php-ext-install, rebuild image, and verify module presence with php -m. Then test connectivity with proper container network hostnames. This sequence resolves most PDO MySQL issues in PHP Docker setups.

A short maintenance note should accompany this implementation in your repository docs so future contributors know expected behavior, validation steps, and rollback options. That small documentation investment usually prevents repeat regressions during dependency upgrades, framework changes, and environment migrations.