MySQL Server Has Gone Away During Laravel Migration Install
When you execute php artisan migrate:install in your Laravel project directory and immediately hit a [PDOException] SQLSTATE[HY000] [2006] MySQL server has gone away, the error message is misleading. It suggests your application lost connection to the database, but in reality, the migration itself is often the culprit. The database server is terminating the active connection because the query takes too long to complete.
This specific behavior stems from a default setting in the MySQL client library known as net_read_timeout. By default, this timeout is set to 60 seconds. When you run migrate:install, Laravel attempts to create the migrations table and populate it with schema metadata. In large projects or those running on systems with heavy load, the database might be temporarily unresponsive while processing complex internal queries or cleaning up previous states. If the server hangs just past the 60-second mark, the MySQL client library assumes the connection is dead and throws HY000 [2006].
The second error, [ErrorException] PDO::__construct(): MySQL server has gone away, appears because Laravel retries the connection logic or attempts to initialize a new session immediately after detecting the failure. Both errors point to the same root cause: the operation exceeded the client-side timeout window before completing.
To resolve this without stopping your development workflow, you need to adjust the wait_timeout and interactive_timeout variables in your MySQL server configuration, or temporarily increase the client-side timeout for the specific command execution.
Adjusting Server-Side Timeouts
The most robust solution involves modifying the MySQL server's configuration files, typically found at /etc/my.cnf on Linux or my.ini on Windows. You need to add or update the following parameters in the [mysqld] section:
[mysqld]
wait_timeout=28800
interactive_timeout=28800
Setting these values to 28800 seconds (8 hours) ensures that idle connections are not dropped prematurely during long-running operations. After making these changes, you must restart the MySQL service for them to take effect:
sudo systemctl restart mysql
Once the server is restarted, run your migration command again. This approach permanently fixes the issue for all subsequent commands and is the recommended practice for production environments where migrations might take time due to large datasets.
Temporary Client-Side Workarounds
If you cannot restart the database service immediately or are working in an environment where configuration changes are restricted, you can force the migrate:install command to run with a higher timeout directly from the command line. Laravel supports passing arguments to the artisan command via the -t flag or by modifying the .env file temporarily.
However, the most direct way to bypass the default 60-second limit without changing global settings is to ensure your application environment variable DB_CONNECTION is correctly set and then explicitly adjust the timeout if your database driver supports it via configuration array. For MySQL connections managed via PDO or mysqli, you can configure the connection parameters in config/database.php:
'settings' => [
'timeout' => 28800, // Set to a higher value like 8 hours
],
Alternatively, if you are using Dockerized MySQL setups common in modern stacks, ensure that the wait_timeout is set within your docker-compose configuration:
services:
db:
image: mysql:8.0
environment:
MYSQL_DATABASE: ${DB_DATABASE}
MYSQL_ROOT_PASSWORD: ${DB_PASSWORD}
command: >
--default-time-zone=UTC
--wait_timeout=28800
--interactive_timeout=28800
Why This Happens
Understanding the mechanics helps prevent future friction. The migrate:install command performs two distinct tasks: it creates the migrations table and inserts a record into it. If the database is under heavy load from other processes (like cron jobs or CI/CD pipelines), the write operation might stall. The MySQL client sees no data arriving within the 60-second window, closes the socket, and throws the "server has gone away" exception.
By extending the timeout window, you give the server enough breathing room to process the request. This is a classic case of configuration mismatch between the client expectations and server reality. Always verify that your database server is healthy before blaming the Laravel application logic when encountering connection timeouts during schema changes.