작업, 크론 및 데드-레터 큐

작업은 함수에 대한 하나의 백그라운드 호출입니다. service_role 키를 사용하여 서버에서 대기열에 넣습니다.

import { createClient } from '@aurabase/aurabase-js'

const admin = createClient(process.env.AURA_URL!, process.env.AURA_SERVICE_ROLE_KEY!)

const { data: job, error } = await admin.functions.enqueueJob('send-report', {
  payload: { month: '2026-10' },
  delaySecs: 60,   // 첫 번째 시도 전에 60초를 기다립니다.
  maxAttempts: 3,  // 기본값
})

getJob(id) 또는 listJobs({ status, limit })(limit 는 1에서 500 사이, 기본값은 50)를 사용하여 작업을 다시 읽습니다. 작업에는 status, attempts, max_attempts, error 및 날짜 scheduled_at, started_at, completed_at이 있습니다.

작업은 다른 요청과 마찬가지로 함수를 호출하며 처리해야 하는 세 가지 차이점이 있습니다.

Deno.serve(async (req) => {
  const jobId = new URL(req.url).pathname.split('/').pop()
  const { month } = await req.json()
  // ...jobId를 멱등성 키로 사용하여 보고서를 작성하고 보냅니다.
  return new Response('ok')
})

실제 통화는 {"method":"JOB","path":"/jobs/d443d541-…","role":null,"userId":null,"body":"{\"items\":[\"a\",\"b\"],\"order\":42}"}에 기록되었습니다.

작업은 사용자 없이 실행됩니다. x-aura-user-id에 의존하지 마십시오. 저작물이 사용자의 것인 경우 페이로드에 사용자의 ID를 넣습니다.

pending ──claimed──▶ running ──▶ completed
   ▲                    │
   └── after 5 s ◀── failed (attempts left)
                        └──▶ dead (no attempts left)

• 작업은 한 번 이상 실행됩니다. 작업자가 실행 중에 중지하면 두 번 실행될 수 있으므로 함수를 멱등성으로 만드세요.
• 실패한 시도는 maxAttempts에 도달할 때까지 5초의 고정된 지연 후에 다시 시도됩니다. 그러면 작업은 dead입니다. 지연 및 기본 시도 횟수는 서비스 설정(JOB_RETRY_DELAY_SECS, JOB_MAX_RETRIES)입니다.
• 임대(기본적으로 450초) 후에도 여전히 running 상태인 작업은 서비스에 의해 회수됩니다.
• 완료된 작업은 기본적으로 14일 동안 보관됩니다.

동일한 실제 실행에서 존재하지 않는 함수에 대한 작업은 다음 순서를 거쳤습니다. 시도 1은 Fonction 'ghost' introuvable을 사용하여 3초에 실패하고, 시도 2는 약 9초에 실패했으며, 작업은 attempts가 max_attempts와 동일한 dead이 되었습니다.

죽은 작업은 대기열에 남아 있으며 나열되고 재시도될 수 있습니다. 이러한 경로에는 아직 SDK 메서드가 없습니다. service_role 키와 함께 HTTP를 사용하세요.

# 죽은 일자리를 나열하다
curl "$AURA_URL/v1/functions/jobs/dlq" -H "apikey: $AURA_SERVICE_ROLE_KEY"

# 작업 하나를 다시 시도하세요
curl -X POST "$AURA_URL/v1/functions/jobs/$JOB_ID/retry" -H "apikey: $AURA_SERVICE_ROLE_KEY"

# 모든 죽은 작업을 다시 시도합니다(최대 1000개).
curl -X POST "$AURA_URL/v1/functions/jobs/dlq/requeue" -H "apikey: $AURA_SERVICE_ROLE_KEY"
# → {"데이터":{"requeued":1},"meta":null}

재시도는 시도 카운터를 재설정하지 않고 작업을 pending로 되돌리므로 정확히 한 번 더 시도하고 다시 실패하면 dead로 돌아갑니다. 다시 시도하기 전에 원인을 수정하세요(예: 누락된 기능 배포).

크론 항목은 함수 자체를 호출하지 않습니다. 함수가 실행될 때마다 작업을 대기열에 넣습니다.

await admin.functions.createCronJob('nightly-cleanup', '0 3 * * *', 'cleanup', {
  payload: { dryRun: false },
})

const { data: crons } = await admin.functions.listCronJobs()
await admin.functions.deleteCronJob('nightly-cleanup') // ID가 아닌 NAME로

• 일정에는 5개 필드 (min hour day month weekday) 또는 6개 필드 (sec min hour day month weekday)가 있습니다. 5개 필드 일정은 0초 앞에 표시됩니다. */1 * * * *는 0 */1 * * * *로 저장됩니다.
• @daily와 같은 별칭은 예상 형식을 명시하는 400로 거부됩니다.
• 시간은 UTC 기준입니다.
• last_run 및 next_run은 첫 번째 실행 전까지 null입니다. 실제 실행에서는 15:40에 생성된 일정이 15:41:00에 실행된 다음 next_run 15:42:00을 표시했습니다.
• 항목을 생성하면 페이로드가 고정됩니다.
• 알 수 없는 이름을 삭제하면 404가 반환됩니다. 크론 항목을 삭제하면 실행도 중지됩니다.
• SDK에는 getCronJob 또는 updateCronJob이 없습니다. 항목을 삭제하고 다시 만드십시오.

순수한 데이터베이스 작업의 경우 Postgres pg_cron 확장은 함수에 대한 왕복을 방지합니다. Cron 페이지를 참조하세요.