How to Update an ACF Field Name Without Losing the Data

Are you using ACF (Advanced Custom Fields) and need to change a field name, but worry you will lose all your data?

You are right to be cautious — ACF uses the field name as the meta key to save and retrieve data. But changing it is possible, and in 2026 you have more options than ever. In this guide, I will walk you through the safest method using ACF built-in rename feature (version 6+), the manual database migration via SQL, a PHP function approach for developers, and how to handle special cases like Repeater fields and Options pages.

The Easy Way: ACF Built-in Field Rename (Version 6+)

If you are running ACF version 6.0 or later, there is good news — ACF added a built-in field rename feature that handles most of the work for you.

How to rename a field in ACF 6+:

1. Go to Custom Fields → Field Groups
2. Edit the field group containing your field
3. Click on the field you want to rename
4. Find the Field Name input and change it
5. ACF will automatically migrate the meta data in the database

Behind the scenes, ACF runs the same kind of database migration we are about to do manually. But having it built-in means fewer mistakes and no SQL required. Important: The rename feature only works when both the old and new field names are different. If you try to rename a field to the same name, nothing happens.

Does ACF handle all field types?

ACF rename feature handles most field types, including text, textarea, number, email, url, select, checkbox, radio, button group, true/false, toggle, date picker, date time picker, user, post object, and taxonomy. For complex field types like Repeater, Flexible Content, and Clone, ACF 6+ will attempt migration but results can vary depending on the field structure. Always backup before renaming these field types.

Manual Database Migration (The Original Method)

Sometimes you need to do this manually — maybe you are on an older ACF version, or you are renaming a field in a custom integration where ACF UI will not help. Here is how to manually migrate your ACF field data with SQL.

Step 1: Backup Your Database

Before running any database scripts, take a full backup. You can use UpdraftPlus, phpMyAdmin export, or WP-CLI with wp db export backup.sql. Do not skip this step.

Step 2: Find Your Field Reference Key

ACF stores fields with two types of meta keys in the database: the field name (e.g., video_url) and an underscore prefix with the ACF reference key (e.g., _video_url → field_abc123). Run this SQL to find your reference key:

SELECT * FROM wp_postmeta
WHERE meta_key = 'your_old_field_name'
LIMIT 5;

Look for a row where meta_key is exactly your_old_field_name. The meta_value is what your field currently stores. Then find the reference key:

SELECT * FROM wp_postmeta
WHERE meta_key = '_your_old_field_name';

The meta_value in that row is your reference key (e.g., field_5af0d933478b4).

Step 3: Update the Meta Keys

Replace the old field name with the new one throughout your database:

UPDATE wp_postmeta as m
JOIN wp_posts as p ON m.post_id = p.ID
SET m.meta_key = 'new_field_name'
WHERE m.meta_key = 'old_field_name'
AND p.post_type = 'your_post_type';

This updates the visible field values. You also need to update the reference key record:

UPDATE wp_postmeta as m
JOIN wp_posts as p ON m.post_id = p.ID
SET m.meta_key = '_new_field_name'
WHERE meta_value = 'your_reference_key'
AND p.post_type = 'your_post_type';

Step 4: Update ACF Field Group Settings

The SQL updates your saved data, but you also need to tell ACF about the new field name in the field group settings. If you are not comfortable editing the database directly, use ACF UI to recreate the field with the new name.

The PHP Function Approach (For Developers)

If you want to automate this in code (useful for migrations or WP-CLI scripts), you can use a PHP function approach:

/**
 * Migrate ACF field name and preserve all data
 *
 * @param string $old_field_name The current field name
 * @param string $new_field_name The desired new field name
 * @param string $post_type The post type to update
 * @return int Number of posts updated
 */
function migrate_acf_field_name($old_field_name, $new_field_name, $post_type = 'post') {
    global $wpdb;

    // Update meta_key for the field values
    $result = $wpdb->query($wpdb->prepare(
        "UPDATE {$wpdb->postmeta} as m
         JOIN {$wpdb->posts} as p ON m.post_id = p.ID
         SET m.meta_key = %s
         WHERE m.meta_key = %s
         AND p.post_type = %s",
        $new_field_name,
        $old_field_name,
        $post_type
    ));

    // Update the underscore reference key
    $wpdb->query($wpdb->prepare(
        "UPDATE {$wpdb->postmeta}
         SET meta_key = %s
         WHERE meta_value = %s
         AND meta_key LIKE %s",
        '_' . $new_field_name,
        'field_' . $old_field_name,
        '\_%'
    ));

    return $result;
}

Note: This is a simplified version. You will need to adjust the reference key lookup to match your specific ACF field group key format.

Special Cases

Repeater Fields

Renaming a Repeater field is more complex because it has a nested structure. Each row and sub-field creates multiple database records. For Repeater fields, ACF 6+ handles the migration, but if you are doing it manually, you will need to update the main repeater field meta key, all the _field_{name} reference keys, and the row index meta keys (e.g., {field_name}_0, {field_name}_1). If you have a repeater with many rows, the safest approach is to use ACF export/import feature: export the field group, edit the XML to rename the field, then reimport.

Options Pages

If your field is on an Options page, the migration is similar but the post_type is different. Options page data typically uses option as the post_type in the meta table queries, or uses wp_options:

-- For options page fields:
UPDATE wp_options
SET meta_key = REPLACE(meta_key, 'old_field_name', 'new_field_name')
WHERE meta_key LIKE '%old_field_name%';

Check your ACF Options page settings to see how it stores data — some use wp_postmeta with special post IDs, others use wp_options.

Block JSON / ACF Blocks

If you are using ACF with block JSON registrations, you will also need to update the block definition files. The block name property in the block.json must match your ACF field name:

{
    "name": "acf/your-new-field-name",
    "title": "Your Field",
    "category": "design",
    "apiVersion": 3,
    "fields": [
        {
            "name": "new_field_name",
            "label": "New Field Name",
            "type": "text"
        }
    ]
}

How to Verify the Migration Worked

After running your migration, verify the data transferred correctly.

Check the database:

SELECT meta_key, COUNT(*) as count
FROM wp_postmeta
WHERE meta_key IN ('new_field_name', '_new_field_name')
GROUP BY meta_key;

Check a post in the admin: Edit a post that should have data in the renamed field and verify the field shows the correct saved value.

Use WP-CLI to verify:

wp post meta list 123 --fields=meta_key,meta_value | grep new_field_name

Replace 123 with a post ID you know has data in this field.

Nathan Kinkead

Blogger, expert WordPress developer, and developer of the awesome bbPress Voting plugin which is a must-have plugin for any bbPress forum.

Download bbPress Voting for free on the WordPress Plugin Directory.