MariaDB Docker: How to Run and Manage a Database Container

MariaDB Docker lets you run MariaDB Server inside a Docker container without installing the database server directly on your host operating system. You can use Docker to create an isolated database environment, simplify deployment, and manage database configuration consistently across development, testing, and production.

The easiest way to get started is to run the official MariaDB image with a persistent volume and a secure root password. For applications with multiple services, MariaDB Docker Compose provides a convenient way to define the database, application, network, and storage in one configuration file.

What Is MariaDB Docker?

MariaDB Docker refers to running MariaDB Server through Docker containers. MariaDB is an open-source relational database management system that stores structured information in tables and supports SQL queries.

A Docker container packages the database software and its runtime environment. You can start, stop, replace, or update the container without managing a traditional database installation on the host in the same way.

MariaDB in Docker is useful for:

• Local development and testing
• WordPress and other web applications
• API backends and application databases
• Reproducible development environments
• Staging environments that resemble production
• Applications deployed with Docker Compose

However, the database files must be stored persistently. Removing a container should not mean losing important database records, so storage, backups, and recovery need to be planned from the beginning.

Why Run MariaDB in a Docker Container?

Running MariaDB in a Docker container offers several benefits, especially when you need consistent environments or manage multiple applications.

1. Easier Deployment

You can start MariaDB from an image instead of manually installing and configuring the database server. A Docker command or Compose file can document the settings required to recreate the environment.

2. Application Isolation

You can run MariaDB separately from your web server, application runtime, and other services. This separation makes it easier to manage dependencies and troubleshoot individual components.

Containers still share the host’s underlying kernel, so Docker should not be treated as a complete security boundary.

3. Reproducible Environments

A team can use the same MariaDB image version and similar configuration across development, staging, and production. This reduces differences between environments, although operating system, hardware, configuration, and data can still affect behavior.

4. Flexible Database Management

You can configure database credentials, storage, networking, and supported server options when creating the container. You can also use Docker Compose to manage MariaDB alongside applications that depend on it.

5. Resource Management

Docker provides mechanisms for controlling container CPU and memory usage. These controls help you manage resource allocation, but you still need to monitor MariaDB performance and leave enough memory for the operating system and other services.

Prerequisites for Running MariaDB with Docker

Before deploying MariaDB, make sure your environment is ready.

• Docker Engine: Install a supported version of Docker on your Linux server or development machine.
• Docker Compose: Install or verify the Docker Compose plugin if you plan to manage multiple services.
• Storage: Reserve enough disk space for database files, logs, backups, and future growth.
• Credentials: Prepare a strong, unique database password.
• Network configuration: Decide whether the database needs local access, access from other containers, or a controlled external connection.
• Backup plan: Determine how you will protect and restore database data.

You can follow the official Docker Engine installation guide and the Docker Compose installation guide.

Verify your installation:

docker --version
docker compose version

docker --version
docker compose version

If you are using a Linux account that requires administrative privileges for Docker, prefix the commands with sudo.

How to Run Docker Container MariaDB

The following steps create a MariaDB container with persistent storage and a dedicated database user.

Step 1: Create a Docker Volume

Create a named volume to store MariaDB data outside the container’s writable layer.

docker volume create mariadb_data

docker volume create mariadb_data

A named volume allows the database files to persist when the container is replaced. It does not protect those files from disk failure, accidental deletion, or every form of data corruption.

Step 2: Start the MariaDB Container

Run the official MariaDB image:

docker run -d \
  --name mariadb-server \
  --restart unless-stopped \
  -e MARIADB_ROOT_PASSWORD='replace-with-a-strong-password' \
  -e MARIADB_DATABASE='appdb' \
  -e MARIADB_USER='appuser' \
  -e MARIADB_PASSWORD='replace-with-a-different-password' \
  -v mariadb_data:/var/lib/mysql \
  mariadb:lts

docker run -d \
  --name mariadb-server \
  --restart unless-stopped \
  -e MARIADB_ROOT_PASSWORD='replace-with-a-strong-password' \
  -e MARIADB_DATABASE='appdb' \
  -e MARIADB_USER='appuser' \
  -e MARIADB_PASSWORD='replace-with-a-different-password' \
  -v mariadb_data:/var/lib/mysql \
  mariadb:lts

Replace both example passwords with strong, unique credentials before running the command. Avoid saving real passwords in shell history or sharing commands containing secrets.

This command:

• Runs the container in the background.
• Names it mariadb-server.
• Configures a restart policy.
• Sets the initial root password.
• Creates an application database named appdb.
• Creates an application user named appuser.
• Stores database files in the mariadb_data volume.
• Uses the official MariaDB long-term support image tag.

The MARIADB_DATABASE, MARIADB_USER, and MARIADB_PASSWORD variables configure the initial database and user when the data directory is empty. They do not automatically reset credentials or recreate databases in an already initialized data directory.

For production, use an appropriate secrets-management method rather than placing credentials directly in shell commands. The Compose example later in this guide demonstrates file-based secrets.

Step 3: Check the Container Status

Verify that the container is running:

docker ps

docker ps

View its startup logs:

docker logs mariadb-server

docker logs mariadb-server

Wait until MariaDB finishes initializing before trying to connect. A running container does not necessarily mean the database is ready to accept connections.

Step 4: Connect to MariaDB

Open a MariaDB client session inside the container:

docker exec -it mariadb-server \
  mariadb -u appuser -p appdb

docker exec -it mariadb-server \
  mariadb -u appuser -p appdb

Enter the application user’s password when prompted.

You can test the connection with a simple SQL statement:

SELECT VERSION();

SELECT VERSION();

To exit the client, run:

EXIT;

EXIT;

Using docker exec lets you connect without exposing MariaDB’s port to the public internet.

How to Use MariaDB Docker Compose

Docker Compose is useful when MariaDB is part of a larger application. Instead of running a long command manually, you define the database service, storage, network, and credentials in a Compose configuration.

This example creates a MariaDB service with persistent storage and a health check.

Step 1: Create a Project Directory

Create a dedicated directory for the database configuration:

mkdir mariadb-docker
cd mariadb-docker

mkdir mariadb-docker
cd mariadb-docker

Create a file named compose.yaml with the following configuration:

services:
  mariadb:
    image: mariadb:lts
    restart: unless-stopped
    environment:
      MARIADB_ROOT_PASSWORD_FILE: /run/secrets/mariadb_root_password
      MARIADB_DATABASE: appdb
      MARIADB_USER: appuser
      MARIADB_PASSWORD_FILE: /run/secrets/mariadb_app_password
    secrets:
      - mariadb_root_password
      - mariadb_app_password
    volumes:
      - mariadb_data:/var/lib/mysql
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 30s

secrets:
  mariadb_root_password:
    file: ./secrets/mariadb_root_password.txt
  mariadb_app_password:
    file: ./secrets/mariadb_app_password.txt

volumes:
  mariadb_data:

services:
  mariadb:
    image: mariadb:lts
    restart: unless-stopped
    environment:
      MARIADB_ROOT_PASSWORD_FILE: /run/secrets/mariadb_root_password
      MARIADB_DATABASE: appdb
      MARIADB_USER: appuser
      MARIADB_PASSWORD_FILE: /run/secrets/mariadb_app_password
    secrets:
      - mariadb_root_password
      - mariadb_app_password
    volumes:
      - mariadb_data:/var/lib/mysql
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 30s

secrets:
  mariadb_root_password:
    file: ./secrets/mariadb_root_password.txt
  mariadb_app_password:
    file: ./secrets/mariadb_app_password.txt

volumes:
  mariadb_data:

This configuration uses file-based secrets so that the passwords do not need to appear directly in the Compose file. The MariaDB official image supports the _FILE form of these initialization variables.

Step 2: Create the Secret Files

Create the directory and two password files:

mkdir secrets
nano secrets/mariadb_root_password.txt
nano secrets/mariadb_app_password.txt

mkdir secrets
nano secrets/mariadb_root_password.txt
nano secrets/mariadb_app_password.txt

Place a different, strong password in each file. Save the files and restrict their permissions:

chmod 600 secrets/mariadb_root_password.txt
chmod 600 secrets/mariadb_app_password.txt

chmod 600 secrets/mariadb_root_password.txt
chmod 600 secrets/mariadb_app_password.txt

Do not commit these files to version control or include them in public backups. For production deployments, consider your platform’s dedicated secret-management system and access controls.

Docker Compose file-based secrets are mounted into containers as files. They are not the same as encrypted, centrally managed secrets in every deployment environment, so protect the source files and host appropriately.

Step 3: Start the MariaDB Service

Start the service in the background:

docker compose up -d

docker compose up -d

Check the service status:

docker compose ps

docker compose ps

View the database logs:

docker compose logs mariadb

docker compose logs mariadb

The health check tests whether MariaDB can accept a connection and whether InnoDB has initialized. A healthy status is a useful readiness signal, but it does not confirm that every application query will succeed.

Step 4: Connect to the Database

Run the MariaDB client inside the service container:

docker compose exec mariadb \
  mariadb -u appuser -p appdb

docker compose exec mariadb \
  mariadb -u appuser -p appdb

Enter the application user’s password when prompted.

When your application also runs in the same Compose project, it can usually connect to the database using the service name mariadb and port 3306. You do not need to publish the database port to the host for communication between services on the same Compose network.

Step 5: Stop or Restart the Service

Stop the Compose project:

docker compose down

docker compose down

Start it again:

docker compose up -d

docker compose up -d

The named volume remains when you run docker compose down without the -v option. Do not add -v casually because it can remove project-managed volumes and permanently delete database data if no other copy exists.

How to Connect an Application to MariaDB Docker

An application needs the database hostname, port, database name, username, and password to connect to MariaDB.

For an application running in the same Compose project, use settings similar to these:

The hostname mariadb works because it matches the Compose service name. It is not a universal hostname for every Docker installation.

Example Application Configuration

A typical application environment might contain:

DB_HOST=mariadb
DB_PORT=3306
DB_DATABASE=appdb
DB_USERNAME=appuser

DB_HOST=mariadb
DB_PORT=3306
DB_DATABASE=appdb
DB_USERNAME=appuser

Provide the password through the application’s supported secret mechanism. Do not publish database credentials in source code, screenshots, logs, or public repositories.

If the application runs directly on the Docker host instead of inside the Compose network, the service name may not resolve. You would need a suitable network route and connection address. Publishing port 3306 can enable host access, but bind it to a trusted interface and restrict firewall access rather than exposing the database publicly.

How to Make MariaDB Docker Data Persistent

Persistent storage is essential because a database stores information that must survive container replacement.

The recommended basic approach is a named volume:

services:
  mariadb:
    image: mariadb:lts
    volumes:
      - mariadb_data:/var/lib/mysql

volumes:
  mariadb_data:

services:
  mariadb:
    image: mariadb:lts
    volumes:
      - mariadb_data:/var/lib/mysql

volumes:
  mariadb_data:

Docker stores the database files in the named volume rather than only in the container’s writable layer.

Named Volumes vs. Bind Mounts

For most beginners, a named volume is the simpler choice. A bind mount can be useful when you have a specific storage layout or need to manage files at a known host path, but permissions and ownership require careful handling.

Do not manually edit live database files inside the data directory. Use MariaDB’s supported tools for database operations, backups, and recovery.

How to Back Up and Restore MariaDB Docker

A persistent volume protects data from ordinary container replacement, but it is not a backup. A separate backup is needed to recover from accidental deletion, corruption, disk failure, or a compromised server.

Create a Logical Backup

You can use mariadb-dump inside the container to export a database:

docker exec mariadb-server \
  mariadb-dump -u root -p appdb > appdb-backup.sql

docker exec mariadb-server \
  mariadb-dump -u root -p appdb > appdb-backup.sql

This prompts for the root password. Depending on your environment and client version, the password prompt may need to be handled differently when executing a command through a non-interactive pipeline. For production automation, use a protected client configuration or a suitable secrets mechanism rather than embedding a password in the command.

Check that the resulting SQL file exists and is not empty. Store backups away from the database server and restrict access because a database dump may contain sensitive information.

Restore a Logical Backup

To restore a dump into the database, use a command such as:

docker exec -i mariadb-server \
  mariadb -u root -p appdb < appdb-backup.sql

docker exec -i mariadb-server \
  mariadb -u root -p appdb < appdb-backup.sql

Interactive password prompting can be unreliable with some combinations of docker exec, input redirection, and client versions. For repeatable restores, use a secure client configuration or another supported way to provide credentials.

Test restores in a separate environment before relying on a backup during an outage. A successful export alone does not prove that the database can be recovered correctly.

For more information, review the official MariaDB Docker documentation.

Common MariaDB Docker Problems and Fixes

1. MariaDB Container Keeps Restarting

Check the container state and logs:

docker ps -a
docker logs mariadb-server

docker ps -a
docker logs mariadb-server

Look for invalid configuration, initialization errors, missing storage access, insufficient memory, or port conflicts. Fix the underlying cause before repeatedly restarting the container.

2. Access Denied for Database User

Verify the username, password, database name, and grants. Remember that the initial environment variables do not reset credentials in an already initialized database volume.

If you changed the Compose password but the old volume already contains a database, update the account through MariaDB’s supported SQL account-management process rather than deleting the volume.

3. Application Cannot Connect to MariaDB

Confirm that the database is ready and that the application uses the correct hostname and port.

For services on the same Compose network, the database service name is generally the correct hostname. If the application runs on the host, check the port mapping, listening interface, and firewall rules.

4. Database Data Disappears After Container Removal

This can happen when data was stored only in the container’s writable layer or when the persistent volume was deleted.

Attach a named volume to /var/lib/mysql and verify that it remains after stopping or recreating the container. Maintain separate backups as well.

5. Port 3306 Is Already in Use

If Docker reports a port conflict, another service may already be listening on the host port. Check listening ports and review your container configuration.

If only other containers need database access, you usually do not need to publish port 3306 at all.

6. Database Initialization Settings Do Not Change

The official MariaDB image uses initialization variables when creating a new database in an empty data directory. Most of these settings do not reinitialize an existing database.

Review the existing volume and current database configuration before making changes. Back up important data before attempting a migration or reinitialization.

MariaDB Docker Security Best Practices

A containerized database still needs the same core protections as any other database server.

1. Use strong credentials. Keep root access separate from the application’s database account.
2. Avoid public database exposure. Do not publish port 3306 unless necessary, and restrict access to trusted networks.
3. Protect secrets. Use suitable secret-management practices instead of hardcoding passwords in source files.
4. Persist database data. Mount a named volume or a carefully configured bind mount.
5. Back up data regularly. Store backups separately from the running database and test recovery.
6. Pin and maintain image versions. Choose an appropriate MariaDB release tag, test upgrades, and avoid unexpected major-version changes.
7. Monitor resource usage. Watch memory, CPU, storage, logs, and database health.
8. Use least privilege. Applications should connect with dedicated database users that have only the permissions they require.
9. Plan upgrades carefully. Back up the database and test version changes before updating production.
10. Restrict host access. Keep Docker administration and server access limited to trusted administrators.

Frequently Asked Questions

Conclusion

MariaDB Docker provides a practical way to deploy a relational database in a repeatable container environment. You can start with the official MariaDB image, attach persistent storage, and use Docker Compose when your application requires multiple services.

For a reliable deployment, keep database access private, protect credentials, monitor container health, and maintain tested backups. These practices help make a simple development container safer to operate and provide a stronger foundation for production workloads.