Changing a field group safely

Every field is a column, so editing a saved field group changes a real database table. The plugin does this with a few safety rules so that you do not lose values by accident.

The safety rules

What each change does

After a save the plugin reports what it did. A rename shows renamed, a type change shows type: text→number, and backups show as migration_backups. For example, after converting a Text field name to Number the editor shows A type change could lose data, so the old values were copied to: name__bak. Check the converted values, then delete the backup columns under Table health.

Renaming a field

1. Change the field's Field key (SQL column name). The row warns Key rename will run SQL RENAME COLUMN.
2. Save. Values are kept.
3. Update templates, shortcodes and code that use the old key.

Through the REST API a rename is the same uid with a new key (see Create a field group).

Changing a field's type

The dialog This type change can lose data appears for risky changes. What you can lose depends on the direction:

Your three choices:

1. Cancel: nothing changes.
2. Convert with a backup: the old values go to {key}__bak first. After saving, check the converted values. When you are happy, delete the backup column under Table health › Leftover columns › Remove from DB.
3. Create a new field instead: adds a second field with the new type and leaves the old column alone. This is the recommended path when you want to migrate values by your own rules (copy them with a script, then remove the old field).

If a backup column with that name already exists, the next one is named {key}__bak_2, {key}__bak_3 and so on.

See Table health for how to review and remove backup columns.

A type change of an indexed field also clears the index if the new type cannot be indexed. If you save through the REST API, send "indexed": false yourself in that case, otherwise the database refuses (BLOB/TEXT column ... used in key specification without a key length) and nothing is changed.

Removing a field

The field leaves the editor and edit screens; its column keeps its values. The column appears in Table health under Leftover columns (Table differences panel) and in the REST schema response as orphan_columns.

From there you can:

Reusing the name of a removed field

If you add a new field whose key equals a leftover column, saving first stops with the dialog These names hold saved values:

A field you removed earlier used the same name, and its values are still in the database. Choose what the new field should do with them.

Click Save changes in the dialog to apply your choice, or Cancel to go back. (REST: the save answers 409 with code wpmcf_orphan_columns and a list of columns; resend the request with "orphan_columns": { "key": "reclaim" } or "fresh".)

Large tables

Altering a table with many rows can take longer than a web request. When the table has about 100,000 rows or more (an estimate), the change is queued and runs in the background through Action Scheduler. Changes that rewrite stored Group or Repeater values start earlier, from about 5,000 rows, because that work runs row by row in PHP. Developers can change the first threshold with the wpmcf/fields/schema_background_rows filter.

While a change is queued or running:

• The editor shows Applying database changes: This table is large, so the changes run in the background. The site uses the previous version until they finish. You can leave this page. and the card shows an Updating badge. When it finishes: The database changes are done.
• The site keeps using the previous definition until the change completes.
• Values saved meanwhile are kept and written once the change is done (renamed fields are mapped to their new columns).
• Save changes is disabled and the API answers 409 (wpmcf_schema_busy): Database changes for this field group are still being applied. Save again when they are done.
• You can cancel a queued change (not a running one) with DELETE /wpmcf/v1/field-groups/{key}/schema-job; a failed change can be dismissed the same way (the Dismiss button).

If the job fails the editor shows The last changes could not be applied with the database message, and The site still uses the previous version of this field group. A job that is still "running" after 15 minutes is treated as interrupted: The database change was interrupted before it finished. Review Table health in the field group, then save again. Action Scheduler must be able to run (WP-Cron or a real cron); see Troubleshooting.

Warnings you may see on save

Troubleshooting