b2-migration

B2 Migration

When to use

• The user asks to migrate objects from another object store, filesystem, bucket, prefix, or account into B2.
• The user asks for a B2-to-B2 copy, re-keying plan, storage layout change, or cutover checklist.
• The user needs validation evidence before switching an application to B2.

Byte path

• Object data MUST move directly between the client or workload runner and B2 using presigned URLs, multipart upload URLs, or an external B2/S3 client.
• MUST NOT route object data through the model or MCP server. MCP coordinates inventory, destination checks, presigned write URLs, copy metadata, and validation only.
• Use worker-side S3/B2 clients, direct B2-to-B2 copy where applicable, or multipart presigned uploads for large objects. Keep source credentials and object payloads outside chat.

Safety gates

• Pause and ask for explicit confirmation before minting write-capable bearer URLs with s3_get_presigned_url using operation: "PutObject".
• Pause and ask for explicit confirmation before s3_copy_object overwrites any destination key found during collision discovery; exclusive destination ownership is not overwrite approval.
• Pause and ask for explicit confirmation before s3_complete_multipart_upload would complete into an existing destination key in a reused prefix; exclusive destination ownership is not overwrite approval.
• Pause and ask for explicit confirmation before overwrite, delete, lifecycle, public-access, or retention-weakening work. Do not combine migration and cleanup in one approval.
• Treat migration cutover as a production change: confirm owner, rollback, freeze window, validation threshold, and DNS or application config changes before action.

Tools used

• b2_list_buckets
• s3_head_bucket
• s3_list_objects_v2
• s3_head_object
• s3_copy_object
• s3_get_presigned_url
• s3_create_multipart_upload
• s3_get_presigned_upload_part_url
• s3_complete_multipart_upload
• s3_list_parts

Playbook

1. Capture scope: source, destination bucket and prefix, object count, estimated bytes, metadata preservation, Object Lock requirements, encryption expectations, cutover deadline, and destination ownership model. Require a unique staging prefix by default. Reuse a visible destination prefix only when the user confirms exclusive write ownership for the whole transfer; pre-listing cannot atomically enforce fail-on-collision.
2. Create a durable migration manifest outside chat with source key, destination key, size, checksum if available, metadata, copy or upload mode, status, retry count, continuation cursor, multipart upload ID, completed parts, and validation checkpoint.
3. Verify destination reachability with b2_list_buckets and s3_head_bucket. List existing destination keys with s3_list_objects_v2 only for planning and collision discovery before any write URL is minted; use pages of at most 1,000 keys, persist continuation tokens, and show at most 50 sampled rows in chat. Do not treat this listing as a create-if-absent guarantee.
4. Choose transfer mode. Use s3_copy_object for applicable B2/S3-compatible server-side copy paths only after collision discovery is complete; for a reused exclusively owned prefix, pause for explicit confirmation before copying any key whose destination already exists or whose overwrite status is uncertain. Use s3_get_presigned_url for simple direct uploads and multipart tools for large objects, persisting upload IDs, part numbers, ETags, and completed-part checkpoints. In a reused prefix, check the destination key and pause for collision-specific overwrite approval before s3_complete_multipart_upload; otherwise limit multipart destinations to the unique staging prefix.
5. Bound retry behavior in the migration worker: exponential backoff with jitter, a declared retry limit per object, and a stop condition that writes failed keys to the manifest instead of looping indefinitely.
6. Require confirmation before write-capable presigned URL batches. Keep URLs short-lived and hand them only to the migration worker that will PUT directly to B2.
7. Resume after restart from the manifest: skip validated objects, continue incomplete multipart uploads from saved state, retry failed objects within the approved limit, and write only inside the unique staging prefix or the confirmed exclusively-owned destination prefix.
8. Validate by sampling and summarizing s3_head_object metadata, object counts, sizes, checksums where available, and application-level probes. Do not read object bodies into the model.
9. Plan cutover in phases: initial sync, delta sync, freeze, final validation, completed-manifest checkpoint, application switch, read-only observation, rollback window, and deferred cleanup. Cutover only proceeds from a completed validation checkpoint.
10. Close with a migration report: transferred count, skipped count, failed keys, validation method, manifest location, cutover status, and cleanup tasks that still require a separate approval.