Register custom table for WP to use in a plugin

Question

I am trying to add a custom table handler to $wpdb.

public function __construct() {
    $this->register_tables();
}

public function register_tables() {
    global $wpdb;

    $wpdb->tables[] = 'my_new_tablename';
}

public function testing() {
    global $wpdb;
    wp_die($wpdb->my_new_tablename);
}

But when running the testing() method, I realize that $wpdb->my_new_tablename is not defined.

How may I register my own table name and make it available at $wpdb->my_new_tablename, just like as if it was a native WP table?

Answer 1

That's not what the $tables variable does, and there is no such thing as a registered custom table. These variables are an internal API not intended for plugin/theme developer use. The $wpdb->mytable pattern itself is just something someone did because they wanted to avoid prefixing manually that caught on in early WordPress articles.

The reason your code in particular doesn't work is because it's called after the set_prefix/set_blog_id methods are called by core that sets those variables. Most people get around this with $wpdb->mytable = $wpdb->prefix . 'mytable'; which is actually what set_prefix and set_blog_id do internally.

These functions are called by wp_set_wpdb_vars which is marked as private, internal, and not for plugin or theme developer use. It runs in wp-load.php which means that getting your code to work would require moving it into WordPress core itself and to a very early point in the load processs.

https://developer.wordpress.org/reference/functions/wp_set_wpdb_vars/

---

However, what you are trying to do is bad practice and not a good thing to do. Instead, consider one of the following options:

• a function that returns the table name with the prefix
• a wrapper object that has methods such as insert/update/delete that abstracts away the SQL queries to simplify your code
• a constant or define
• a custom post type

I would suggest option 1 as you already have an object, $this->table or $this->table_name() would be simpler, and more in line with OOP. It's even fewer characters to type.

Generally, custom post types are colloquially held up as a reliable/fast way to speed up WordPress, but unless you know how to structure your tables carefully and add the appropriate indexes this is no guarantee it will be faster, and could actually be much slower. Most speed improvements are not gained because a custom table was used, but because posts are no longer being filtered/searched by post meta via meta_query.

Unless you need to integrate with a non-WordPress database table/application or have exceptionally unique data storage requirements that require specialist data and querying ( e.g. searching geodata by radius, large directed graphs ), custom tables are rarely appropriate or the best use of developer time in a WP site.