Drupal – Change the Database Connection in Drupal’s Settings.php

The settings.php file in Drupal is actually a very short and simple file with just a few settings, but they are critical settings.

If you’re new to Drupal and moving or updating, it’s very important to understand what this file does. Misconfiguration here causes error messages, failed sites, and page not found problems that can be easily remedied if you know where to look

One such problem that comes up frequently is a missing or improper data base connection. In this tutorial, we’re going to show you where to find it and how to configure or change it.

Step #1. Locate the settings.php file

Change the Database Connection in Drupal's Settings.php

The settings.php file is located in your drupal directory under sites/default/settings.php.

This is a special file that is created during the installation process. It doesn’t exist until you create it. The System copies the default.setttings.php file and rewrites it using the configuration data you entered during set up.

Notice that the permissions are set to 444. You will not be able to make any changes to this file until you reset the permissions to 644.

This is initially very frustrating for beginners because you cannot CHMOD this file until you CHMOD the parent directory, which is default

Step #2. CHMOD the parent directory then the file to be writable

Change the Database Connection in Drupal's Settings.php
  • CHMOD the “default” directory to 755.
  • Open the folder
  • CHMOD the settings.php file to 644

Be sure to change them back to the original permissions – 555 for the default folder and 444 for the settings.php when you are done. Leaving these files with writable permissions is a security risk.

Step #3. Download the original settings.php file

Change the Database Connection in Drupal's Settings.php

It’s just good practice to always save the original version of any file you are going to change. It’s just too easy to make a mistake and forget what you did. Always have the original so you can restore it to the last working copy.

Tip. I always use the word ORIGINAL, in case I make more than one change. Then after I make the first change, I save a backup copy as settings_v1.php. After the second change, I save that one as settings_v2.php and so on. Making as few changes per version as practical. That way you won’t always have to go back to the beginning, and you’ll know what your last working version was if you have to take a step back.

Step #4. Open the settings.php with a text editor


When you open the file, you will see that it looks to be quite long. Most of this is instructions and comments on how to use the file itself. Above you see the section inside settings.php that describes the setup for the data base connection. Notice that it’s all one color, and every line is preceded with an asterisk “*”.

The asterisk renders the line invisible to the parser, so that nothing in the line is is actually used or activated..

If you don’t have a good script editor, here is a free, open source editor you can download. The image above is from the this script editor.

With an actual script editor, you will see line numbers and color formatting for the code making it much easier to modify a script. You can use MS Notepad, but don’t use Word Pad or a word processor of any kind. They insert things like line endings and formatting that will not work in a php script.


The actual database array is way down at line 180. The script editor provides the color coding making it much easier to see and read.

Step #5. Change the array to point to your database

  • Type the new data base name between the single quotes.
  • Type the data base user name between the single quotes
  • Type the new password between the single quotes
  • Only change the prefix if this data base is using a different prefix than the original. If this is a copy of another database, the prefix will remain the same.

The database prefix is similar to a tag. All the data that starts out with the prefix drpl1 (in this example) will be related. If you had two sites sharing a database, the second site would have a different prefix (tag), like drpl2. Those would be related and would never get mixed with anything labeled drpl1.

Step #6. Upload your changes

  • Upload and overwrite the file on the server.
  • CHMOD the file back to 444
  • CHMOD the directory “default” back to 555.

I used an FTP program to make these changes for demonstration purposes and also to introduce you to a script editor. You could make these same changes using the file manager on your server hosting control panel, and whatever built in editing tools it provides. The procedure is the same: CHMOD the directory and file, make the changes, CHMOD back to the original.

This is how you make the changes. The settings.php file itself contains a wealth of information in the comments. If your a beginner it’s well worth the effort to at least scan the file and find out what types of things it controls. If you’re not a beginner, all the instructions are there to refresh your memory.