How to correctly add a table to the WordPress MySQL database

Firstly I would try to avoid the use of a custom table using custom post types, custom taxonomies and post/user/term meta. This will greatly increase compatibility and give you a large chunk of free functionality, such as UIs, import/export support, archives, REST APIs, etc

But assuming you cannot use that, for whatever reason, you should:

  • Use the database prefix in your table names where possible. Aside from consistency, some people use a single database for multiple installations, and this scenario will fail if you always use the same table name
  • Use dbDelta to create and update your table. The syntax and input of this function is extremely strict so be careful to follow the instructions to the letter. It’s tempting to do it via a wpdb query but don’t!
  • Use a wpdb object to make your queries. There’s the global wpdb object, but you can create your own if you need to use a different user/pass or connect to a remote server. A lot of people will use mysql_connect etc, this is bad
  • If for whatever reason dbDelta and wpdb are not going to cut it ( rare ), use PDO/mysqli or an ORM library. That this is necessary is very unlikely and improbable.
  • WordPress does not need to be told about your table, and does not keep track of it, that’s entirely up to you.
  • Updates of WordPress will not change your tables, but changes to Core tables will be undone on update if the database schema changes.
  • If you’re trying to add a new form of meta ( e.g. term meta ), there are already expected table names that map into the meta APIs that you can use

For more information see the codex