Skip to content

feat(ledger): add setting to disable alone-in-bucket query optimization #478

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
sylr merged 1 commit into from
Jun 11, 2026
Merged

feat(ledger): add setting to disable alone-in-bucket query optimization #478

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 18 additions & 0 deletions docs/04-Modules/03-Ledger.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,24 @@ spec:
value: strict
```

### Disable Ledger Scope Optimization

By default, the Ledger skips the `ledger = ?` predicate on read queries when a
ledger is the only one in its bucket (the "alone-in-bucket" optimization). Set
this to `true` to always emit the predicate, as a performance/safety escape
hatch:

```yaml
apiVersion: formance.com/v1beta1
kind: Settings
metadata:
name: ledger-disable-ledger-scope-optimization
spec:
stacks: ["*"]
key: ledger.disable-ledger-scope-optimization
value: "true"
```

## Worker Settings (v2.3+)

Starting with Ledger v2.3, a separate worker process is deployed alongside the main Ledger API. The worker can be configured using the Settings CRD.
Expand Down
1 change: 1 addition & 0 deletions docs/09-Configuration reference/01-Settings.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,7 @@ While we have some basic types (string, number, bool ...), we also have some com
| ledger.experimental-numscript-flags | Array | experimental-overdraft-function experimental-get-asset-function experimental-get-amount-function experimental-oneof experimental-account-interpolation experimental-mid-script-function-call experimental-asset-colors | Enable numscript interpreter flags |
| ledger.experimental-exporters | Bool | true | Enable new exporters feature |
| ledger.schema-enforcement-mode | String | strict | Schema enforcement mode for the Ledger (v2.4+) |
| ledger.disable-ledger-scope-optimization | Bool | true | Always emit the `ledger = ?` predicate on read queries, disabling the alone-in-bucket optimization that skips it when a ledger is the only one in its bucket |
| ledger.worker.async-block-hasher | Map | max-block-size=1000, schedule="0 * * * * *" | Configure async block hasher for the Ledger worker (v2.3+). Fields: `max-block-size`, `schedule` |
| ledger.worker.bucket-cleanup | Map | retention-period=720h, schedule="0 0 * * *" | Configure bucket cleanup for the Ledger worker (v2.4+). Fields: `retention-period`, `schedule` |
| ledger.worker.pipelines | Map | pull-interval=5s, push-retry-period=10s, sync-period=1m, logs-page-size=100 | Configure pipelines for the Ledger worker (v2.3+). Fields: `pull-interval`, `push-retry-period`, `sync-period`, `logs-page-size` |
Expand Down
19 changes: 13 additions & 6 deletions docs/09-Configuration reference/settings.catalog.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -383,12 +383,19 @@
"internal/resources/ledgers/deployments.go:87"
]
},
{
"key": "ledger.disable-ledger-scope-optimization",
"valueType": "bool",
"sources": [
"internal/resources/ledgers/deployments.go:139"
]
},
{
"key": "ledger.experimental-exporters",
"valueType": "bool",
"sources": [
"internal/resources/ledgers/deployments.go:149",
"internal/resources/ledgers/deployments.go:264"
"internal/resources/ledgers/deployments.go:157",
"internal/resources/ledgers/deployments.go:272"
]
},
{
Expand Down Expand Up @@ -417,7 +424,7 @@
"valueType": "string",
"sources": [
"internal/resources/ledgers/deployments.go:131",
"internal/resources/ledgers/deployments.go:239"
"internal/resources/ledgers/deployments.go:247"
]
},
{
Expand All @@ -435,7 +442,7 @@
}
],
"sources": [
"internal/resources/ledgers/deployments.go:209"
"internal/resources/ledgers/deployments.go:217"
]
},
{
Expand All @@ -453,7 +460,7 @@
}
],
"sources": [
"internal/resources/ledgers/deployments.go:248"
"internal/resources/ledgers/deployments.go:256"
]
},
{
Expand All @@ -479,7 +486,7 @@
}
],
"sources": [
"internal/resources/ledgers/deployments.go:221"
"internal/resources/ledgers/deployments.go:229"
]
},
{
Expand Down
8 changes: 8 additions & 0 deletions internal/resources/ledgers/deployments.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -136,6 +136,14 @@ func installLedgerStateless(ctx core.Context, stack *v1beta1.Stack, ledger *v1be
container.Env = append(container.Env, core.Env("SCHEMA_ENFORCEMENT_MODE", schemaEnforcementMode))
}

disableLedgerScopeOptimization, err := settings.GetBoolOrFalse(ctx, stack.Name, "ledger", "disable-ledger-scope-optimization")
if err != nil {
return fmt.Errorf("failed to get disable ledger scope optimization setting: %w", err)
}
if disableLedgerScopeOptimization {
container.Env = append(container.Env, core.Env("DISABLE_LEDGER_SCOPE_OPTIMIZATION", "true"))
}

err = setCommonAPIContainerConfiguration(ctx, stack, ledger, imageConfiguration, database, &container)
if err != nil {
return err
Expand Down