Docker-compose: Connect to database using localhost & mysql as hostname

Docker-compose: Connect to database using localhost & mysql as hostname

July 9, 2026 · Illustrated author avatarBy Stefan Bogdanescu
Docker-compose: Connect to database using localhost & mysql as hostname

Docker-Compose: Connecting to Databases Using localhost & mysql as Hostname

Hello developers! Today I’m going to help you navigate a common challenge when dockerizing your applications for local development—specifically, connecting your application containers to databases using localhost and mysql as the hostname.

Understanding the Challenge

Let’s start by understanding your current setup. You’re working with Magento, which is already quite complex on its own. You’ve tried linking your database container (mariadb) to your application container (php-fpm) using Docker Compose:

    mariadb:
      image: mariadb:5.5
    php-fpm:
      build: docker/php-fpm
      links:
        - "mariadb:mysql"

This works initially, allowing you to reach MariaDB by setting mysql as the hostname instead of 127.0.0.1. However, you want to keep using localhost, and that’s where things start getting tricky.

The Need for Networking Magic

To solve this, let me introduce a networking trick I found in this blog post. It requires setting up a new network bridge:

docker network create --driver bridge mynetwork

Then, attach both your containers to this new network:

    mariadb:
      image: mariadb:5.5
      networks:
        - mynetwork

    php-fpm:
      build: docker/php-fpm
      networks:
        - mynetwork
      links:
        - "mariadb:mysql"

  networks:
    mynetwork:
      driver: bridge

The Catch: Magento’s Weird Expectations

This networking setup works perfectly for most applications. However, you found that it breaks your ability to run PHP scripts that leverage Magento core modules directly on the host machine.

The issue lies in how Magento expects a database hostname called mysql. Since we’re using Docker now and the links feature is deprecated, this expectation isn’t met when we set up our network bridge. That’s why you’re facing this strange behavior.

A Workaround: Overriding the Hostname Environment Variable

To fix this, let’s modify your php-fpm container configuration to override the MYSQL_HOST environment variable:

    php-fpm:
      ...
      environment:
        - MYSQL_HOST=mysql

By doing this, you’re explicitly setting the hostname to mysql, which should satisfy Magento’s weird expectation.

The Final Solution: Balancing localhost & mysql

To achieve your final goal—connecting through localhost and having a database reachable by mysql—you can use the following configuration:

    mariadb:
      image: mariadb:5.5
      networks:
        - mynetwork
      ports:
        - "3306:3306"

    php-fpm:
      build: docker/php-fpm
      networks:
        - mynetwork
      links:
        - "mariadb"
      environment:
        - MYSQL_HOST=mysql

  networks:
    mynetwork:
      driver: bridge

In this setup, MariaDB is exposed through the 3306 port of your host machine (127.0.0.1). This allows you to connect using both localhost:3306 and mysql.

Conclusion

Dockerizing complex applications like Magento requires a deep understanding of networking and configuration. By carefully crafting your Docker Compose configurations, setting up environment variables, and overriding hostnames when necessary, you can achieve the behavior you need.

Remember, dockerization is about standardizing development environments across teams while maintaining the flexibility to connect to services using localhost or specific hostnames as required.

If you found this guide helpful, check out Laravel Company’s guides on Docker for more in-depth tutorials and best practices. Happy coding!

Database Configuration

Our network