diff --git a/docs/04-Modules/03-Ledger.md b/docs/04-Modules/03-Ledger.md index 9bbaea5b..2a78816e 100644 --- a/docs/04-Modules/03-Ledger.md +++ b/docs/04-Modules/03-Ledger.md @@ -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. diff --git a/docs/09-Configuration reference/01-Settings.md b/docs/09-Configuration reference/01-Settings.md index 9b798375..c744bdea 100644 --- a/docs/09-Configuration reference/01-Settings.md +++ b/docs/09-Configuration reference/01-Settings.md @@ -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` | diff --git a/docs/09-Configuration reference/settings.catalog.json b/docs/09-Configuration reference/settings.catalog.json index a4316ca8..181fdf81 100644 --- a/docs/09-Configuration reference/settings.catalog.json +++ b/docs/09-Configuration reference/settings.catalog.json @@ -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" ] }, { @@ -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" ] }, { @@ -435,7 +442,7 @@ } ], "sources": [ - "internal/resources/ledgers/deployments.go:209" + "internal/resources/ledgers/deployments.go:217" ] }, { @@ -453,7 +460,7 @@ } ], "sources": [ - "internal/resources/ledgers/deployments.go:248" + "internal/resources/ledgers/deployments.go:256" ] }, { @@ -479,7 +486,7 @@ } ], "sources": [ - "internal/resources/ledgers/deployments.go:221" + "internal/resources/ledgers/deployments.go:229" ] }, { diff --git a/internal/resources/ledgers/deployments.go b/internal/resources/ledgers/deployments.go index 2e6249c3..5345e0c4 100644 --- a/internal/resources/ledgers/deployments.go +++ b/internal/resources/ledgers/deployments.go @@ -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