fix: cap poller batch size at config limit and make cleanup/requestShutdown optional

[jumski]

The Worker class previously held a direct reference to a postgres.Sql connection and always closed it on shutdown. This coupling meant the worker unconditionally owned the SQL connection regardless of whether it was externally provided.

This change introduces a WorkerOptions interface that replaces the positional requestShutdown and sql constructor arguments. The worker now accepts an optional cleanup callback instead of a SQL instance directly, and only invokes it if one is provided. Both createFlowWorker and createQueueWorker track whether they created the SQL connection themselves (ownsSql), and only pass a cleanup callback that closes the connection when they own it. When a SQL connection is passed in via config, the worker leaves lifecycle management of that connection to the caller.

requestShutdown on PlatformAdapter is now optional, and both worker factories use optional chaining when binding it. SupabasePlatformAdapter.stopWorker wraps the worker stop call in a try/finally block so the platform-owned SQL connection is always closed even if the worker stop throws.

The batch size limit parameter in ReadWithPollPoller and StepTaskPoller is now capped at the configured batchSize using Math.min, preventing a caller from requesting more messages than the poller is configured to handle.

New tests cover the cleanup callback invocation on worker stop, the ownsSql-conditional SQL teardown behavior, the sql.end guarantee when worker stop rejects, the optional requestShutdown type contract, and the corrected batch size capping logic in both poller implementations.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 5509849

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[jumski]

• fix: cap poller batch size at config limit and make cleanup/requestShutdown optional #622 👈 (View in Graphite)
• feat: refill execution slots eagerly and add self-hosted Supabase guide #620
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[nx-cloud]

View your CI Pipeline Execution ↗ for commit 5509849

Command	Status	Duration	Result
nx test:types:health dsl	✅ Succeeded	12s	View ↗

---

☁️ Nx Cloud last updated this comment at 2026-06-03 16:33:44 UTC

[jumski]

Merge activity

• Jun 3, 4:31 PM UTC: A user started a stack merge that includes this pull request via Graphite.
• Jun 3, 4:33 PM UTC: Graphite rebased this pull request as part of a merge.
• Jun 3, 4:33 PM UTC: @jumski merged this pull request with Graphite.

[github-actions]

🚀 Production Deployment: Website

✅ Successfully deployed to production!

🔗 Production URL: https://pgflow.dev

📝 Details:

• Commit: 79c23137d181abfde78fc3951bddd9ceff5b16a0
• View Logs

Deployed at: 2026-06-03T18:33:30+02:00