[Bug]Toolkit db mv may delete the source database after a copy failure, causing data loss #6940

Activity

1. halibobo1205

   added

   type:bug

   on Sep 1, 2026
2. halibobo1205 commented on Sep 2, 2026

   

   halibobo1205

   on Sep 2, 2026

   Last edited by halibobo1205

   CollaboratorAuthor

   More actions

   Implementation design

   Problem addressed: The previous db mv implementation ignored per-file copy errors. It could then delete the source and link it to an incomplete destination while still printing move db done. and returning exit code 0.

   Invariant: For a stopped node with a stable, non-overlapping source/destination layout, no source database is deleted or replaced until every selected database has been copied successfully. Handled validation, copy, and finalization failures return non-zero and report what remains on disk.

   Flow:

   1. Validate before writing. ConfigConverter performs database-independent checks during option parsing. Path validation runs later in call(), after all options have their final values. It rejects a missing source, a regular-file source, a source symlink, an existing destination (including a dangling symlink), a destination equal to its source, or a destination inside any selected source. Validation failures exit with code 2 before creating any destination.
   2. Phase 1 — copy databases. Each source is walked recursively without following links. Directories are recreated, including empty directories; regular files are copied; symlinks, special entries, unreadable attributes, traversal failures, I/O errors while creating the destination or copying files, and runtime failures cause the copy to fail.
   3. Handle copy failures. allMatch prevents later databases from starting after one database fails. Within a database, entries that observe hasError are skipped, and every copy already in progress finishes before cleanup begins. The command then attempts to remove every configured destination (all were validated absent at start, so anything present was created by this run) and exits with code 1. If cleanup succeeds, the command can be retried after correcting the I/O problem. If cleanup is incomplete, it reports the remaining paths for manual removal.
   4. Phase 2 — replace sources with links. This phase starts only after every database copy succeeds. Each source is deleted and replaced with a symbolic link to its destination. Finalization continues through every selected database so that each result is reported. A deletion or link-creation failure keeps the complete destination, prints manual recovery instructions, and causes exit code 1.
   5. Report success. move db done. is printed and exit code 0 is returned only after every database has been copied and every source has been replaced with its symbolic link.

   Exit codes:

   • 0: all copy and source-to-link operations completed successfully;
   • 1: handled copy, cleanup, deletion, or link-creation failure;
   • 2: configuration or path-validation failure.

   Non-goals:

   • Detecting a running node; stopping the node remains a documented precondition.
   • Resumable copying; retries start from a clean destination after successful cleanup.
   • Validating overlapping sources or overlapping destinations; the design assumes stable, non-overlapping paths.

   Sequence Diagram

   sequenceDiagram
       autonumber
       actor Op as Operator
       participant CLI as picocli
       participant CC as ConfigConverter
       participant MV as DbMove.call()
       participant CP as Copy phase
       participant LK as Link phase
       participant FS as File system
   
       Op->>CLI: db mv -d database-dir -c config-file
       CLI->>CC: parse configuration
       Note over CC: Keep usable name/path entries,<br/>require at least one,<br/>reject duplicate names
       alt configuration invalid
           CC-->>Op: error, exit 2
       end
   
       CLI->>MV: call() after options are final
       loop each selected database
           MV->>MV: construct and validate Property
           Note over MV: Reject missing/file/symlink source,<br/>existing destination including dangling link,<br/>or destination equal to source
       end
       MV->>MV: reject any destination inside a selected source
       alt path validation fails
           MV-->>Op: error, exit 2, nothing written
       end
   
       rect rgb(232, 240, 254)
           Note over CP,FS: Phase 1 — copy databases
           loop each database until one fails
               MV->>CP: copy(database)
               CP->>FS: collect the source tree
               CP->>FS: create destination
               loop entries processed in parallel
                   CP->>CP: read attributes with NOFOLLOW_LINKS
                   alt directory
                       CP->>FS: create directory
                   else regular file
                       CP->>FS: copy file
                   else unsupported entry, I/O or runtime failure
                       CP->>CP: record failure
                   end
               end
               Note over CP: New work observing hasError is skipped,<br/>in-flight copies finish before rollback
           end
       end
   
       alt copy failed
           MV->>FS: attempt to remove the configured destinations
           alt cleanup succeeded
               MV-->>Op: sources kept, exit 1,<br/>retry after correcting the failure
           else cleanup incomplete
               MV-->>Op: sources kept, report leftovers,<br/>manual cleanup required, exit 1
           end
       end
   
       rect rgb(254, 240, 232)
           Note over LK,FS: Phase 2 — replace sources with links
           loop each selected database
               MV->>LK: replaceSourceWithLink(database)
               LK->>FS: delete source
               alt deletion failed
                   LK-->>Op: report source state,<br/>complete copy, and recovery instructions
               else source deleted
                   LK->>FS: create symbolic link
                   alt link creation failed
                       LK-->>Op: report complete copy<br/>and recovery instructions
                   end
               end
           end
       end
   
       alt any finalization failed
           MV-->>Op: exit 1
       else all operations succeeded
           MV-->>Op: print "move db done.", exit 0
       end
   

   Loading

   Design guarantees

   1. Phase 1 does not delete or replace any source database.
   2. A copy failure prevents the entire link phase from starting.
   3. A copy failure preserves every source and attempts to remove every configured destination.
   4. A cleanup failure is reported explicitly instead of claiming that the command is directly retryable.
   5. Complete destination copies are retained when finalization fails.
   6. move db done. and exit code 0 occur only after the entire migration succeeds.
   7. A destination inside any selected source is rejected before anything is written, regardless of configuration order.
3. halibobo1205 commented on Sep 3, 2026

   

   halibobo1205

   on Sep 3, 2026

   CollaboratorAuthor

   More actions

   This will be fixed by #6946.
4. halibobo1205

   added a parent issue on Sep 9, 2026

   • Tracking: prepare and manage release_v4.8.3 branch #6957
5. github-project-automation

   added this to java-tronon Sep 9, 2026
6. SeriousCoding789

   added this to the GreatVoyage-v4.8.3 milestone on Sep 21, 2026
7. halibobo1205

   removed this from the GreatVoyage-v4.8.3 milestone on Sep 24, 2026