WordPress gives you a flexible data model out of the box. Posts, post meta, terms, users, user meta and options can represent almost anything, and most plugins should use them. They come with caching, the REST API, revisions, admin interfaces and a huge ecosystem of tools.
But flexibility has limits. I’ve worked on plugins storing millions of log entries, booking slots, analytics events or product price histories in post meta, and the result was predictable: bloated tables, slow queries and an admin that crawled. For high-volume, structured data that’s queried in specific ways, a custom table is often the right tool.
Here’s when custom tables make sense, and how to build them properly.
When to use custom tables
Custom tables are worth considering when:
- You store large volumes of structured records, like logs, events, transactions, bookings or analytics data.
- You filter and sort by multiple fields, which post meta handles poorly at scale.
- Records have a fixed structure with typed fields.
- The data doesn’t need WordPress post features, like revisions, the editor, permalinks or the standard admin screens.
- Write volume is high, such as recording every API call or every visit.
Stick with posts and meta when:
- Content is editorial, edited by people in the admin.
- You need permalinks, templates, revisions or REST endpoints for free.
- Volumes are modest.
- Other plugins need to interact with the data through standard WordPress functions.
A good rule: if you’d naturally describe the data as “content”, use posts. If you’d describe it as “records” or “rows”, consider a custom table.
Designing the table
Plan the schema carefully:
- A primary key, usually an auto-incrementing ID.
- Typed columns: integers for IDs and counts, decimals for money, datetimes for timestamps and appropriately sized strings for text.
- Indexes on columns you filter or sort by frequently.
- Foreign key columns referencing WordPress objects, like post_id or user_id, indexed for lookups.
For example, a table recording product price history:
- id: primary key.
- product_id: indexed.
- price: decimal.
- currency: short string.
- recorded_at: datetime, indexed.
Think about the queries you’ll run, and design indexes for them. Avoid indexing everything; each index adds overhead to writes and uses storage.
Creating the table with dbDelta
WordPress provides dbDelta, a function that creates tables and updates their structure when the schema changes. It’s in wp-admin/includes/upgrade.php.
dbDelta’s strict formatting rules
dbDelta parses SQL in a particular way, and small formatting differences cause it to fail silently or repeatedly try to alter tables:
- Put each field on its own line.
- Use two spaces between PRIMARY KEY and the column definition.
- Use KEY rather than INDEX.
- Give keys a name.
- Use lowercase data types consistently, and avoid unusual SQL syntax.
- Don’t use backticks around field names.
These rules feel odd, but following them avoids frustrating bugs.
Use the table prefix and charset
Always use $wpdb->prefix, so your table respects the site’s configured prefix and works on Multisite. Use $wpdb->get_charset_collate() so the table uses the same character set and collation as WordPress.
Versioning the schema
Your table structure will change over time. Track the schema version in an option, and run upgrades when the plugin’s version is newer:
Activation hooks don’t run when a plugin is updated automatically, so checking the version on plugins_loaded ensures upgrades happen. dbDelta adds new columns and indexes, but it won’t drop columns or rename them. For those changes, write explicit migration code, with backups and careful testing.
For large tables, schema changes can take time and lock tables. Run heavy migrations in the background or through WP-CLI, rather than during a normal page load.
Inserting, updating and deleting
Use $wpdb’s helper methods, which prepare values safely:
The format arrays tell WordPress the data types. Check return values: these methods return false on errors, and $wpdb->last_error contains the error message.
Store timestamps in UTC, as in the example with current_time and the GMT flag, and convert to local time for display. Mixing time zones causes subtle bugs.
Querying safely
Always use $wpdb->prepare for queries with variables:
Table names can’t be passed as placeholders in older WordPress versions. Build them from $wpdb->prefix and a fixed string, never from user input. Recent WordPress versions also support the %i placeholder for identifiers.
Caching
Custom tables don’t benefit from WordPress’s post and meta caches automatically. Add caching for frequently read data using the object cache API:
Invalidate the cache when you insert or update relevant rows.
Multisite considerations
On Multisite, $wpdb->prefix includes the site ID, so each site gets its own table. Decide whether your data should be per site or network-wide. For network-wide data, use $wpdb->base_prefix. When the plugin is network-activated, you may need to create tables for each site, and for new sites created later, using the appropriate hook for site creation.
Cleaning up on uninstall
When your plugin is deleted, remove its tables and options in uninstall.php:
Some plugins offer a setting to keep data on uninstall, which is considerate for users who might reinstall later. Leaving abandoned tables behind is a common cause of database clutter.
Data retention
High-volume tables, like logs and events, grow forever unless you prune them. Schedule a cleanup task that removes old records based on a retention period, and consider privacy obligations for personal data.
Exposing data through the REST API
Custom tables aren’t available through the REST API automatically. If you need API access, register custom routes with proper permission checks and argument validation.
A real example
One booking plugin I took over stored every time slot as a post with half a dozen meta fields. With several years of bookings, the posts and postmeta tables held hundreds of thousands of rows, and checking availability for a single day ran slow meta queries across all of them. The admin was painfully slow, and the front-end availability calendar sometimes timed out.
We migrated bookings into a custom table with typed columns and indexes on the date, resource and status fields. Availability checks became simple indexed queries returning in milliseconds. The posts table shrank dramatically, which made the rest of the site faster too. The migration ran in batches through a WP-CLI command over a quiet evening, with a full backup beforehand and a verification step comparing counts afterwards.
The decision to use posts had made sense when the plugin started small. It stopped making sense as data grew. Choosing the right storage early saves a painful migration later.
Admin interfaces for custom tables
Because custom table data doesn’t appear in standard admin screens, plan how administrators will view and manage it. The WP_List_Table class, used throughout WordPress’s own admin, provides sortable columns, pagination, bulk actions and search. Build list screens with proper capability checks and nonces on any actions that change data.
Exporting and privacy
If your table holds personal data, integrate with WordPress’s privacy tools by registering a personal data exporter and eraser. That way, when a user requests their data or asks for deletion, your plugin’s records are included automatically.
Plan for scale from the start
When designing a custom table, estimate how many rows it will hold in a year or two, and which queries will run most often. Design indexes for those queries, plan retention for old data and consider partitioning or archiving strategies for truly huge tables. A little foresight prevents the slow, painful migrations that come from tables outgrowing their original design.
Document the schema
Keep a short description of each custom table in your plugin’s developer documentation: what it stores, what each column means and which indexes exist and why. Future maintainers, including you, will need it when queries change or performance problems appear.
Good documentation keeps custom tables maintainable for years.
Frequently asked questions
Are custom tables bad practice in WordPress?
No. They’re the right tool for high-volume, structured data. They’re inappropriate for content that fits naturally in posts.
Why does dbDelta keep altering my table?
Usually because the SQL formatting doesn’t match what dbDelta expects. Follow its formatting rules exactly.
Do I need to create tables on every page load?
No. Create them on activation and check the schema version on plugin load, running dbDelta only when the version changes.
How do I make custom table data appear in the admin?
Build an admin screen, often with the WP_List_Table class, which provides sortable, paginated tables similar to core admin screens.
Final thoughts
Custom tables are a powerful option for plugins handling large volumes of structured data. Use them when posts and meta would strain, design schemas around your queries, create and upgrade tables with dbDelta following its rules, version your schema, use $wpdb helpers and prepared queries, add caching, handle Multisite thoughtfully, prune old data and clean up on uninstall. Done properly, custom tables keep both your plugin and the sites using it fast.




