Laravel deployment issues: why is my database not connecting?

but now i'm stuck on a new, super frustrating problem – my database isn't connecting on the live server. i'm a total noob with this stuff, so please bear with me.

Hello Ling Kim,

I completely understand how frustrating this "connection refused" error can be. I've been in your shoes more times than I care to count, especially with new Laravel deployments. It's a classic server configuration headache that often comes down to environment variables or PHP module issues.

You've already done some solid troubleshooting by checking the .env, clearing caches, and verifying direct database access. That last point, specifically, is critical: if you can connect from the server's terminal with the same credentials, the database itself is healthy and reachable from the server machine. This shifts our focus squarely onto how your Laravel application, via PHP-FPM/Nginx or Apache, is interpreting and using those credentials.

Here’s a structured approach to debug and resolve these Laravel deployment issues:

1. Deep Dive into Environment Variables and Caching

• Ensure .env is Correctly Loaded: Even if you "think" they're correct, verify these points:
  • Is the .env file actually present in the root directory of your Laravel application on the server?
  • Permissions: The .env file should typically have permissions like 644 or 640, and be owned by the web server user (e.g., www-data or nginx).
  • Absolute Paths for DB_HOST: Sometimes, localhost resolves differently depending on the system's hosts file. Try explicitly setting DB_HOST=127.0.0.1 instead of localhost.
• Configuration Caching: You ran php artisan config:clear, which is good. However, if you've previously run php artisan config:cache, Laravel will ignore your .env file changes and use the cached configuration.
  • Always run php artisan config:clear first.
  • Then, if you want to optimize for production, run php artisan config:cache. But during debugging, it's safer to avoid caching the configuration until everything works.
  • Also, clear the application cache: php artisan cache:clear and php artisan view:clear.

2. PHP Modules and FPM Configuration

• PHP MySQL Extension: Your PHP environment needs the correct MySQL extension.
  • For modern PHP versions, this is usually php-mysql (or php-pdo_mysql).
  • Check if it's installed and enabled for the specific PHP version your web server (Nginx/Apache) is using with FPM. You can verify this by creating a phpinfo.php file (e.g., <?php phpinfo(); ?>) in your public directory and accessing it via browser. Look for a 'mysql' or 'pdo_mysql' section.
  • If missing, install it: sudo apt install php8.x-mysql (replace 8.x with your PHP version) and restart PHP-FPM (e.g., sudo systemctl restart php8.x-fpm).
• PHP-FPM Environment Variables: This is a common culprit. PHP-FPM pools don't always inherit environment variables directly from the shell where you run commands.
  • Check your PHP-FPM pool configuration file (e.g., /etc/php/8.x/fpm/pool.d/www.conf or similar).
  • Look for lines like env[DB_HOST] = 127.0.0.1. If you're explicitly setting variables here, ensure they match your .env or are overridden. Generally, it's better to let Laravel read its own .env, but FPM can sometimes interfere.
  • Ensure clear_env = no is set in your FPM pool config if you want FPM to inherit environment variables from the server. However, this is less secure and less common in modern setups. Laravel should read its own .env.

3. File Permissions and Ownership

• Storage Directory: Laravel needs write access to its storage and bootstrap/cache directories.
  • Run these commands from your Laravel project root:

    sudo chown -R www-data:www-data storage bootstrap/cache
    sudo chmod -R 775 storage bootstrap/cache

  • Replace www-data with your web server user if it's different (e.g., nginx for Nginx on some systems).

4. Network and Firewall

• Database Server Firewall: Even if port 3306 is open on the *application* server, ensure that the *database* server (if it's a separate machine) allows connections from your application server's IP address. This is less likely if the database is on the same machine, but worth a quick check for remote DB setups.

5. Advanced Debugging

• Dump Environment Variables: Temporarily add dd(env('DB_DATABASE')); (or DB_HOST, etc.) at the very top of your config/database.php file or in a controller that's causing the error. This will show you exactly what value Laravel is seeing for that environment variable. If it's null or incorrect, you know the .env isn't being read or is being overridden.
• Check PHP Error Logs: Beyond storage/logs/laravel.log, also check the main PHP-FPM error logs (e.g., /var/log/php8.x-fpm.log) and your Nginx/Apache error logs for any related messages. They might provide clues about PHP extensions or FPM issues.

Given that you can connect via the terminal, the most common culprits are either the configuration caching, incorrect PHP module setup, or PHP-FPM not correctly passing/reading the environment variables from your .env file. Start by explicitly dumping the env() variables from within your Laravel application to confirm what it's actually using.

Ah, got it! The dd(env('DB_DATABASE')); tip sounds super useful for debugging. Could you share a quick example of where exactly in config/database.php or a controller I should put that?