Key Remapping

Replace production primary keys and rewrite foreign keys consistently.

Replacing names and emails is not always enough. A production primary key can still identify a person if the same ID appears in logs, URLs, exports, support tickets, or external systems.

Key remapping replaces primary-key values before they reach the target and rewrites declared foreign keys to the new values.

Example

tables:
  users:
    rows:
      strategy: full
    columns:
      id:
        strategy: remapping
        arguments:
          - use: random_integer
          - foreign_keys:
              - table: orders
                column: user_id
              - table: employees
                column: manager_id
                self_referential: true
      email:
        strategy: fake
        faker_method: safeEmail
        faker_arguments: []

In this example, users.id receives new random values. orders.user_id and employees.manager_id are rewritten to point to the new IDs.

Why it matters

Key remapping helps keep the relational graph intact while reducing the risk of correlating target records back to production identifiers.

Limitations

Polymorphic relations are not supported. Key remapping only handles standard foreign keys (single table + column). If your schema uses Laravel's polymorphic relations (e.g., commentable_type + commentable_id), you must:

  • Disable foreign key checks with disable_foreign_key_checks: true, or
  • Manually handle type-based IDs after cloning

Disabling remapping

Remapping can be turned off without removing its definition — persistently in the YAML:

options:
  remap_keys: false

or for a single run:

clonio cloning:run production.cloning.yaml --target staging --no-remap-keys

--skip-remapping-keys is an alias of --no-remap-keys and keeps working in existing scripts.

--remap-keys re-enables remapping for one run when the YAML sets remap_keys: false. cloning:dump --no-remap-keys writes remap_keys: false into a new config.

This is useful when the schema has many cross-references that are not declared as foreign keys, so remapping would leave them pointing at the old IDs.

Warning: With remapping disabled, primary and foreign key values are copied from production unchanged. If those IDs can identify people (see Why it matters), the target is less anonymized. cloning:run prints a notice whenever configured remapping is skipped.

Large databases

For large mappings, use file-based mapping storage:

clonio cloning:run production.cloning.yaml --target staging --file-based

If memory is acceptable and PHP's memory limit is the blocker:

clonio cloning:run production.cloning.yaml --target staging --no-memory-limit