ClickHouse DB::Exception: Wrong DDL renaming settings

The "DB::Exception: Wrong DDL renaming settings" error in ClickHouse occurs when a RESTORE command includes an invalid or malformed rename mapping. The WRONG_DDL_RENAMING_SETTINGS error code signals that ClickHouse cannot parse or apply the rename rules specified in the RESTORE statement, preventing the restore operation from proceeding.

Impact

A failed RESTORE operation means the backup data cannot be loaded into the target database or table. This can delay disaster recovery procedures, migration workflows, or environment provisioning that depends on restoring from backup. No data is modified when this error occurs -- the restore is aborted before any changes are applied.

Common Causes

Incorrect syntax in the SETTINGS rename_after_processing or rename mapping clause of the RESTORE command
Specifying a rename mapping that references a database or table not present in the backup
Mapping the same source to multiple destinations or creating circular rename rules
Using incompatible rename rules, such as renaming a database while also renaming individual tables within it in conflicting ways
Typographical errors in database or table names within the rename mapping
Version mismatch between the ClickHouse server performing the restore and the one that created the backup, leading to unsupported rename syntax

Troubleshooting and Resolution Steps

Review the exact error message to identify which part of the rename mapping is invalid. The message typically points to the problematic rule or setting.

Verify the rename syntax in your RESTORE command. A correct rename mapping looks like:

RESTORE TABLE my_db.my_table AS my_db.new_table_name
FROM Disk('backups', 'my_backup');

Check that the source databases and tables specified in your rename mapping actually exist in the backup:
```
SELECT * FROM system.backups WHERE name = 'my_backup';
```
Ensure there are no conflicting rename rules. For example, avoid renaming a database and simultaneously renaming tables within that database to a different database:
```
-- Avoid conflicting rules like these together:
RESTORE DATABASE db1 AS db2,
       TABLE db1.table1 AS db3.table1
FROM Disk('backups', 'my_backup');
```
If restoring across ClickHouse versions, confirm the RESTORE syntax you are using is supported in your server version by consulting the documentation for your specific release.
Simplify the RESTORE command by removing rename mappings entirely and restoring to the original names first. Then use RENAME TABLE statements afterward to achieve the desired naming.

Best Practices

Test RESTORE commands with rename mappings in a staging environment before running them in production.
Keep rename mappings simple and avoid combining database-level and table-level renames in the same RESTORE statement.
Document backup contents so operators know which databases and tables are available for restore and renaming.
Use consistent ClickHouse versions for backup and restore operations whenever possible.
Validate RESTORE syntax against the ClickHouse documentation for your version before executing.

Frequently Asked Questions

Q: Can I rename both a database and its tables during a single RESTORE?
A: Yes, but the mappings must be consistent. If you rename the database, table references should use the new database name. Conflicting or overlapping rules trigger the WRONG_DDL_RENAMING_SETTINGS error.

Q: Does this error cause any partial restore or data corruption?
A: No. ClickHouse validates the rename mappings before starting the actual restore. If the validation fails, no data is written.

Q: How do I list the contents of a backup to verify what can be renamed?
A: You can query system.backups for metadata, or attempt a dry-run restore to see what objects are included in the backup.

Q: Is the rename mapping syntax the same across all ClickHouse versions?
A: The core syntax has been stable, but newer versions may support additional options. Always check the release notes if you are restoring across versions.