Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

Spring Boot in a container cannot connect to the MySQL container

ErrorCommunications link failure

Short answer

In Compose the app and MySQL are separate containers. The failure comes from three settings: a JDBC URL that still says localhost, the published host port used where the container port belongs, or an app that starts while MySQL is still preparing its first database. Fix the URL through an environment variable and add a health check.

  • Applies to Spring Boot 3 and 4, MySQL Connector/J 9, MySQL 8.4 Docker image, Docker Compose 2
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Read the JDBC URL the application actually uses, and the state of the MySQL container. The environment of the running app container shows what overrides application.properties.

    docker compose exec app env | grep -i SPRING_DATASOURCE
    docker compose ps
    docker compose logs mysql --tail 20
  2. 2Match what you see, then jump to its fix

    1. 1The URL in the log or in application.properties starts with jdbc:mysql://localhostThe JDBC URL still points at localhostFix
    2. 2mysql is mapped as 3307:3306 and the app URL ends in :3307The URL uses the port published on the hostFix
    3. 3The failure shows only on the first start or after docker compose down -v, and a restart of the app container makes it passThe app starts before MySQL has finished preparing its databaseFix

What does the error look like?

  • Communications link failure

Cause 1 of 3

The JDBC URL still points at localhost

1Check

In the app container, localhost is the app container itself. Other containers are reached by their Compose service name, which each service registers with an internal DNS server. Spring Boot lets an environment variable override a value from application.properties, and the variable for spring.datasource.url is SPRING_DATASOURCE_URL: dots become underscores and the name is upper case.

grep -n "datasource" src/main/resources/application.properties
docker compose exec app env | grep -i datasource

2Fix

Set the URL, user and password for the container through the compose file, with the service name of MySQL as host.

services:
  app:
    build: .
    environment:
      SPRING_DATASOURCE_URL: jdbc:mysql://mysql:3306/appdb
      SPRING_DATASOURCE_USERNAME: appuser
      SPRING_DATASOURCE_PASSWORD: change-me-example
  mysql:
    image: mysql:8.4
    environment:
      MYSQL_ROOT_PASSWORD: change-me-example
      MYSQL_DATABASE: appdb
      MYSQL_USER: appuser
      MYSQL_PASSWORD: change-me-example

3Verify

Recreate the app container and watch for the pool to start.

docker compose up -d --force-recreate app
docker compose logs app --tail 30

Confirmed by docs.spring.io

Did this fix it?

Cause 2 of 3

The URL uses the port published on the host

1Check

In a ports entry the left number is for clients on the host, and the right number is the container port. Services talk to each other on the container port.

docker compose config | grep -n -E -B2 -A2 "published|ports"

2Fix

Use the right-hand number in the URL inside the network, and keep the mapped port for tools on your laptop.

# inside Compose
SPRING_DATASOURCE_URL=jdbc:mysql://mysql:3306/appdb

# from the host, with ports: ["3307:3306"]
jdbc:mysql://localhost:3307/appdb

3Verify

The app logs no connection error after the next start.

docker compose logs app --tail 30

Confirmed by docs.docker.com

Did this fix it?

Cause 3 of 3

The app starts before MySQL has finished preparing its database

1Check

On a fresh data directory the image creates the database first, and the server does not take connections until that is done. Compose waits only until the container runs, not until the server is ready, so the app's first attempt arrives too early.

docker compose logs mysql --tail 40

2Fix

Give MySQL a health check and make the app wait for it. mysqladmin ping reports success when the server is running, even if it then refuses the login.

services:
  mysql:
    image: mysql:8.4
    # MYSQL_ROOT_PASSWORD is set in the environment of this service
    healthcheck:
      test: ["CMD-SHELL", "mysqladmin ping -h localhost -u root -p$${MYSQL_ROOT_PASSWORD}"]
      interval: 10s
      retries: 5
      start_period: 30s
      timeout: 10s
  app:
    depends_on:
      mysql:
        condition: service_healthy

3Verify

docker compose ps shows mysql as healthy, then the app container starts.

docker compose up -d && docker compose ps

Confirmed by docs.docker.com

Did this fix it?

How do I stop it coming back?

  • Keep the datasource settings of containers in the compose file, and leave application.properties for the values that do not change between environments.
  • Run the app with a spring profile for Docker, so a local profile with localhost cannot end up in the image.
  • Give every database service a health check and depend on it with service_healthy.
  • Print the final URL at start-up (without the password) so a wrong host is visible in the first log lines.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.