Incremental reprocessing and S3 object storage (bucket storage v4 - Service v1.26.0)

[benitav]

Still a WIP. I still need to do a full human review of the documentation.

Resolves:

• [Drift] MongoDB storage version 3 promoted to stable as storage version 4 (powersync-service #776) #605
• [Drift] New S3 storage stats add per-sync-config Prometheus metrics (powersync-service #770) #603
• [Drift] New --incremental-only compact flag added; MongoDB V3 storage compaction restructured (powersync-service #752) #570

This PR documents two new Beta features planned for PowerSync Service v1.26.0:

• Incremental reprocessing
• S3 bucket storage

Both features rely on MongoDB bucket storage version 4. For self-hosted deployments, version 4 is opt-in and version 2 remains the default. The version 4 storage format is stable, but incremental reprocessing and S3 bucket storage are still Beta features.

Incremental reprocessing applies automatically to eligible Sync Streams after moving to storage version 4. S3 bucket storage also requires explicit object-store configuration.

Summary

• Explained S3 bucket storage around its main benefit: improving large initial syncs and reducing the amount of bucket data stored in and read from MongoDB.
• Clarified that this affects data moving from the PowerSync Service to clients. It does not make the initial replication from the source database into PowerSync faster.
• Clarified that S3 bucket storage extends MongoDB bucket storage rather than replacing it.
• Added a simple explanation of what remains in MongoDB, what moves to object storage, and how clients receive that data.
• Added self-hosted configuration, provider guidance, timeout behavior, monitoring, cleanup, and teardown information.
• Explained incremental reprocessing using the “change one stream, keep the others” mental model.
• Documented its benefits: shorter Sync Config deployments, less source database processing, and fewer repeated client downloads.
• Documented when PowerSync can reuse prepared data and when it must perform a full reprocess.
• Clarified what clients download after incremental and full reprocessing.
• Covered custom checkpoints, replication logs, compacting, defragmenting, and storage growth during deployments.
• Updated the storage-version documentation to include stable version 4 and the migration path from experimental version 3.
• Documented the new object-storage and per-Sync-Config storage metrics, including their Prometheus attributes.
• Documented the experimental compact --incremental-only option.
• Updated related architecture, configuration, compatibility, feature-status, billing, and operational guidance.
• Applied consistent “Sync Config” casing across the pages touched by this work.

Assumptions and decisions

• Storage version 4 has a stable format, while incremental reprocessing and S3 bucket storage are Beta.
• For self-hosted deployments, storage version 4 is opt-in in Service v1.26.0 and version 2 remains the default.
• PowerSync Cloud manages its storage version and bucket storage infrastructure.
• S3 bucket storage requires MongoDB as the bucket storage database.
• S3 bucket storage can be used with any supported source database, including Postgres.
• S3 bucket storage works with Sync Streams and legacy Sync Rules.
• Incremental reprocessing currently requires Sync Streams, a MongoDB source database, MongoDB bucket storage, and storage version 4.
• Incremental reprocessing has no separate feature setting. It applies automatically to eligible deployments after the first version 4 deployment has completed.
• Postgres bucket storage does not currently support storage version 4.
• Experimental storage version 3 is mentioned only as the predecessor to version 4 and as a migration case. It is not recommended for new deployments.

TODOs

• Confirm the availability and rollout of both Beta features for PowerSync Cloud instances.
• Confirm when either feature is expected to become GA.
• Confirm whether and when storage version 4 will become the default.
• Confirm plans for storage version 4 support with Postgres bucket storage.
• Confirm plans for incremental reprocessing with Postgres sources or Postgres bucket storage.

🤖 Codex assisted with tracing the PowerSync Service implementation, finding related documentation, checking technical details, and drafting the changes. A human review is still required.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
powersync	🟢 Ready	View Preview	Sep 1, 2026, 1:46 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.