Give AI the upload, read, transform, delete, database-reference, authorization, CDN, worker, and infrastructure paths. Ask it to inventory the full storage contract, build a compatibility matrix for old and new reads and writes, and split the migration into prepare, copy, verify, cut over, reconcile, and retire. Copy before deleting, preserve stable object identity, verify bytes and metadata independently, and keep a measured rollback path until no production flow depends on the old store.
A File Is More Than Its Bytes
An uploaded file participates in several contracts at once. The application may store an object key in a database, construct a public URL from that key, issue a short-lived signed URL, generate thumbnails in a worker, cache the response at a CDN, scan the content, enforce an ownership rule, and delete derivatives when the original is removed. Moving only the bytes preserves just one part of that system.
The migration also happens while the product is live. A user can upload after the bulk copy has passed their key. A retry can write a derivative to the old bucket after the new reader is enabled. A cached URL can outlive the redirect that made it valid. A deletion requested during the migration can race with a copy and bring the object back. Safe migration means defining the valid combinations during that overlap and proving that creates, reads, updates, transforms, and deletes converge on one intended result.
Use AI to assemble repository evidence and expose unknowns. Do not let it invent bucket contents, object versions, retention locks, encryption settings, IAM policies, lifecycle rules, CDN behavior, egress limits, or current request traffic. Confirm those facts with provider inventory, configuration, logs, metrics, database queries, and responsible owners. Sanitize filenames, metadata, and access logs before placing samples in a prompt.
The Six-Part Migration Plan
Locate every upload endpoint, client upload flow, object-key generator, database reference, read path, signed-URL issuer, public URL builder, image or document processor, queue, delete path, restore path, cache, lifecycle rule, event notification, and administrative tool. Record the source and target inventory by object count, logical bytes, key prefix, version state, metadata, content type, ownership, encryption, retention, and accessibility. Include orphaned objects and database rows that point to missing objects rather than assuming both inventories already agree.
Write down what must stay stable and what will change: canonical object identity, key format, URL shape, cache behavior, access decision, signed-URL lifetime, metadata, encryption, transformation outputs, deletion semantics, and event delivery. State invariants such as “a private object never becomes public,” “one database record resolves to one intended object,” and “a deletion acknowledged during the migration is not reversed by the copier.” A successful copy is not enough if those behaviors change accidentally.
Evaluate old and new application versions against old and new storage paths. Decide where reads fall back, where writes land, how transforms find their source, and how deletes or replacements propagate during each phase. Prefer one authoritative write path whenever possible. If temporary dual writes are unavoidable, name the source of truth, define partial-failure handling, make operations idempotent, and reconcile differences continuously instead of assuming both writes always succeed together.
Copy rather than move. Use bounded batches with durable checkpoints, stable object identity, safe retries, rate and cost limits, and a failure ledger. Preserve required metadata explicitly; defaults can differ between stores. Record source and target evidence for each batch and make a rerun harmless. Treat multipart uploads, object versions, large files, zero-byte objects, unusual keys, and transforms as named cases—not surprises discovered after cutover.
Verify counts and logical bytes, then compare a provider-supported checksum or a freshly computed digest where feasible. Do not assume an ETag is a portable content hash. Sample reads through the real application path and test private access, signed URL expiry, cache headers, range requests, content types, transforms, upload retries, replacements, and deletion races. Shift reads and writes through explicit gates, observe a bounded cohort, and reconcile changes made after the initial copy before expanding traffic.
Keep the old store read-only or otherwise recoverable through the rollback window. Prove that no supported application version, worker, scheduled task, event subscription, CDN origin, administrative tool, or restore procedure still uses it. Check recent access logs and unresolved reconciliation failures. Then disable credentials and integrations before deleting data. Destructive cleanup is its own reviewed operation with retention, backup, legal, cost, and recovery approval—not an automatic final line in the copy script.
A Minimal Compatibility Matrix
Separate reads, writes, transforms, and deletes. A plan that covers only upload and download leaves the most damaging races undefined.
| Operation | During migration | Required rule | Proof |
|---|---|---|---|
| Read an object copied earlier | Expected | Resolve the same logical object with equivalent authorization and response metadata | Application-path read plus byte, metadata, and access comparison |
| Upload while the bulk copy runs | Expected | Write to one authority or capture the change in a replayable delta path | Upload before, during, and after a batch checkpoint |
| Delete or replace during copy | Expected | Order the mutation so stale source state cannot resurrect or overwrite the target | Controlled race test plus reconciliation result |
| Old worker creates a derivative | Prevent or support explicitly | Route the derivative to the authoritative store and preserve its parent identity | Mixed-version transform and retry test |
| Previously issued URL is requested | Policy decision | Redirect, proxy, preserve, or deliberately expire it without widening access | Public, private, cached, expired, and range-request checks |
Ask what happens when an object is copied, then deleted in the source by a live request, and then encountered again by a restarted copy batch. If the answer depends on timing or “the migration should finish quickly,” the plan needs version, tombstone, event, or reconciliation evidence that makes the final state deterministic.
Keep Object Identity Separate From Location
Database records and external clients should not need to know which provider currently holds an object. Where the existing design permits it, keep a stable application-level object ID and resolve it to a storage key or delivery URL at a boundary. If the database stores complete provider URLs, treat rewriting those rows as a separate database and API contract migration with its own compatibility window and rollback plan.
Do not casually rename keys while changing providers. A key-format change can affect authorization prefixes, cache keys, event filters, transforms, deduplication, and links embedded outside the application. If renaming is required, keep an explicit old-to-new mapping or deterministic transform and test collisions, case sensitivity, Unicode, reserved characters, and maximum key lengths before the first production batch.
Access Control Travels With the Read Path
“Private bucket” does not by itself preserve application authorization. Trace who decides whether this user may access this object, what identity reaches that decision, and whether the target can bypass it through a public URL, broad service credential, permissive CDN origin, or client-generated key. Test with two accounts and at least one unauthenticated request so ownership boundaries are proven, not inferred from the interface.
Signed URLs deserve their own compatibility decision. Existing URLs may point directly at the old provider and remain valid beyond cutover. New signatures may use a different hostname, canonical request, expiry rule, or response header. Decide whether old links are allowed to expire naturally, served through a compatibility layer, or invalidated deliberately. Never convert private objects to public merely to preserve an old URL shape.
Copy-Paste Prompt: Storage Migration Analysis
"Plan this file or object storage migration before editing files. Desired outcome: [outcome]. Upload, read, URL, database-reference, authorization, transform, queue, delete, cache/CDN, infrastructure, and observability paths: [paths]. Known source and target inventory, key format, versions, metadata, access model, encryption, retention, lifecycle, events, traffic, provider limits, and cost constraints: [evidence or unknown]. First inspect repository evidence and list runtime or provider facts that require owner confirmation. Then output: (1) complete storage contract and dependency inventory, (2) source-to-target delta for bytes, keys, metadata, URLs, access, transforms, events, lifecycle, and deletion, (3) compatibility matrix for old/new reads, writes, replacements, transforms, and deletes, (4) prepare-copy-verify-cutover-reconcile-retire phases, (5) restartable batch and checkpoint design, (6) count, logical-byte, checksum, metadata, application-path, access, cache, and race proof per phase, (7) telemetry, gates, cost limits, stop conditions, and rollback action, and (8) credential-disable and old-data removal criteria. Flag dual-write ambiguity, stale copies, object resurrection, URL breakage, permission widening, nonportable checksum assumptions, unbounded retries, hidden egress cost, and invented production facts. Do not implement or delete anything yet."
Resolve runtime unknowns before requesting a patch or copy command. Then implement the smallest reversible preparation step and review application code, infrastructure, database references, bucket policy, CDN configuration, workers, dashboards, reconciliation reports, and runbooks together. The repository rarely contains the complete storage system.
Common Failure Modes
The first is copying files once while live writes continue. The second is preserving bytes but dropping content types, cache headers, ownership metadata, or access rules. The third is assuming matching object counts prove matching content. The fourth is using an ETag as a universal checksum. The fifth is dual-writing without a source of truth or repair ledger. The sixth is forgetting deletes, replacements, derivatives, old signed URLs, and CDN caches. The seventh is removing the source as soon as new uploads appear to work.
The correction is an evidence-backed sequence: inventory the whole contract, define stable identity and invariants, make overlap explicit, copy in restartable batches, verify through independent and user-visible paths, reconcile concurrent mutations, cut over with gates, and separate credential shutdown from final data deletion.
Conclusion
AI is useful for tracing storage calls, finding embedded URLs, drafting inventory tools, generating race tests, and challenging cutover order. The safety comes from verified live state and deliberate compatibility. Treat uploaded files as durable application state whose bytes, identity, metadata, permissions, references, and lifecycle must cross the migration together.
Continue with The AI Database Migration Plan, The AI API Contract Change Plan, The AI Background Job Migration Plan, and AI Observability.