Ledger migration strategy when creating a new ledger segment

[gurtajkhatra]

I've been reading through the Formance documentation and was curious about more specifics about this "Segmentation strategies" section: https://docs.formance.com/modules/ledger/advanced-topics/architecting-for-scale#segmentation-strategies

When creating a new segment for a time period, what would the strategy be for migrating old balances that are still relevant from the previous ledger to the new ledger segment while still being able to read and write transactions (i.e without downtime)?

My current thinking was to just iterate through accounts that are worth migrating the the new ledger but is there a way to do this in an atomic way? Alternatively is there a better recommended approach?

[aalloiteau]

Hi @gurtajkhatra , thanks for your question

For horizontal scalability, segmentation is indeed the recommended approach.

A common pattern is to segment ledgers by time period (for example, creating a separate ledger per year). To maintain continuous balance processing without gaps, the ending balances from the previous ledger are migrated into the new one. This effectively starts a new immutable log while ensuring clean separation between time-segmented ledgers.

Once segmented, historical data remains accessible only within the older ledgers—queries against the new ledger will not include past transactions by design.

After iterating over the relevant accounts, you can leverage the _bulk endpoint with the atomic parameter to batch the migration actions. Initializing balances in the new ledger is then simply a matter of creating transactions from a designated source account (e.g., world or a more explicit account such as ledger:2025:balance:update, configured with overdraft to the target accounts user:xxx:main, with amounts matching the balances being carried forward.