docs: document array payload merging behavior with job_key

[Recursing]

Summary

Documents the undocumented array payload merging behavior when using job_key to update existing jobs.

When both the existing job's payload and the new payload are JSON arrays, Graphile Worker concatenates them rather than replacing. This enables powerful batching patterns, especially when combined with preserve_run_at for fixed batching windows.

Changes

• Add "Array payload merging" section to job-key.md with SQL example
• Add cross-reference tip in tasks.md batch jobs section
• Document the caution that non-array payloads trigger standard replace behavior

Context

I discovered this behavior while implementing a batching system using database triggers. The feature is implemented in add_jobs():

payload =
  case
  when json_typeof(jobs.payload) = 'array' and json_typeof(excluded.payload) = 'array' then
    (jobs.payload::jsonb || excluded.payload::jsonb)::json
  else
    excluded.payload
  end,

This is genuinely useful but hard to discover without reading the source code.

🤖 Generated with Claude Code

Note that the above is AI generated and I might be misunderstanding things, apologies if this is noise and thank you for this project!