Table health
5 min read
Each field group has a database table. Table health is where you see whether that table matches the field group definition, and where you repair it when something changed outside the plugin (a developer ran SQL, a migration tool dropped a column, a backup was restored partly).
Table health has three places:
Place | Where | For |
|---|---|---|
Table health panel | Group info section of a saved group | Health badge, size statistics, recreating a missing table. |
Table differences panel | Between Group info and Fields in the editor (only when there is something to show) | Missing columns, leftover columns, columns changed outside the plugin. |
Unregistered database tables | Top of WPM Fields › Field Groups | Tables without a field group (orphan tables). |
The Table health panel
Open a saved group and expand Group info.
Item | Meaning |
|---|---|
Badge Healthy / Table missing | Whether the table exists. The editor asks the database each time you open the group. |
Total columns | All columns including system columns: |
Rows (est.) | The InnoDB estimate of the row count. It can differ slightly from |
Data size | Size of the table's data in KB or MB. |
When the table is missing
The panel says The physical database table for this field group does not exist. You can recreate it or remove this settings entry. and offers:
Button | Effect |
|---|---|
Create table | Creates an empty table from the definition. Values that were in the lost table are not restored. |
Remove the definition only | Deletes the group's definition from the settings and does not touch the database. The confirmation title is Remove the definition only, the button Remove settings. |
Saving the group also recreates a missing table. Reading a value from a group whose table is missing returns the default (empty) value instead of breaking your page, and writing a value returns false.
On the Field Groups list, such groups show the No table badge and an info line (1 field group has no database table yet. Open each group to create the table or remove the definition.). The list uses the table state the plugin remembers; the group editor checks the database itself, so open the group to refresh the real state.
The Table differences panel
The panel title carries a counter. It has up to three lists.
Missing columns
These fields are defined in settings but their columns are absent from the database table.
Action | Effect |
|---|---|
Add to DB | Creates the column (and its index and helper columns) from the field's definition. Existing rows get |
Leftover columns
These columns exist in the database but are not in the field definition. Backup columns were created automatically when a field type was changed. Leftover columns come from removed fields, removed location rules (mid, mtype), renamed sub-fields or retyped fields (backups, marked with the badge backup).
Action | Effect |
|---|---|
Import as fields (normal columns only; backup and helper columns are refused) | Adds the column to the definition as a new field. The type is guessed from the SQL type (SQL |
Remove from DB | Drops the column and its values permanently, after a confirmation. |
Changed outside the plugin
These columns exist in both settings and the database, but their SQL type has been changed directly in the database. Each row shows Settings: {type} and DB: {type}.
Action | Effect |
|---|---|
Sync to DB | Runs |
There is no "update the definition from the database" button for a changed column: change the field's SQL column options instead (see Field settings).
Unregistered database tables (orphan tables)
A table named {prefix}wpmcf_fg_* that has no field group is an orphan table. This happens when a group's definition was removed but its table stayed, or after importing a database. The list screen shows a panel: N unregistered database tables found. These tables exist in the database but have no matching field group definition. Register them to manage their data through the UI, or drop them if they are no longer needed. Each entry shows its columns and rows.
Action | Effect |
|---|---|
Register | Creates a field group from the table: one field per column (types guessed from the SQL types, system columns skipped). The label is built from the key, and location rules are empty until you set them. Open the new group to name the fields and add rules. |
Delete table | Drops the table after a confirmation (Delete database table, button Drop permanently): |
Creating a group with the key of an orphan table is refused (A database table for this key is left over from a deleted field group. Register it under Orphan tables to keep its data, or choose another key.) so no data is overwritten by accident.
Deleting a field group
See Create a field group. Deleting drops the table. If the table is already gone, the delete still removes the definition. A queued background change is discarded first.
REST reference
All routes need an administrator (manage_options).
Route | Purpose |
|---|---|
|
|
| Create the missing table. |
| Remove the definition only. |
| Add a missing column. |
| Re-apply the field's column definition. |
| Add a column as a field. |
| Drop a leftover column. |
| List unregistered tables. |
| Register a table. |
| Drop a table. |
Troubleshooting
Problem | Fix |
|---|---|
Values do not save and Settings › Health shows a database error | A column was dropped or changed outside the plugin. Open the group, use Add to DB or Sync to DB. |
The table differences panel shows | Another tool added columns. Import as fields to manage them or Remove from DB. |
A restored backup brought back an old table | Compare the Table differences panel after restoring; Sync to DB fixes types. |
After switching the database prefix groups show No table | Tables are named with the prefix. Rename the tables to the new prefix, or recreate them. |
Still stuck? Contact support