How to troubleshoot database connection problems

Draft status not available -- AWAITING PEER REVIEW
A user encounters a "database connection problem" during the Drupal installation process.

This lessons walks the user through a step-by-step databse connection troubleshooting workflow.


A working web server:

  • Is the database server running? If you're using WAMP, XAMPP, MAMP, Acquia Dev Desktop or any other type of *AMP stack that includes a control panel, ensure that the database server (usually a MySQL server) is running. This is often indicated by a red (not running) or green (running) light.
  • Did you select the correct "Database type"? If you're using an *AMP stack, the "Database type" should be set to "MySQL, MariaDB, or equivalent".
  • Did you enter the correct "Database name"? Prior to installing Drupal, an empty database must be present - the name of this empty database must match the "Database name" that is entered during Drupal's installation process.
  • Are the proper credentials supplied in the settings.php file? These settings are usually added to the settings.php file automatically via user prompts during Drupal's installation process. Ensure that the correct values were provided. These credentials are usually created during the *AMP installation process.
  • Are you connecting to the proper database port? Under most circumstances, the default database port and other settings in the "advanced options" fieldset do not need to be modified during installation unless the user specified non-default settings during the *AMP installation. A common mistake is modifying the default "advanced options" settings unnecessarily. Drupal installation, database configuration, advanced options

Lesson tags: