How to fix 'SQLSTATE[HY000] [2002] Connection refused' Laravel error in GitHub Actions

GitHub Actions streamlines continuous integration (CI) for GitHub repositories. YAML workflow files automate tasks like testing and deployment. A common Laravel/MySQL CI snag is the "SQLSTATE[HY000] [2002] Connection refused" error, often cropping up during initial test migrations. This article explores three frequent causes and their solutions.

A Valid GitHub Actions Workflow (Example)

Before troubleshooting, let's examine a functional Laravel/MySQL GitHub Actions workflow:

name: Run tests

on: [push]

jobs:
  tests:
    name: Run tests
    runs-on: ubuntu-latest

    services:
      mysql:
        image: mysql:8
        env:
          MYSQL_ROOT_PASSWORD: password
          MYSQL_DATABASE: testing
        ports:
          - 3306:3306
        options: --health-cmd="mysqladmin ping" --health-interval=10s --health-timeout=5s --health-retries=3

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 1

      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: 8.3

      - name: Run composer install
        run: composer install -n --prefer-dist

      - name: Prepare Laravel Application
        run: |
          cp .env.ci .env
          php artisan key:generate

      - name: Run tests
        run: php artisan test

.env.ci:

<code>DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=testing
DB_USERNAME=root
DB_PASSWORD=password</code>

1. Incorrect MySQL Port

The most common culprit: mismatched port numbers. GitHub Actions assigns a random port to the service container's 3306.

• Dynamic Port: Access the assigned port using ${{ job.services.mysql.ports['3306'] }}:

- name: Run tests
  run: php artisan test
  env:
    DB_PORT: ${{ job.services.mysql.ports['3306'] }}

• Hardcoded Port: Explicitly define the port (e.g., 33306) in both the workflow and .env.ci.

2. Missing MySQL Service

Overlooking the services definition is a frequent oversight. The workflow above demonstrates the correct inclusion. Without it, the connection fails.

3. MySQL Unavailability

Even with a service defined, MySQL might not be immediately responsive. The options parameter in the mysql service definition is crucial:

options: --health-cmd="mysqladmin ping" --health-interval=10s --health-timeout=5s --health-retries=3

This ensures the workflow waits until MySQL is ready before proceeding. Without this, tests might run prematurely, resulting in the connection error.

Conclusion

This guide covers three key reasons for the "SQLSTATE[HY000] [2002] Connection refused" error in GitHub Actions Laravel/MySQL workflows. Addressing port mapping, service definition, and MySQL readiness ensures smoother CI processes. For production application stability, consider robust error monitoring tools like Honeybadger, which integrates well with Laravel.

The above is the detailed content of How to fix 'SQLSTATE[HY000] [2002] Connection refused' Laravel error in GitHub Actions. For more information, please follow other related articles on the PHP Chinese website!