Using a local containerized database offers flexibility and ease of setup,letting you mirror production environments closely without the overhead oftraditional database installations. Docker simplifies this process, enabling youto deploy, manage, and scale databases in isolated containers with just a fewcommands.

In this guide, you'll learn how to:

This guide uses the MySQL image for examples, but the concepts can be applied to other database images.

To follow along with this guide, you must have Docker installed. To install Docker, seeGet Docker.

Most popular database systems, including MySQL, PostgreSQL, and MongoDB, have aDocker Official Image available on Docker Hub. These images are a curated setimages that follow best practices, ensuring that you have access to the latestfeatures and security updates. To get started, visitDocker Hub and search for the database you'reinterested in. Each image's page provides detailed instructions on how to runthe container, customize your setup, and configure the database according toyour needs. For more information about the MySQL image used in this guide, see the Docker HubMySQL image page.

To run a database container, you can use either the Docker Desktop GUI orCLI.

To run a container using the CLI, run the following command in a terminal:

In this command:

To verify that you container is running, run docker ps in a terminal

To run a container using the GUI:

In the Docker Desktop Dashboard, select the global search at the top of the window.

Specify mysql in the search box, and select the Images tab if not alreadyselected.

Hover over the msyql image and select Run.The Run a new container model appears.

Expand Optional settings.

In the optional settings, specify the following:

Select Run.

Open the Container view in the Docker Desktop Dashboard to verify that yourcontainer is running.

When you have a database running inside a Docker container, you may need toaccess its shell to manage the database, execute commands, or performadministrative tasks. Docker provides a straightforward way to do this using thedocker exec command. Additionally, if you prefer a graphical interface, youcan use Docker Desktop's GUI.

If you don't yet have a database container running, seeRun a local containerized database.

To access the terminal of a MySQL container using the CLI, you can use thefollowing docker exec command.

In this command:

After executing this command, you will be given access to the bash shell insideyour MySQL container, from which you can manage your MySQL server directly. Youcan run exit to return to your terminal.

In this terminal you can access to the shell inside your MySQL container, fromwhich you can manage your MySQL server directly.

Once you've accessed the container's terminal, you can run any tools availablein that container. The following example shows using mysql in the container tolist the databases.

Connecting to a containerized database from your host machine involves mapping aport inside the container to a port on your host machine. This process ensuresthat the database inside the container is accessible via the host machine'snetwork. For MySQL, the default port is 3306. By exposing this port, you can usevarious database management tools or applications on your host machine tointeract with your MySQL database.

Before you begin, you must remove any containers you previously ran for thisguide. To stop and remove a container, either:

Next, you can use either the Docker Desktop GUI or CLI to run the container withthe port mapped.

Run the following command in a terminal.

In this command, -p 3307:3306 maps port 3307 on the host to port 3306 in the container.

To verify the port is mapped, run the following command.

You should see output like the following.

To run a container using the GUI:

In the Docker Desktop Dashboard, select the global search at the top of the window.

Specify mysql in the search box, and select the Images tab if not alreadyselected.

Hover over the msyql image and select Run.The Run a new container model appears.

Expand Optional settings.

In the optional settings, specify the following:

Select Run.

In the Containers view, verify that the port is mapped under thePort(s) column. You should see 3307:3306 for the my-mysqlcontainer.

At this point, any application running on your host can access the MySQL service in the container at localhost:3307.

Connecting to a containerized database from another container is a commonscenario in microservices architecture and during development processes.Docker's networking capabilities make it easy to establish this connectionwithout having to expose the database to the host network. This is achieved byplacing both the database container and the container that needs to access it onthe same Docker network.

Before you begin, you must remove any containers you previously ran for thisguide. To stop and remove a container, either:

To create a network and run containers on it:

Run the following command to create a Docker network named my-network.

Run your database container and specify the network using the --networkoption. This runs the container on the my-network network.

Run your other containers and specify the network using the --networkoption. For this example, you'll run a phpMyAdmin container that can connectto your database.

Run a phpMyAdmin container. Use the --network option to specify thenetwork, the -p option to let you access the container from your hostmachine, and the -e option to specify a required environment variablefor this image.

Verify that the containers can communicate. For this example, you'll accessphpMyAdmin and verify that it connects to the database.

At this point, any application running on your my-network container networkcan access the MySQL service in the container at my-mysql:3306.

Persisting database data in a Docker volume is necessary for ensuring that yourdata survives container restarts and removals. A Docker volume lets you storedatabase files outside the container's writable layer, making it possible toupgrade the container, switch bases, and share data without losing it. Here’show you can attach a volume to your database container using either the DockerCLI or the Docker Desktop GUI.

Before you begin, you must remove any containers you previously ran for thisguide. To stop and remove a container, either:

Next, you can use either the Docker Desktop GUI or CLI to run the container with a volume.

To run your database container with a volume attached, include the -v optionwith your docker run command, specifying a volume name and the path where thedatabase stores its data inside the container. If the volume doesn't exist,Docker automatically creates it for you.

To run a database container with a volume attached, and then verify that thedata persists:

Run the container and attach the volume.

This command mounts the volume named my-db-volume to the /var/lib/mysql directory in the container.

Create some data in the database. Use the docker exec command to runmysql inside the container and create a table.

This command uses the mysql tool in the container to create a table namedmytable with a column named column_name, and finally inserts a value ofvalue.

Stop and remove the container. Without a volume, the table you created wouldbe lost when removing the container.

Start a new container with the volume attached. This time, you don't need tospecify any environment variables as the configuration is saved in thevolume.

Verify that the table you created still exists. Use the docker exec commandagain to run mysql inside the container.

This command uses the mysql tool in the container to select all therecords from the mytable table.

You should see output like the following.

To run a database container with a volume attached, and then verify that thedata persists:

Run a container with a volume attached.

In the Docker Desktop Dashboard, select the global search at the top of the window.

Specify mysql in the search box, and select the Images tab if notalready selected.

Hover over the mysql image and select Run.The Run a new container model appears.

Expand Optional settings.

In the optional settings, specify the following:

Here, the name of the volume is my-db-volume and it is mounted in thecontainer at /var/lib/mysql.

Select Run.

Create some data in the database.

In the Containers view, next to your container select the Showcontainer actions icon, and then select Open in terminal.

Run the following command in the container's terminal to add a table.

This command uses the mysql tool in the container to create a tablenamed mytable with a column named column_name, and finally inserts avalue of value`.

In the Containers view, select the Delete icon next to yourcontainer, and then select Delete forever. Without a volume, the tableyou created would be lost when deleting the container.

Run a container with a volume attached.

In the Docker Desktop Dashboard, select the global search at the top of the window.

Specify mysql in the search box, and select the Images tab if notalready selected.

Hover over the mysql image and select Run.The Run a new container model appears.

Expand Optional settings.

In the optional settings, specify the following:

Select Run.

Verify that the table you created still exists.

In the Containers view, next to your container select the Showcontainer actions icon, and then select Open in terminal.

Run the following command in the container's terminal to verify that tableyou created still exists.

This command uses the mysql tool in the container to select all therecords from the mytable table.

You should see output like the following.

At this point, any MySQL container that mounts the my-db-volume will be ableto access and save persisted data.

Customizing your database image lets you include additional configuration,scripts, or tools alongside the base database server. This is particularlyuseful for creating a Docker image that matches your specific development orproduction environment needs. The following example outlines how to build andrun a custom MySQL image that includes a table initialization script.

Before you begin, you must remove any containers you previously ran for thisguide. To stop and remove a container, either:

To build and run your custom image:

Create a Dockerfile.

Create a file named Dockerfile in your project directory. For thisexample, you can create the Dockerfile in an empty directory of yourchoice. This file will define how to build your custom MySQL image.

Add the following content to the Dockerfile.

In this Dockerfile, you've set the environment variable for the MySQLdatabase name. You can also use the COPY instruction to add customconfiguration files or scripts into the container. In thisexample, files from your host's ./scripts/ directory are copied into thecontainer's /docker-entrypoint-initdb.d/ directory. In this directory,.sh, .sql, and .sql.gz scripts are executed when the container isstarted for the first time. For more details about Dockerfiles, see theDockerfile reference.

Create a script file to initialize a table in the database. In thedirectory where your Dockerfile is located, create a subdirectory namedscripts, and then create a file named create_table.sql with thefollowing content.

You should now have the following directory structure.

Build your image.

In a terminal, change directory to the directory where your Dockerfileis located.

Run the following command to build the image.

In this command, -t my-custom-mysql tags (names) your new image asmy-custom-mysql. The period (.) at the end of the command specifies thecurrent directory as the context for the build, where Docker looks for theDockerfile and any other files needed for the build.

Run your image as you did inRun a local containerizeddatabase. This time, specify yourimage's name instead of mysql:latest. Also, you no longer need to specifythe MYSQL_DATABASE environment variable as it's now defined by yourDockerfile.

Verify that your container is running with the following command.

You should see output like the following.

Verify that your initialization script was ran. Run the following command ina terminal to show the contents of the myothertable table.

You should see output like the following.

Any container ran using your my-custom-mysql image will have the tableinitialized when first started.

Docker Compose is a tool for defining and running multi-container Dockerapplications. With a single command, you can configure all your application'sservices (like databases, web apps, etc.) and manage them. In this example,you'll create a Compose file and use it to run a MySQL database container and a phpMyAdmin container.

To run your containers with Docker Compose:

Create a Docker Compose file.

Create a file named compose.yaml in your project directory. This filewill define the services, networks, and volumes.

Add the following content to the compose.yaml file.

For the database service:

In addition to the database service, there is a phpMyAdmin service. Bydefault Compose sets up a single network for your app. Each container fora service joins the default network and is both reachable by othercontainers on that network, and discoverable by the service's name.Therefore, in the PMA_HOST environment variable, you can specify theservice name, db, in order to connect to the database service. For more details about Compose, see theCompose file reference.

Run Docker Compose.

Open a terminal and change directory to the directory where yourcompose.yaml file is located.

Run Docker Compose using the following command.

You can now access phpMyAdmin athttp://localhost:8080 and connect to yourdatabase using root as the username and my-secret-pw as the password.

To stop the containers, press ctrl+c in the terminal.

Now, with Docker Compose you can start your database and app, mount volumes,configure networking, and more, all with a single command.

This guide introduced you to the essentials of using containerized databases,specifically focusing on MySQL, to enhance flexibility, ease of setup, andconsistency across your development environments. The use-cases covered inthis guide not only streamline your development workflows but also prepare youfor more advanced database management and deployment scenarios, ensuring yourdata-driven applications remain robust and scalable.

Related information: