wp-config.php: The Essential Minimum

Without programming knowledge, wp-config looks overwhelming: CHARSET, COLLATE, ABSPATH… Plus all those semicolons, brackets and dollar signs. And making a mistake can crash your site.

Perhaps you don’t have the time to read an “ultimate guide” and become a wp-config expert. You just want to get it right and out of the way. This page is for you.

Contents

What wp-config does

wp-config file is mainly about two things: configuration and security. It makes sure your website

  1. works
  2. doesn’t get hacked

What you need to do

When setting up a new WordPress website, you need to change two things in wp-config.php:

  1. Enter your database specifications
  2. Enter new security keys

There are many other settings you can change or add if you want to modify default WordPress behaviour, but these two things are alsways needed.

wp-config.php location

The file is location in the main (root) directory – the same directory where you can find subdirectories suchs as wp-content, wp-admin or wp-includes.

What if it’s missing?

If you have just downloaded WordPress and uploaded it onto your hosting account, you won’t find wp-config.php. But there (in the main directory) should be a file named wp-config-sample.php. Rename this file to wp-config.php and open it to edit.

wp-config file contents

When you first open wp-config.php, don’t be scared by the syntax. It is written in the PHP programming language. You don’t need to know programming – you just need to overwrite a few values. Just make sure you don’t accidentally delete any quotes, brackets or semicolons.

Most of the lines in wp-config.php actually do nothing. All the lines which start with /** or * are comments. They can provide valuable information about what the next piece of code does and what you should do with it.

So let’s start to edit the file.

Setting database details

A WordPress website has two main parts: the files and the database. One of the main roles of wp-config.php is to store the info where the database is located and how to access it. This information has four pieces:

  • database name
  • username
  • password
  • host (the server where the database is stored)

If you have already created the database in your hosting account, you must know its name, username and password to enter in wp-config. If you are doing wp-config first (order doesn’t matter), you will then need to use the same details when creating the database.

Database name (DB_NAME)

Find this line in your wp-config file:

define( 'DB_NAME', 'database_name_here' );

Replace database_name_here with the actual name of your WordPress database. Make sure to keep the single quotes in place.

Easy, right? Most of the other settings follow the same logic:

There is the keyword define, followed with brackets and a semicolon. In the brackets there are two items, separated by a comma and each enclosed in single quotes.

The first item is always the name of the setting, like DB_NAME. Don’t change that.

The second item is the value of the setting, which you can overwrite.

Database username (DB_USER)

define( 'DB_USER', 'username_here' );

Replace username_here with the actual MySQL username which you have configured for your database.

Database password (DB_PASSWORD)

define( 'DB_PASSWORD', 'password_here' );

Replace password_here with the actual password for the MySQL user defined above. Make it very strong – a random string of at least 15 or so characters, including uppercase and lowercase letters and digits. You don’t need to remember this password – it is NOT the password used for logging into your website. And if you forget it, you can always find it in wp-config.php.

Database host (DB_HOST)

define( 'DB_HOST', 'localhost' );

This one is a bit tricky. In most cases, you should keep the default – localhost. It means the database is stored on the same server. Less commonly, the database will be stored on a different server, and in such case you need to replace localhost with the address.

Bottom line: Unless you are sure what to put in here, keep localhost. Nothing too bad can happen if it’s wrong – the worst case is that your WordPress installation won’t complete. You can always ask you web hosting provider what to enter here.

DB_CHARSET and DB_COLLATE

There are two more database settings:

/** Database Charset to use in creating database tables. */
define( 'DB_CHARSET', 'utf8' );

/** The Database Collate type. Don't change this if in doubt. */
define( 'DB_COLLATE', '' );

DB_CHARSET sets the character set for your database – things like storing and handling accents and special language-specific characters. In most cases, the default utf8 is best (even when your site’s language has many non-english characters).

DB_COLLATE sets how your database will sort different characters (e.g. should à come before â, or vice-versa?). Again, unless you know what it is about and what value you want to enter here, keep it unchanged.

Table prefix

One last setting for your database is usually a bit further down the wp-config file and it has a different format.

$table_prefix = 'wp_';

Overwrite the wp_ with something else (keep the quotes and semicolon). What to put in here?

Generally, a WordPress database consists of several tables – there is a table for posts, for categories and tags, for comments etc. All table names start with the same few characters – e.g. wp_posts, wp_terms or wp_comments. This 'wp_' is defined in the $table_prefix setting.

You can keep wp_ and it will work.

But for security reasons, it is best to use something other than the default. It doesn’t need to be too long or cryptic – just changing it to something like wprs_ or a short version of your website’s name will do the job. You don’t need to remember it.

Authentication keys

Even more important for security is the following. The comment is self-explanatory.

/**#@+
 * Authentication Unique Keys and Salts.
 *
 * Change these to different unique phrases!
 * You can generate these using the {@link https://api.wordpress.org/secret-key/1.1/salt/ WordPress.org secret-key service}
 * You can change these at any point in time to invalidate all existing cookies. This will force all users to have to log in again.
 *
 * @since 2.6.0
 */
define( 'AUTH_KEY', 'put your unique phrase here' );
define( 'SECURE_AUTH_KEY', 'put your unique phrase here' );
define( 'LOGGED_IN_KEY', 'put your unique phrase here' );
define( 'NONCE_KEY', 'put your unique phrase here' );
define( 'AUTH_SALT', 'put your unique phrase here' );
define( 'SECURE_AUTH_SALT', 'put your unique phrase here' );
define( 'LOGGED_IN_SALT', 'put your unique phrase here' );
define( 'NONCE_SALT', 'put your unique phrase here' );

In your web browser, open the url they suggest:

https://api.wordpress.org/secret-key/1.1/salt/

You will see a page with random unique security keys generated. Copy all to your wp-config.php, replacing the existing rows from define( 'AUTH_KEY', ... to define( 'NONCE_SALT', ...

Again, obviously, you don’t need to remember these codes.

Debug mode

Another important security measure is to never use WordPress in debug mode for live websites.

define( 'WP_DEBUG', false );

Keep the default setting (false).

In the future, if you ever see a problem with your website, like a page not loading, missing parts of a page, or anything unexpected, you can temporarily set WP_DEBUG to true.

In debug mode, details about errors (such as which line of code in which file is the problem) will be displayed on the page. This can help you fix the problem, but it should never be seen by outsiders.

In short, other than for brief debugging, always keep WP_DEBUG false.

Advanced settings

Unless you are an advanced WordPress user or need some non-standard configuration, you don’t need to worry about the remaining settings.

If needed, you can find full official documentation here.

Installing WordPress

When you are done editing, save the file. If you were editing it on your local computer, upload it to WordPress root directory on the server.

If you haven’t created your database yet, do it now. Use the same database name, username and password which you have entered in wp-config.php.

When you have both wp-config and database ready, you can proceed with WordPress installation. Visit your website’s homepage (e.g. www.ozeb.com) in the browser.

If you have configured everything correctly, you should see the WordPress setup page, asking you to choose your website’s name, admin username and password. These are login details for your new website’s admin interface where you will publish and edit content – they are different from the database username and password saved in wp-config.php.

What the installation really does behind the scenes is look into wp-config.php for the database details, connect to the database and build the tables for posts, categories, tags etc. When you enter details like website name, username and password in the setup form, it will save them in the database.

Error establishing a database connection

If, instead of the setup page, you see “Error establishing a database connection”, either you have forgotten to create the database or the database details in wp-config.php don’t match the existing database. Easy to fix.

If you are sure that your database name, username and password match and still see “Error establishing a database connection”, the likely suspect is the DB_HOST setting. Ask your web hosting provider what setting to use.

Securing your wp-config file

When you have successfully completed WordPress setup, there is one more, very important step.

With all the sensitive details it contains, it is absolutely essential to protect wp-config.php from outsiders. It is easy to do – just add four lines to .htaccess, which is a file located in the same directory:

<files wp-config.php>
order allow,deny
deny from all
</files>

Make sure to add the above lines somewhere between lines

<ifmodule mod_rewrite.c>

and

</ifmodule>

If you can’t see the .htaccess file, there are two possible causes:

  1. Make sure your file brower / FTP program can display hidden files, because .htaccess is a hidden file.
  2. It may be because .htaccess has not been created yet. Log into your WordPress admin area (www.yourdomain.com/wp-admin), go to Settings, then Permalinks, and click Save. It will generate the .htaccess file, which you can then edit.