HyperDB is a very advanced database class that replaces a few of the WordPress built-in database functions. The main differences are:
* HyperDB can be connect to an arbitrary number of database servers,
* HyperDB inspects each query to determine the appropriate database.

It supports:

  • Read and write servers (replication)
  • Configurable priority for reading and writing
  • Local and remote datacenters
  • Private and public networks
  • Different tables on different databases/hosts
  • Smart post-write master reads
  • Failover for downed host
  • Advanced statistics for profiling
  • WordPress Multisite

It is based on the code currently used in production on WordPress.com with many MySQL servers spanning multiple datacenters.


Nothing goes in the plugins directory.

  1. Enter a configuration in db-config.php.

  2. Deploy db-config.php in the directory that holds wp-config.php. This may be the WordPress root or one level above. It may also be anywhere else the web server can see it; in this case, define DB_CONFIG_FILE in wp-config.php.

  3. Deploy db.php to the /wp-content/ directory. Simply placing this file activates it. To deactivate it, move it from that location or move the config file.

Any value of WP_USE_MULTIPLE_DB will be ignored by HyperDB.


What can I do with HyperDB that I can’t do with WPDB?

WordPress.com, the most complex HyperDB installation, manages millions of tables spanning thousands of databases. Dynamic configuration logic allows HyperDB to compute the location of tables by querying a central database. Custom scripts constantly balance database server resources by migrating tables and updating their locations in the central database.

Stretch your imagination. You could create a dynamic configuration using persistent caching to gather intelligence about the state of the network. The only constant is the name of the configuration file. The rest, as they say, is PHP.

How does HyperDB support replication?

HyperDB does not provide replication services. That is done by configuring MySQL servers for replication. HyperDB can then be configured to use these servers appropriately, e.g. by connecting to master servers to perform write queries.

How does HyperDB support load balancing?

HyperDB randomly selects database connections from priority groups that you configure. The most advantageous connections are tried first. Thus you can optimize your configuration for network topology, hardware capability, or any other scheme you invent.

How does HyperDB support failover?

Failover describes how HyperDB deals with connection failures. When HyperDB fails to connect to one database, it tries to connect to another database that holds the same data. If replication hasn’t been set up, HyperDB tries reconnecting a few times before giving up.

How does HyperDB support partitioning?

HyperDB allows tables to be placed in arbitrary databases. It can use callbacks you write to compute the appropriate database for a given query. Thus you can partition your site’s data according to your own scheme and configure HyperDB accordingly.

Is there any advantage to using HyperDB with just one database server?

None that has been measured. HyperDB does at least try again before giving up connecting, so it might help in cases where the web server is momentarily unable to connect to the database server.

One way HyperDB differs from WPDB is that HyperDB does not attempt to connect to a database until a query is made. Thus a site with sufficiently aggressive persistent caching could remain read-only accessible despite the database becoming unreachable.

What if all database servers for a dataset go down?

Since HyperDB attempts a connection only when a query is made, your WordPress installation will not kill the site with a database error, but will let the code decide what to do next on an unsuccessful query. If you want to do something different, like setting a custom error page or kill the site, you need to define the ‘db_connection_error’ callback in your db-config.php.


5 0512 October 0512 000000 2020
We use this with AWS RDS and read replicas. Please keep maintaining and keep up the great work.
2 0217 October 0217 000000 2020
Maybe this plugin is not so popular because many WordPress users are just not technical users, but I truly glad the plugin is here, and hopefully the WordPress team still always have a time to maintenance this 🙂 Kudos!
10 1053 June 1053 000000 2020
Plugin seems outdated. And before anyone goes "Can you even read? You didnt follow the readme" yes I did. So to recap - Downloaded the .zip on separate machine - Unpacked - Opened Readme - Opened db-config and according to the db-config itself, it uses the definitions from wp-config.php, so actually according to the file no changes is technically required. - moved db.config.php into root web directory next to wp-config. - moved db.php into wp-content. -- Attempted first-time install (page appeared) On step=2 there are tons of WordPress Database errors indicating "bad default value" for pretty much everything. Therefore unable to first-time login as Admin, as the admin user was not successfully put into the DB by HyperDB itself. The db.config contained a singular configured DB (localhost) and yes, both read/write as 1. Wordpress works excellently when the plugin is taken out and these insert errors only appears when db.php and db.config is present in their corresponding folders. Somewhat likely the plugin here is outdated for the newer versions of WordPress/Mysql.
13 1325 August 1325 000000 2018
This plugin works as described and perfectly for my AWS Aurora Writer/Reader setup.
21 2118 May 2118 000000 2018
I have followed all the steps mentioned in the installation. But plugins never activates logging me out from wp-admin. Deserves 0 stars.
Read all 13 reviews

Contributors & Developers

“HyperDB” is open source software. The following people have contributed to this plugin.


Translate “HyperDB” into your language.

Interested in development?

Browse the code, check out the SVN repository, or subscribe to the development log by RSS.



  • Support for fallback master connections
  • Add support for marking servers read-only
  • Fix the issue when do_action() is not available
  • Use APCu to cache the results of server responsiveness
  • Add support for the utf8mb4 server capability


  • Add support for information_schema and transactions
  • Requires WordPress 4.2 for wpdb::get_table_from_query()


  • Add support for MYSQL_CLIENT_FLAGS which was added to wpdb in [21609]
  • Fix PHP 7.3 Notice


  • Fix WordPress 4.8.3 SQLi vulnerability
  • Add action for SQL logging
  • Never db_connect for SELECT FOUND_ROWS()
  • Better cleanup when disconnecing db connections


  • Additional logging for HyperDB failures and do not save “null” queries.


  • Improved failed query tracking


  • PHP7 compatability
  • MySQLi support
  • Allow utf8mb4 character set


  • Extended callbacks functionality
  • Added connection error callback
  • Added replication lag detection support


  • Removed support for WPMU and BackPress.
  • New class with inheritance: hyperdb extends wpdb.
  • New instantiation scheme: $wpdb = new hyperdb(); then include config. No more $db_* globals.
  • New configuration file name (db-config.php) and logic for locating it. (ABSPATH, dirname(ABSPATH), or pre-defined)
  • Added fallback to wpdb in case database config not found.
  • Renamed servers to databases in config in an attempt to reduce ambiguity.
  • Added config interface functions to hyperdb: add_database, add_table, add_callback.
  • Refactored db_server array to simplify finding a server.
  • Removed native support for datacenters and partitions. The same effects are accomplished by read/write parameters and dataset names.
  • Removed preg pattern support from $db_tables. Use callbacks instead.
  • Removed delay between connection retries and avoid immediate retry of same server when others are available to try.
  • Added connection stats.
  • Added save_query_callback for custom debug logging.
  • Refined SRTM granularity. Now only send reads to masters when the written table is involved.
  • Improved connection reuse logic and added mysql_ping to recover from “server has gone away”.
  • Added min_tries to configure the minimum number of connection attempts before bailing.
  • Added WPDB_PATH constant. Define this if you’d rather not use ABSPATH . WPINC . ‘/wp-db.php’.