Custom Field conversion and recovery

Follow the conversion tutorial, then use this reference for mappings and recovery. Enable compound_field_custom_field.

Check compatibility

drush compound-field:custom-field-preflight node.field_sessions --yaml
drush compound-field:custom-field-convert node.field_sessions --dry-run

Omit the field name from preflight to inspect all Custom Fields. Preflight checks configuration; the conversion dry run also checks stored values. The conversion keeps the host field's name and cardinality across all bundles sharing its storage. Each source column becomes a single-value compound sub-field. Resolve reported setting disagreements between bundles and unmapped columns. No acknowledgment flag accepts an unresolved mapping.

Source type	Destination
String, long string, telephone, email, boolean, integer, float, decimal, link, entity reference, image	Corresponding Drupal field type
File	Drupal File, adding default display and description properties
Datetime, date range	Review timezone and duration properties with no equivalent
Color, duration, time, UUID, URI, time range	No automatic equivalent preserving complete behavior
Map, map string, Viewfield	Unsupported

Command options

Option	Purpose
--compound-id	Unused compound ID; defaults to the field name without field_.
--dry-run	Check without writing.
--acknowledge	Accept the destructive rebuild; -y also answers confirmation.
--chunk-size	Rows per batch.
--capture-dir	Export affected configuration; also works with --status and --abandon.
--status	Show progress and retained source tables.
--abandon --acknowledge	Forget the conversion record after recovery; restores nothing.

Protect data and configuration

Back up the database, export configuration and stop content writers and cron. The field reads empty during part of its rebuild. Current and revision rows retain their mapped values and language coordinates. Test translations and pending drafts on a site copy.

Widget and formatter settings need reconfiguration. Review Views, search indexes and other consumers of old columns. Capture dependent configuration in a private, empty directory outside the webroot and configuration sync directory:

drush compound-field:custom-field-convert node.field_sessions --status \
  --capture-dir=/private/backups/conference-custom-field

For captured objects reported as deleted, adapt before restoring. Compare repaired objects with their live versions; leave untouched objects alone. A name-only capture needs the earlier export. Do not blindly import captures containing old columns. --capture-dir-holds-other-config bypasses directory checks, including for configuration sync, and can expose obsolete settings to a later import.

Resume or restore

Inspect --status, fix the cause and rerun the original command. Only one process can convert a field. A killed worker retains its lease for up to ten minutes after its last progress; then a rerun resumes from the saved cursor and discards unfinished chunk rows. Repeated verification failures require restoring the pre-conversion database backup.

Keep cron stopped and Custom Field installed until recovery is complete. Deleted-field purge removes retained source tables. Resume refuses missing or shortened tables that originally held rows; restore the backup. Tables recorded as originally empty may be absent. Older records without counts cannot establish that a missing table was empty.

Manual recovery requires original storage, instances, configuration and both current and revision rows. Keep all tables named by --status. After recovery, export recovery information before using --abandon --acknowledge; it removes only the conversion record. After verification, resume cron and let purge finish before uninstalling Custom Field. Recovery after purge requires the backup.