docker-library/mysql: the Docker Official Image for MySQL Community Server

What docker-library/mysql actually is, and what it is not

This repository is the Git repo of the Docker Official Image for mysql, maintained by the Docker Community and the MySQL Team. The README is explicit that this is not to be confused with any official mysql image provided by mysql upstream. That sentence carries the whole scope of the project: what lives here is packaging, entrypoint logic and build templates, not the database server's own source code.

The practical consequence is that issues about query planning, replication semantics or storage engine behaviour do not belong in this repository. What belongs here is tag generation, Dockerfile structure, the entrypoint script and the version matrix. The README points readers to the Docker Hub page for the full usage readme and to the docker-library/docs repository, specifically the mysql directory, for the image description text. It also points to the library/mysql file in the official-images repository as the current source of truth for the image. If you are deciding whether to adopt this, read those three places, not this repository's README, which is short by design.

The audience is narrow and specific. It is for teams that already run MySQL and want the server in a container with a repeatable tag, and for people who need a disposable MySQL instance for local work or CI. It is not for anyone looking for a managed database, a tuning guide, or a support contract.

How the image is built: version directories, templates and generated files

The repository layout tells you the build model. There are version directories, 8.4/ and 9.7/, alongside an innovation/ directory. There is a Dockerfile.oracle at the top level. The scripts apply-templates.sh, generate-stackbrew-library.sh, update.sh and versions.sh sit next to versions.json.

That combination implies a generated-image workflow rather than hand-edited Dockerfiles. The version directories hold per-release build context, the templates and versions.json drive what gets rendered, and generate-stackbrew-library.sh produces the library file that the official-images repository consumes. This is the standard docker-library pattern, and it explains why the README says the file is generated by generate-repo-stub-readme.sh: the visible documentation is an artifact of the pipeline, not a document a maintainer edits by hand.

The runtime side is docker-entrypoint.sh. In this family of images the entrypoint is the component that decides whether a data directory is already initialized, starts a temporary server to apply initialization when it is not, and then hands off to the real mysqld process. That is why environment variables can create a database and a user on first boot. It is also why the first start of a fresh container takes noticeably longer than subsequent starts: initialization runs once, and the resulting files live in the data directory. Everything after that is the server starting normally.

Where the run instructions actually live

This is the section where a reader expects a command to copy. There is none to give honestly. The README of this repository does not contain a single run command, a single environment variable, or a single port. It says plainly: see the Docker Hub page for the full readme on how to use this Docker image and for information regarding contributing and issues. The full image description on Docker Hub is generated and maintained over in the docker-library/docs repository, specifically in the mysql directory.

So the run instructions for this image are not in this repository at all. They live in two other places, and both are linked from the README: the Docker Hub page for mysql, and the mysql directory of docker-library/docs. If you are evaluating the image, open those. If you copy a command from a blog post instead, you have no way to check whether the variable names and flags still match what the maintainers publish.

This split is deliberate, not an oversight. The README in this repository is itself generated by generate-repo-stub-readme.sh, which is why it reads as a pointer rather than a manual. The repository's job is to build and publish the image; the documentation's job is to explain how to use it. Treating the two as interchangeable is the mistake that leads people to file bugs here about usage questions that the Docker Hub description already answers.

What you can learn from this repository without leaving it is structural: which version lines exist, how the entrypoint is wired, and how the library file that Docker Hub consumes gets generated. That is the material below.

The initialization rule that catches people out

The most common failure with this image family is not a crash. It is silence. Someone changes an initialization variable on an existing data volume, restarts, and nothing happens. The entrypoint only performs initialization against an empty data directory, so the new values are ignored and the old credentials remain in force.

The fix is to remove the volume and start clean, which also removes the data. That is a real trade-off, not a bug: it is what makes the image safe to restart repeatedly without re-running setup. But it means those variables are a provisioning mechanism, not a configuration mechanism. If you need to change a password or add a database on a running instance, do it through SQL, not through the container environment.

The second failure mode is treating the container as durable storage. The data directory is the only stateful path, and a volume has to be mounted there. A container with no volume is fine for a throwaway test and wrong for anything else. Related to this, the image is not a backup strategy. It gives you a server in a container; it does not give you point-in-time recovery, replication topology management or failover. Those are MySQL features you configure yourself, and the image documentation does not walk through them.

The third case is architectural. If your platform does not let you mount a persistent volume, or if you need to run MySQL on a non-Linux base, this image is the wrong tool. It is built for Linux containers, and the repository's Dockerfile.oracle entry shows that variants exist precisely because one base image does not cover every consumer.

How this compares with the upstream Oracle mysql image

The README's warning about confusion points at a genuine fork in the road. There is an official mysql image provided by mysql upstream, and there is this Docker Official Image. They are different artifacts with different maintainers.

The difference in approach is who owns the build. This repository is maintained by the Docker Community and the MySQL Team together, and its images are produced through the docker-library pipeline: version directories, templates, versions.json, and a generated library file that the official-images repository consumes. That pipeline is what makes the tag list consistent, what makes multi-architecture publishing predictable, and what ties the image to the Docker Hub description generated from docker-library/docs.

An upstream-built image follows the vendor's own release and packaging process instead. If your organisation already standardises on Oracle's distribution channel, or your compliance process expects the vendor to be the publisher, that difference matters more than any technical detail of the entrypoint. Conversely, if you want the image that the Docker ecosystem treats as the canonical mysql tag, with the library file as the source of truth, this is the one.

There is no universal answer. Pick based on which publisher your environment already trusts, and check the library/mysql file so you know exactly what a given tag resolves to.

Maintenance, licensing and the cost of upgrading

The repository is not archived, and the last push was on 2026-08-19. That is recent enough that the packaging is being kept in step with MySQL releases, but the README gives no release cadence, no support window and no deprecation policy for individual tags. There is no CHANGELOG in the top-level entries either, so the upgrade path is not documented in this repository.

What you can infer is where upgrade cost comes from. Because tags map to version directories, moving from one major line to another is a tag change plus whatever the server itself requires. The image does not abstract that away, and the README does not document rollback. If you upgrade a data directory in place and the new server version cannot read it, the image will not rescue you. That is a MySQL property, but it lands on you at container level, so plan the upgrade the way you would plan a server upgrade.

Licensing is the other cost to price in. This repository is GPL-2.0. MySQL Community Server itself carries its own licence terms, and the README points you to the Docker Hub page for the full description. Running a GPL-2.0-licensed image does not automatically impose GPL obligations on your application, but the combination of the packaging licence and the server licence is something to have your own counsel review against how you distribute. Nothing here is legal advice, and the repository does not attempt to answer the question for you.

The practical maintenance burden is small if you pin tags and mount volumes. It grows if you track a moving tag, because you inherit whatever the pipeline publishes next without a changelog in this repository to read first.

Editorial conclusion

Adopt this image when you want MySQL Community Server running from a pinned tag with data on a named volume and initialization driven by environment variables, and when you accept that the container's filesystem is disposable. Do not adopt it if you need the upstream Oracle-built image, a non-Linux base, or a deployment where you cannot mount a volume for /var/lib/mysql. Before rollout, verify which tag you are pulling, confirm the licence terms for your distribution, and check the library/mysql file in the official-images repository for the tag's current source of truth.

Frequently asked questions

Official sources

1. docker-library/mysql on GitHub
2. Issues
3. License: GPL-2.0
4. Project website
5. README