schemaTemplateParam should mark schema replacement as Stable: true to enable Replacer cache

[IgorDeo]

Hey folks! We've been tracking down a memory leak in our production Go service that uses River v0.33+ with riverpgxv5, and we traced it back to the sqlctemplate.Replacer cache never being used for schema replacements.

What's happening

The schemaTemplateParam function in riverpgxv5 passes Stable: false (the default) on the schema replacement:

// riverdriver/riverpgxv5/river_pgx_v5_driver.go
func schemaTemplateParam(ctx context.Context, schema string) context.Context {
    return sqlctemplate.WithReplacements(ctx, map[string]sqlctemplate.Replacement{
        "schema": {Value: schema},  // Stable defaults to false
    }, nil)
}

Because of this, replacerCacheKeyFrom always returns cacheEligible = false, and ReplaceAllStringFunc runs on every single query — even though the schema value never changes for the lifetime of a River client.

The caching mechanism from #802 exists and works correctly, it's just never activated because Stable isn't set.

Impact we observed

We run River in two deployments (an API that enqueues jobs and a worker that processes them). After profiling with go tool pprof in production:

• Worker (runs river.Start() with continuous polling): regexp.ReplaceAllStringFunc grew +29MB in 16 minutes, accounting for 99% of all memory growth
• API (insert-only client): regexp.ReplaceAllStringFunc grew +16.9MB in 20 minutes, accounting for 89% of all memory growth

The strings allocated by the regex are short-lived but under production throughput, the allocation rate outpaces GC and downstream consumers (like pgx tracers or OTel span attributes) can hold references long enough for the memory to accumulate.

We confirmed the fix by patching schemaTemplateParam locally via a go.mod replace directive — after deploying with Stable: true, memory graphs in our monitoring flatlined.

Suggested fix

One-line change in schemaTemplateParam:

"schema": {Value: schema, Stable: true},

The same applies to the ColumnExists method which also passes a schema replacement without Stable.

The schema value is derived from the client's config and is constant for the lifetime of the River client — it's the textbook case for Stable: true.

This wouldn't affect queries that use dynamic replacements like where_clause and order_by_clause (e.g., JobList, JobDeleteMany) — those correctly remain uncached since their replacements don't set Stable.

Environment

• River: v0.33.0 (also confirmed on v0.35.1)
• riverpgxv5
• Go 1.26.2
• pgx v5.9.2

Happy to open a PR if you'd like!

Screenshot of our pods in sandbox environment before and after the fix

[brandur]

Thanks for the report Igor!

If you want to open a PR, that'd be great. (And if you do, can you please sign our CLA over at https://github.com/riverqueue/rivercla.)

I need to take a quick look at this when I get home to make sure there wasn't some reason we couldn't set Stable there, but hopefully it's just an oversight.

One question: you said there was a memory leak at the top. Although this looks like an inefficient/unnecessarily frantic use of memory, it doesn't look like a leak if I'm reading this right. Is there a memory leak somewhere else, or was this just a liberal use of the term.

[IgorDeo]

You're right, "memory leak" was a liberal use of the term. There's no permanent retention of the strings. What we observed is the repeated regex allocations creating enough GC pressure that, under production throughput combined with a heavier pgx tracer, the heap growth outpaced collection and looked like a leak in our monitoring. The Stable: true fix eliminated the symptom entirely by caching the output.

Happy to open the PR. I'll sign the CLA. Since the schema value comes from the client config and is constant for the client's lifetime, setting Stable: true on schemaTemplateParam (and the schema replacement in ColumnExists) seems like the straightforward fix. Let me know if you see any reason it should be handled differently after your review.

[IgorDeo]

While working on the PR, I noticed the same missing Stable: true exists in the other drivers too:

• riverdatabasesql has it in schemaTemplateParam (line 1250) and ColumnExists (line 129).
• riversqlite has it in schemaTemplateParam (line 1683).

Same pattern in both: schema replacement without Stable, so the Replacer cache is bypassed on every query.

Is it okay to address all three drivers in the same PR? The fix is identical, just adding Stable: true to each schema replacement. I've already written tests for all three.