Complete Guide: Connect Docker to MySQL Host

To connect a Docker container to a MySQL server running on the host machine’s localhost, several approaches are available depending on your network configuration and security requirements. The most common methods include using the host network mode for direct connectivity, configuring MySQL to accept connections from the Docker bridge subnet, or using Macvlan networks for more advanced scenarios.

Contents

• Connecting via Host Network Mode
• Connecting via Docker Bridge Network
• Connecting via Macvlan Network
• Connecting via Overlay Network
• MySQL Configuration Requirements
• Security Considerations
• Troubleshooting Connection Issues

Connecting via Host Network Mode

The simplest approach is to use the host network mode, which makes your container share the host machine’s network stack. This means localhost inside the container is exactly the same as localhost on the host machine.

To use this method, run your container with the --network=host flag:

docker run --network=host your-application-image

Advantages:

• Direct access to localhost services without any configuration
• No network overhead
• Simplifies connection strings (use localhost or 127.0.0.1)

Disadvantages:

• Reduced container isolation
• All ports are exposed to the host
• Potential port conflicts with host services

According to Saravana J’s blog post, “The host networking mode will make the container use the same network as the host machine. This means the host machine and the container share the same IP and ports.”

Connecting via Docker Bridge Network

When using the default bridge network (or a custom bridge), you need to configure both MySQL and your container to communicate across the bridge.

Default Bridge Configuration

The default Docker bridge network has a gateway IP of 172.17.0.1 on most systems. You need to:

1. Configure MySQL to accept bridge connections:
   Edit MySQL configuration file (usually /etc/mysql/mysql.conf.d/mysqld.cnf) and set:

   bind-address = 0.0.0.0
   

   Or specifically bind to the bridge IP:

   bind-address = 172.17.0.1
   

2. Create MySQL user with bridge access:

   sql

   CREATE USER 'your_user'@'172.17.0.1' IDENTIFIED BY 'your_password';
   GRANT ALL PRIVILEGES ON *.* TO 'your_user'@'172.17.0.1';
   FLUSH PRIVILEGES;
   

3. Connect from container using bridge IP:

   bash

   mysql -h 172.17.0.1 -u your_user -p
   

Custom Bridge Network

For better isolation, create a custom bridge network:

docker network create -d bridge --subnet=192.168.0.0/24 --gateway=192.168.0.1 my-bridge-net

Then run your container in this network and use the gateway IP for MySQL connections.

As Stack Overflow explains, “When you start MySQL with default settings that bind it to 0.0.0.0 it’s available for Docker containers through the Docker virtual bridge.”

Connecting via Macvlan Network

Macvlan networks assign a MAC address to each container, making them appear as physical devices on your network. This is useful when applications require Layer 2 networking or their own MAC addresses.

Setup Macvlan Network

docker network create -d macvlan \
  --subnet=10.1.149.0/24 \
  --gateway=10.1.149.1 \
  -o parent=eth0 \
  my-macvlan-net

Configure MySQL for Macvlan Access

MySQL needs to accept connections from the Macvlan subnet. You’ll need to:

1. Bind MySQL to all interfaces:

   bind-address = 0.0.0.0
   

2. Create user with Macvlan subnet access:

   sql

   CREATE USER 'your_user'@'10.1.149.%' IDENTIFIED BY 'your_password';
   GRANT ALL PRIVILEGES ON *.* TO 'your_user'@'10.1.149.%';
   FLUSH PRIVILEGES;
   

Important consideration: With Macvlan, containers can’t communicate with the host by default. You’ll need additional configuration to allow host-to-container communication.

As Aiden Arnkels-Webb explains, “When to use it: When you want your containers to act as though they’re physical devices on the same network as your router, and avoid the abstraction layers of Docker and the host.”

Connecting via Overlay Network

Overlay networks are primarily designed for multi-host Docker setups, but can be used for single-host scenarios as well.

Setup Overlay Network

docker network create -d overlay --attachable my-overlay-net

Configure MySQL for Overlay Access

Similar to other network types, MySQL needs to accept connections from the overlay subnet. Since overlay networks use different IP ranges, you’ll need to identify the correct subnet and configure MySQL accordingly.

As Docker documentation states, “For communication among containers running on different Docker daemon hosts, you can either manage routing at the OS level, or you can use an overlay network.”

MySQL Configuration Requirements

Regardless of your Docker network configuration, proper MySQL setup is crucial:

Binding Configuration

MySQL must be configured to accept external connections. Edit your MySQL configuration:

[mysqld]
bind-address = 0.0.0.0  # Accept connections from all interfaces
# or
bind-address = 172.17.0.1  # Accept connections only from Docker bridge

User Privileges

Create appropriate user privileges for your Docker containers:

-- For specific IP access (recommended for security)
CREATE USER 'docker_user'@'172.17.0.1' IDENTIFIED BY 'secure_password';
GRANT ALL PRIVILEGES ON *.* TO 'docker_user'@'172.17.0.1';

-- For subnet access
CREATE USER 'docker_user'@'172.17.0.%' IDENTIFIED BY 'secure_password';
GRANT ALL PRIVILEGES ON *.* TO 'docker_user'@'172.17.0.%';

-- For wildcard access (less secure)
CREATE USER 'docker_user'@'%' IDENTIFIED BY 'secure_password';
GRANT ALL PRIVILEGES ON *.* TO 'docker_user'@'%';

Security Considerations

When connecting Docker containers to host MySQL services, consider these security best practices:

1. Use specific IP ranges instead of wildcard ‘%’ for MySQL user privileges
2. Create dedicated MySQL users for Docker applications with minimal required privileges
3. Consider using SSL/TLS connections between containers and MySQL
4. Regularly update MySQL to the latest stable version
5. Implement proper firewall rules to restrict access to MySQL ports

As noted in the Stack Overflow discussion, you can use iptables to control access to MySQL from Docker containers.

Troubleshooting Connection Issues

If you’re having trouble connecting to MySQL from a Docker container:

Common Issues and Solutions

1. Connection Refused

• Verify MySQL is running and bound to correct interfaces
• Check firewall rules on both host and container
• Ensure MySQL user has proper privileges

2. Network Configuration Problems

• Verify container network settings: docker inspect <container> | grep IPAddress
• Check bridge network configuration: ip addr show docker0
• Test connectivity from container: ping <mysql_host_ip>

3. Authentication Issues

• Verify MySQL user credentials and privileges
• Check MySQL error logs for authentication failures
• Consider resetting MySQL user password if needed

4. Port Conflicts

• Ensure MySQL port (3306) isn’t being used by other services
• Check if port forwarding is properly configured

Conclusion

Connecting Docker containers to a MySQL server on the host machine’s localhost can be accomplished through several methods depending on your specific needs:

1. For simplicity and direct connectivity, use the host network mode with --network=host flag
2. For better isolation with default setup, configure MySQL to accept connections from the Docker bridge subnet (172.17.0.1)
3. For advanced networking needs, consider Macvlan or overlay networks with proper subnet configuration
4. Always follow security best practices by using specific IP ranges for MySQL user privileges and implementing proper firewall rules

The key to successful connection lies in proper MySQL configuration (binding to correct interfaces) and appropriate user privilege setup. Choose the network mode that best balances your connectivity requirements with security and isolation needs.

Sources

1. From inside of a Docker container, how do I connect to the localhost of the machine? - Stack Overflow
2. How to connect docker container with host machine’s localhost mysql database? - Stack Overflow
3. Single Host Networking for MySQL Containers on Docker | Severalnines
4. Dockers seven network types and when to use them | Aiden Arnkels-Webb
5. Sharing a MySQL Database Across Docker Containers | Saravana J
6. Bridge network driver | Docker Docs
7. Networking using a macvlan network | Docker Docs
8. Connect to mysql in a docker container from the host - Stack Overflow