Change the Database Connection in Drupal’s Settings.php

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.


  • Steve Burge

    Steve is the founder of OSTraining. Originally from the UK, he now lives in Sarasota in the USA. Steve's work straddles the line between teaching and web development.

0 0 votes
Blog Rating
Notify of
Newest Most Voted
Inline Feedbacks
View all comments

Excellent, clear instructions. Thanksalot


What about the local host? I’m trying to migrate a local drupal install to a Godaddy hosted site and have created a database through them. Do I use that database hostname for the host? Do you have an example of what that would look like?


Excellent, clear instructions.



Thanks! I was wondering why the changes I made to the settings.php file weren’t working – I had to change the file permissions to 644. Very helpful!


It’s good !!


my settings.php file does not show that db connection part. I use opigno. Can’t figure out which file to look.


Your humble servant !

Lechi Rlk

one day my drupal site work fine but now display Error establishing a database connection how to fix please help me


Hi Lechi,
We would love to help you with this. Could you sign up for one of our affordable support plans at [url=]…[/url] ?


hi steve its very helpfull thanks for sharing.. i have a very small question that how i can use an external database with drupal webforms.. i mean i have another database created in mysql and i want to connect this database with drupal webforms.i want to use this external database with webforms only. thanks


So here we are, more than 8 years after you wrote this, and it was still helpful! I needed to add Trusted Host Patterns to settings.php on Hostinger and your quick and excellent guide was a tremendous help. Not sure if you are still active after eight years, but thanks!


Thanks so much!  Very happy to have been useful to you.  Yes, we are still active! Keep your eye out for our new blog posts that happen weekly.  Thanks again for taking the time to comment. We appreciate you.


Ottimo, ma che succede quando cambiando server la cartella cambia da var/www/cartellasito a web/ in un server condiviso con drupal 8? Non ho assistenza per cui mi devo arrangiare da solo e non saprei dove metter mani. Ho impostato il settings.php con i dati giusti… ma continuo a vedere la pagina di default di apache. Grazie in anticipo per qualsiasi consiglio

TRANSLATION:  Great, but what happens when changing server the folder changes from var / www / site folder to web / in a server shared with drupal 8? I have no assistance for which I have to fend for myself and I don’t know where to put my hands. I set the settings.php with the right data … but I keep seeing the default apache page. Thanks in advance for any advice


Hi Paolo,
Unfortunately, that’s not a database issue but a server issue.  In Drupal 7’s settings.php file there was a setting for $base_url.  This was removed in Drupal 8 for security reasons.  Please take a look at this article: The solution depends on your server. 

I hope this helps.


Excellent instructions. Nicely done!

Would love your thoughts, please comment.x