Background

WiredTiger makes the removal of an object's metadata durable before completing removal of its underlying data files. A drop can therefore leave files on disk that are no longer referenced by WiredTiger metadata in the following situations:

• The process crashes after the metadata removal is committed but before the data file is renamed or removed.
• Removal of the original data file fails, including when a deferred-removal rename was not used or failed.
• The data file is renamed for deferred removal, but the process crashes before that removal runs. Pending removals are tracked only in memory.
• Removal of a renamed file fails. The error is logged, the pending entry is discarded, and the failure is not returned to the drop caller.

The remaining file may retain its original name or a deferred-removal name such as <filename>.<btreeId>.wtdrop (optionally with a numeric suffix). These files can persist across restarts, consuming disk space and retaining dropped data. A successful drop return does not guarantee that physical file removal completed.

This behavior is considered by design. Applications using WiredTiger are responsible for identifying and safely removing orphaned files.

Documentation gap

The public WT_SESSION::drop documentation describes transaction rollback on failure and the remove_files option, but does not describe orphaned files or application cleanup responsibility. The schema architecture Drop section states that the method "will delete all related files and metadata entries," without qualifying this guarantee.

Proposed change

Add a high-level note to the public WT_SESSION::drop documentation and update the schema architecture Drop section consistently. Keep the failure scenarios and filename details in this ticket, not in the documentation.