feat: add queue management handlers

[ferhatelmas]

What kind of change does this PR introduce?

feat

What is the current behavior?

Manual queue management under load while jumping between systems.

What is the new behavior?

Admin app attaches endpoints for listing, backup and restore.
Add a client to attach it via npm scripts.

Additional context

Kind of playbook automation/ease of use.
Disabled orioledb for restore due to targetless on conflict incompatibility, that support isn't really needed.

[coveralls]

Coverage Report for CI Build 29583752771

Coverage increased (+0.4%) to 79.932%

Details

• Coverage increased (+0.4%) from the base build.
• Patch coverage: 29 uncovered changes across 6 files (283 of 312 lines covered, 90.71%).
• 17 coverage regressions across 1 file.

Uncovered Changes

File	Changed	Covered	%
src/internal/database/pg-connection.ts	33	22	66.67%
src/internal/queue/overflow.ts	114	108	94.74%
src/scripts/jobs-client.ts	96	90	93.75%
src/http/routes/admin/queue.ts	35	31	88.57%
src/config.ts	2	1	50.0%
src/internal/queue/database.ts	3	2	66.67%
Total (11 files)	312	283	90.71%

Coverage Regressions

17 previously-covered lines in 1 file lost coverage.

File	Lines Losing Coverage	Coverage
src/internal/http/agent.ts	17	32.56%

---

Coverage Stats

Relevant Lines:	13021
Covered Lines:	10860
Line Coverage:	83.4%
Relevant Branches:	7594
Covered Branches:	5618
Branch Coverage:	73.98%
Branches in Coverage %:	Yes
Coverage Strength:	418.62 hits per line

---

💛 - Coveralls

[Copilot]

Pull request overview

This PR adds admin-facing queue overflow management capabilities for pg-boss “created” job backlogs, along with an operator CLI (npm scripts) to list backlog hotspots, archive (“backup”) created jobs into an overflow table, and restore them in controlled batches.

Changes:

• Added QueueOverflowStorePg with SQL-backed list/count/backup/restore operations and associated unit/integration tests.
• Exposed new admin endpoints under /queue/overflow, /queue/overflow/count, /queue/overflow/backup, and /queue/overflow/restore with request schemas and disconnect-aware abort handling.
• Added an operator CLI (jobs-client.ts) + docs and wired npm scripts; refactored pprof-client.ts to reuse shared integer parsers.

Reviewed changes

Copilot reviewed 23 out of 23 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
src/test/admin-queue-overflow.test.ts	Integration coverage for admin queue overflow routes against a real pg-boss schema/tables.
src/scripts/README.md	Operator documentation for the jobs CLI and endpoint semantics.
src/scripts/pprof-client.ts	Reuses shared integer parsing helpers from @internal/parser.
src/scripts/jobs-client.ts	New CLI for listing/backing up/restoring created-job overflow via the admin API.
src/scripts/jobs-client.test.ts	Unit tests for CLI config parsing, request building, and restore throttling/backoff behavior.
src/internal/queue/queue.ts	Moves PG_BOSS_SCHEMA to constants and types Queue.getDb() as QueueDB.
src/internal/queue/overflow.ts	New queue overflow store implementing list/count/backup/restore with transactional + advisory-lock semantics.
src/internal/queue/overflow.test.ts	Unit tests validating filter normalization, SQL shapes, transaction/abort behavior, and move/restore semantics.
src/internal/queue/index.ts	Exports the new overflow module from the queue package.
src/internal/queue/database.ts	Adds beginTransaction() to QueueDB to support transactional maintenance operations.
src/internal/queue/constants.ts	Adds PG_BOSS_SCHEMA constant to shared queue constants.
src/internal/parser/string-list.ts	New helpers for normalizing string lists and parsing comma-separated env/query values.
src/internal/parser/string-list.test.ts	Tests for list normalization and comma-separated parsing behavior.
src/internal/parser/integer.ts	New strict integer parsers for non-negative and positive safe integers.
src/internal/parser/integer.test.ts	Tests for integer parsing strictness and bounds.
src/internal/parser/index.ts	Barrel export for new parser utilities.
src/internal/parser/boolean.ts	New strict optional-boolean parser used by the jobs CLI.
src/internal/parser/boolean.test.ts	Tests for optional-boolean parsing behavior.
src/internal/database/pg-connection.ts	Extends beginTransaction options to include abort signals; adds signal-aware pool checkout helper.
src/internal/database/pg-connection.test.ts	Tests for signal-aware transaction checkout and late-client release behavior.
src/http/routes/admin/queue.ts	Adds admin endpoints + JSON schemas for queue overflow list/count/backup/restore routes.
src/http/routes/admin/queue.test.ts	Ensures config initialization order for existing admin queue route tests.
package.json	Adds npm scripts for the jobs CLI (list/backup/restore).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 23 out of 23 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 26 out of 26 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 26 out of 26 changed files in this pull request and generated no new comments.

[fenos]

I'm worried that this function might caused some race conditions.
For example what if we abort the signal while a query is still ongoing and we call release?

It might create some issue. I'm not super confident that having an abort signal on acquisition when the signal can't be passed down to connect (which i'm not sure is cancellable)

[ferhatelmas]

Yes, it isn't cancelable. I wanted to add here exactly because queue connection timeout is unbounded (for this case - incident, better to fail fast). Ideally, we should set it to a reasonable value but I didn't want to change it since it's operationally bigger, instead capped here so that we can retry.

For the case (running query and release), ownership is transferred and as usual, connection will be destroyed.

Also, added two new tests in the last commit for more confidence

[Copilot]

Pull request overview

Copilot reviewed 27 out of 27 changed files in this pull request and generated 1 comment.