HyperDB Explained Part 1

HyperDB is a replacement for the standard WPDB class which adds the ability to use multiple databases. HyperDB supports partition of data as well as replication.

HyperDB is a plugin written by matt, andy, ryan, & mdawaffe from Automattic.     It is written primarily as a way to help larger sites manage growth as well as offers support for replication for backup and performance redundancy.     While most users will never need something like HyperDB, this tutorial has a purpose of explaining its configuration.

We might as well get this out right now….the disclaimer!

  • This tutorial was written for testing and personal purposes.
  • I make no warranty that this will work for you as all setups are generally different.
  • HyperDB is designed for larger sites to scale when one server isn’t enough and not recommended on small projects
  • Backup all data before trying it out.
  • This tutorial is not sanctioned by Automattic or the developers, but to be used as a helping guide if possible.

Now that we have that out of the way, let us continue!

The first thing you need to do is download HyperDB.   It has 3 files included.    From the readme.txt you get the following directions and should become extremely familiar with them:

Nothing goes in the plugins directory.

1. *WordPress MU only:* add this line near the top of `wp-config.php`:
`define(’WPMU’, true);`

2. Upload `db.php` to the `/wp-content/` directory. At this point, HyperDB is active. It will use the database connection constants until you complete the final steps.

3. Upload `db-settings.php` in the directory that holds `wp-config.php`

4. Edit the db settings according to the directions in that file.

5. Add this line near the top of `wp-config.php`:


Any value of `WP_USE_MULTIPLE_DB` will be ignored by HyperDB. If you wish to switch off multiple DB, remove the ‘require’ statement from step 5.

As you can see, it is pretty straight forward except for step 4 ;) That is what we are going to talk about today.    I suggest that you do step 4 first using my example and then the other steps in order, but it is up to you.   In my example I am going to demonstrate how you can use HyperDB to split up your wp_users table so that you can share your users with another install.   In our PART 2, we will discuss some of the more advanced issues of HyperDB, but this is just to get you familiar with working with it.

For documentation purposes, I am going to have the following assumptions:

  1. Your IP Address of your server is and your mySQL is on the standard port
  2. You have 2 databases:   1) blog 2) users
  3. Your Database username is “wp-user” for both databases
  4. Your Database password is “wp-password” for both databases


This is the main and only configuration file required to run HyperDB.     The first thing you should notice is that line 57 is there so your install works with the readme.txt before getting to step 4.     Since we are starting on step 4, we need to comment it out right away.

// add_db_server(’global’, 0,    ”, 1, 1,                        DB_HOST,                        DB_HOST,    DB_NAME,     DB_USER,     DB_PASSWORD);

I like to copy line 61 and place it just below that previously commented out line.    This is the one that we are going to edit for our first database, “blog”.   This is the line we should copy across before we edit it.

add_db_server(’global’, 0, ‘nyc’, 1, 1,’′,’global.mysql.example.lan:3509′,’global-db’,’globaluser’,’globalpassword’);

This is where we tell HyperDB where and what our server really is.     There are some things in that configuration that can be configured for more advanced purposes, but will remain the same in this discussion.    For example, “nyc” is the New York Data center.    This is important for replication (discussed later), but not now.   Here is the configuration using our assumptions earlier and our data center we will just call “fun” :)

add_db_server(’global’, 0, ‘fun’, 1, 1,’′,’localhost’,’blog’,’wp-user’,’wp-password’);

This tells HyperDB that we are going to have all calls (reads and writes) going to this global database unless we specify otherwise.   It is calling the IP address of our database server, since we don’t have a fancy DNS for our database setup and just localhost for the same reason.   If your host has some DNS entries setup, then you will have to adjust accordingly.

Now that we have defined our main database, we are going to add the following line below our previous one for our second database that houses our users.   *If you haven’t already, copy the wp_users table into the “users” database*

add_db_server(’users’, 0, ‘fun’, 1, 1,’′,’localhost’,’users’,’wp-user’,’wp-password’);

This tells HyperDB that we have a second database setup and that we are going to have calls to it.    We haven’t told it yet what we are going to call, but that is next.   You can also copy the wp_usermeta table as well and set it up if you want the same user roles in the second blog.    I want that on a blog by blog basis, so I only am using the wp_users table.

On line 97 there is the following line:

// add_db_table(’misc’, ‘bbq_sauces’);

We are going to make sure that below this line we setup our calls to our second database, “users”.   In our example, we are adding the following lines to call the users  information from our second database:

add_db_table(’users’, ‘wp_users’);

That should be all we need to do.    Now complete the rest of the steps in the readme.txt file including copying this db-settings.php file we created to the same directory as wp-config.php, edit wp-config.php to have the following in it near the top of the file:


Finally, copy db.php to your /wp-content/ directory.     Everything should be working correctly at this point.    If you find it isn’t, just comment out the require that we just did in wp-config.php, rename db.php to db.txt and double check all your settings.   When I say comment out, I mean:

// require(’db-settings.php’);

This concludes our PART 1 series on HyperDB configuration.    As you can see, you could have a second install of WP or WPMU using HyperDB and tell it to use the second “users” database and completely share users!    In PART 2 we will discuss replication and configuring other plugins like Buddypress to have its tables in a database for itself.


  1. Christian Louboutin Pumps
    2014/06/19 at 13:52 · Reply

    Hurrah, that’s what I was looking for, what a
    data! existing here at this weblog, thanks admin of this site.

  2. Jenn
    2016/05/11 at 08:16 · Reply

    HyperDB is a very advanced database class that replaces a few of the WordPress built-in database functions.

Leave a Reply

Your email address will not be published. Required fields are marked *